1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
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>
|
