NAME

       "Future::Queue" - a FIFO queue of values that uses Futures

SYNOPSIS

          use Future::Queue;
          use Future::AsyncAwait;

          my $queue = Future::Queue->new;

          async sub process_queue
          {
             while(1) {
                my $thing = await $queue->shift;
                ...
             }
          }

          my $f = process_queue();
          $queue->push( "a thing" );

DESCRIPTION

       Objects in this class provide a simple FIFO queue the stores arbitrary perl values. Values
       may be added into the queue using the "push" method, and retrieved from it using the
       "shift" method.

       Values may be stored within the queue object for "shift" to retrieve later, or if the
       queue is empty then the future that "shift" returns will be completed once an item becomes
       available.

CONSTRUCTOR

   new
          $queue = Future::Queue->new( %params );

       Returns a new "Future::Queue" instance.

       Takes the following named arguments:

       max_items => INT
           Since version 0.50.

           Optional. If defined, there can be at most the given number of items in the queue.
           Attempts to call "push" beyond that will yield a future that remains pending, until a
           subsequent "shift" operation makes enough space.

       prototype => STRING or OBJECT or CODE
           Since verison 0.51.

           Optional. If defined, gives either a class name, an object instance to clone or a code
           reference to invoke when a new pending "Future" instance is needed by the "shift" or
           "push" methods when they cannot complete immediately.

              $f = $prototype->();    # if CODE reference
              $f = $prototype->new;   # otherwise

           If not provided, a default of "Future" will be used.

   push
          $queue->push( @items );

          await $queue->push( @items );

       Adds more items into the queue. If the queue was previously empty and there is at least
       one "shift" future waiting, then the next one will be completed by this method.

       Since version 0.50 this can take multiple items; earlier versions can only take one value
       at once.

       This method always returns a Future instance. If "max_items" is defined then it is
       possible that this future will be in a still-pending state; indicating that there was not
       yet space in the queue to add the items. It will become completed once enough "shift"
       calls have been made to make space for them.

       If "max_items" is not defined then these instances will always be immediately complete; it
       is safe to drop or ignore it, or call the method in void context.

       If the queue has been finished then more items cannot be pushed and an exception will be
       thrown.

   shift
          $item = await $queue->shift;

       Returns a "Future" that will yield the next item from the queue. If there is already an
       item then this will be taken and the returned future will be immediate. If not, then the
       returned future will be pending, and the next "push" method will complete it.

       If the queue has been finished then the future will yield an empty list, or "undef" in
       scalar context.

       If "undef" is a valid item in your queue, make sure to test this condition carefully. For
       example:

          while( ( my $item ) = await $queue->shift ) {
             ...
          }

       Here, the "await" expression and the assignment are in list context, so the loop will
       continue to iterate while any value is assigned, even if that value is "undef". The loop
       will only stop once no items are returned, indicating the end of the queue.

   shift_atmost
          @items = await $queue->shift_atmost( $count );

       Since version 0.50.

       A bulk version of "shift" that can return multiple items at once.

       Returns a "Future" that will yield the next few items from the queue. If there is already
       at least one item in the queue then up to $count items will be taken, and the returned
       future will be immediate. If not, then the returned future will be pending and the next
       "push" method will complete it.

   finish
          $queue->finish;

       Since version 0.50.

       Marks that the queue is now finished. Once the current list of items has been exhausted,
       any further attempts to "shift" more will yield empty.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>