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

       Paul Evans <leonerd@leonerd.org.uk>

perl v5.38.2                                       2024-01-20                                 Future::Queue(3pm)

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

       Returns a new "Future::Queue" instance.

       Takes the following named arguments:

       max_items => INT
           Sinceversion0.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
           Sinceverison0.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.

       Sinceversion0.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 );

       Sinceversion0.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;

       Sinceversion0.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.

       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.

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

          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" );