File Coverage

blib/lib/Piper/Role/Queue.pm

Criterion	Covered	Total	%
statement	11	11	100.0
branch			n/a
condition			n/a
subroutine	4	4	100.0
pod			n/a
total	15	15	100.0

#####################################################################
## AUTHOR: Mary Ehlers, [e-mail]
## ABSTRACT: Basic queue role used by the Piper system
#####################################################################

package Piper::Role::Queue;

use v5.10;
use strict;
use warnings;

use Moo::Role;

our $VERSION = '0.03'; # from Piper-0.03.tar.gz

#pod =head1 DESCRIPTION
#pod
#pod =for stopwords dequeued queueing
#pod
#pod The role exists to support future subclassing of L (and L such subclasses) with alternate queueing systems.
#pod
#pod =head1 REQUIRES
#pod
#pod This role requires the following object methods.
#pod
#pod =head2 dequeue($num)
#pod
#pod Removes and returns C<$num> items from the queue.
#pod
#pod Default C<$num> should be 1.  If wantarray, should return an array of items from the queue.  Otherwise, should return the last of the dequeued items (allows singleton dequeues, behaving similar to splice):
#pod
#pod   Ex:
#pod   my @results = $queue->dequeue($num);
#pod   my $single = $queue->dequeue;
#pod
#pod If requesting more items than are left in the queue, should only return the items left in the queue (and should not return Cs as placeholders).
#pod
#pod =cut

requires 'dequeue';

#pod =head2 enqueue(@items)
#pod
#pod Adds the C<@items> to the queue.  It should not matter what the C<@items> contain, within reason.
#pod
#pod =cut

requires 'enqueue';

#pod =head2 ready
#pod
#pod Returns the number of items that are ready to be dequeued.
#pod
#pod =cut

requires 'ready';

#pod =head2 requeue(@items)
#pod
#pod Inserts the C<@items> to the top of the queue in an order such that C would subsequently return C<$items[0]> and so forth.
#pod
#pod =cut

requires 'requeue';

#pod =head1 TESTING
#pod
#pod Verify the functionality of a new queue class by downloading the L tests and running the following:
#pod
#pod   PIPER_QUEUE_CLASS= prove t/01_Queue.t
#pod
#pod =cut

1;

__END__