File Coverage

blib/lib/Future/Queue.pm
Criterion Covered Total %
statement 27 27 100.0
branch 4 4 100.0
condition n/a
subroutine 7 7 100.0
pod 3 3 100.0
total 41 41 100.0


line stmt bran cond sub pod time code
1             # You may distribute under the terms of either the GNU General Public License
2             # or the Artistic License (the same terms as Perl itself)
3             #
4             # (C) Paul Evans, 2019-2022 -- leonerd@leonerd.org.uk
5              
6             package Future::Queue;
7              
8 2     2   83226 use v5.10;
  2         17  
9 2     2   9 use strict;
  2         4  
  2         50  
10 2     2   10 use warnings;
  2         4  
  2         560  
11              
12             our $VERSION = '0.49';
13              
14             =head1 NAME
15              
16             C - a FIFO queue of values that uses Ls
17              
18             =head1 SYNOPSIS
19              
20             use Future::Queue;
21              
22             my $queue = Future::Queue->new;
23              
24             my $f = repeat {
25             $queue->shift->then(sub {
26             my ( $thing ) = @_;
27             ...
28             });
29             };
30              
31             $queue->push( "a thing" );
32              
33             =head1 DESCRIPTION
34              
35             Objects in this class provide a simple FIFO queue the stores arbitrary perl
36             values. Values may be added into the queue using the L method, and
37             retrieved from it using the L method.
38              
39             Values may be stored within the queue object for C to retrieve later,
40             or if the queue is empty then the future that C returns will be
41             completed once an item becomes available.
42              
43             =cut
44              
45             =head1 CONSTRUCTOR
46              
47             =cut
48              
49             =head2 new
50              
51             $queue = Future::Queue->new
52              
53             Returns a new C instance.
54              
55             =cut
56              
57             sub new
58             {
59 2     2 1 1199 my $class = shift;
60 2         11 return bless {
61             items => [],
62             waiters => [],
63             }, $class;
64             }
65              
66             =head2 push
67              
68             $queue->push( $item )
69              
70             Adds a new item into the queue. If the queue was previously empty and there is
71             at least one C future waiting, then the next one will be completed by
72             this method.
73              
74             =cut
75              
76             sub push :method
77             {
78 2     2 1 415 my $self = shift;
79 2         5 my ( $item ) = @_;
80              
81 2         3 push @{ $self->{items} }, $item;
  2         9  
82 2 100       4 ( shift @{ $self->{waiters} } )->done if @{ $self->{waiters} };
  1         5  
  2         8  
83             }
84              
85             =head2 shift
86              
87             $item = $queue->shift->get
88              
89             Returns a C that will yield the next item from the queue. If there is
90             already an item then this will be taken and the returned future will be
91             immediate. If not, then the returned future will be pending, and the next
92             C method will complete it.
93              
94             =cut
95              
96             sub shift :method
97             {
98 2     2 1 7 my $self = shift;
99              
100 2 100       4 if( @{ $self->{items} } ) {
  2         7  
101 1         2 return Future->done( shift @{ $self->{items} } );
  1         11  
102             }
103              
104 1         2 push @{ $self->{waiters} }, my $f = Future->new;
  1         4  
105             return $f->then(sub {
106 1     1   89 return Future->done( shift @{ $self->{items} } );
  1         6  
107 1         14 });
108             }
109              
110             =head1 AUTHOR
111              
112             Paul Evans
113              
114             =cut
115              
116             0x55AA;