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>

