1Thread::Queue(3) User Contributed Perl Documentation Thread::Queue(3)
2
6 Thread::Queue - Thread-safe queues
7
9 This document describes Thread::Queue version 3.02
10
12 use strict;
13 use warnings;
14 use threads;
16 use Thread::Queue;
17 my $q = Thread::Queue->new(); # A new empty queue
19 # Worker thread
21 my $thr = threads->create(
22 sub {
23 # Thread will loop until no more work
24 while (defined(my $item = $q->dequeue())) {
25 # Do work on $item
26 ...
27 }
28 }
29 );
30 # Send work to the thread
32 $q->enqueue($item1, ...);
33 # Signal that there is no more work to be sent
34 $q->end();
35 # Join up with the thread when it finishes
36 $thr->join();
37 ...
39 # Count of items in the queue
41 my $left = $q->pending();
42 # Non-blocking dequeue
44 if (defined(my $item = $q->dequeue_nb())) {
45 # Work on $item
46 }
47 # Blocking dequeue with 5-second timeout
49 if (defined(my $item = $q->dequeue_timed(5))) {
50 # Work on $item
51 }
52 # Get the second item in the queue without dequeuing anything
54 my $item = $q->peek(1);
55 # Insert two items into the queue just behind the head
57 $q->insert(1, $item1, $item2);
58 # Extract the last two items on the queue
60 my ($item1, $item2) = $q->extract(-2, 2);
61
63 This module provides thread-safe FIFO queues that can be accessed
64 safely by any number of threads.
65 Any data types supported by threads::shared can be passed via queues:
67 Ordinary scalars
69 Array refs
70 Hash refs
71 Scalar refs
72 Objects based on the above
73 Ordinary scalars are added to queues as they are.
75 If not already thread-shared, the other complex data types will be
77 cloned (recursively, if needed, and including any "bless"ings and read-
78 only settings) into thread-shared structures before being placed onto a
79 queue.
80 For example, the following would cause Thread::Queue to create a empty,
82 shared array reference via "&shared([])", copy the elements 'foo',
83 'bar' and 'baz' from @ary into it, and then place that shared reference
84 onto the queue:
85 my @ary = qw/foo bar baz/;
87 $q->enqueue(\@ary);
88 However, for the following, the items are already shared, so their
90 references are added directly to the queue, and no cloning takes place:
91 my @ary :shared = qw/foo bar baz/;
93 $q->enqueue(\@ary);
94 my $obj = &shared({});
96 $$obj{'foo'} = 'bar';
97 $$obj{'qux'} = 99;
98 bless($obj, 'My::Class');
99 $q->enqueue($obj);
100 See "LIMITATIONS" for caveats related to passing objects via queues.
102
104 ->new()
105 Creates a new empty queue.
106 ->new(LIST)
108 Creates a new queue pre-populated with the provided list of items.
109
111 The following methods deal with queues on a FIFO basis.
112 ->enqueue(LIST)
114 Adds a list of items onto the end of the queue.
115 ->dequeue()
117 ->dequeue(COUNT)
118 Removes the requested number of items (default is 1) from the head
119 of the queue, and returns them. If the queue contains fewer than
120 the requested number of items, then the thread will be blocked
121 until the requisite number of items are available (i.e., until
122 other threads <enqueue> more items).
123 ->dequeue_nb()
125 ->dequeue_nb(COUNT)
126 Removes the requested number of items (default is 1) from the head
127 of the queue, and returns them. If the queue contains fewer than
128 the requested number of items, then it immediately (i.e., non-
129 blocking) returns whatever items there are on the queue. If the
130 queue is empty, then "undef" is returned.
131 ->dequeue_timed(TIMEOUT)
133 ->dequeue_timed(TIMEOUT, COUNT)
134 Removes the requested number of items (default is 1) from the head
135 of the queue, and returns them. If the queue contains fewer than
136 the requested number of items, then the thread will be blocked
137 until the requisite number of items are available, or until the
138 timeout is reached. If the timeout is reached, it returns whatever
139 items there are on the queue, or "undef" if the queue is empty.
140 The timeout may be a number of seconds relative to the current time
142 (e.g., 5 seconds from when the call is made), or may be an absolute
143 timeout in epoch seconds the same as would be used with
144 cond_timedwait(). Fractional seconds (e.g., 2.5 seconds) are also
145 supported (to the extent of the underlying implementation).
146 If "TIMEOUT" is missing, c<undef>, or less than or equal to 0, then
148 this call behaves the same as "dequeue_nb".
149 ->pending()
151 Returns the number of items still in the queue. Returns "undef" if
152 the queue has been ended (see below), and there are no more items
153 in the queue.
154 ->end()
156 Declares that no more items will be added to the queue.
157 All threads blocking on "dequeue()" calls will be unblocked with
159 any remaining items in the queue and/or "undef" being returned.
160 Any subsequent calls to "dequeue()" will behave like
161 "dequeue_nb()".
162 Once ended, no more items may be placed in the queue.
164
166 The following methods can be used to manipulate items anywhere in a
167 queue.
168 To prevent the contents of a queue from being modified by another
170 thread while it is being examined and/or changed, lock the queue inside
171 a local block:
172 {
174 lock($q); # Keep other threads from changing the queue's contents
175 my $item = $q->peek();
176 if ($item ...) {
177 ...
178 }
179 }
180 # Queue is now unlocked
181 ->peek()
183 ->peek(INDEX)
184 Returns an item from the queue without dequeuing anything.
185 Defaults to the the head of queue (at index position 0) if no index
186 is specified. Negative index values are supported as with arrays
187 (i.e., -1 is the end of the queue, -2 is next to last, and so on).
188 If no items exists at the specified index (i.e., the queue is
190 empty, or the index is beyond the number of items on the queue),
191 then "undef" is returned.
192 Remember, the returned item is not removed from the queue, so
194 manipulating a "peek"ed at reference affects the item on the queue.
195 ->insert(INDEX, LIST)
197 Adds the list of items to the queue at the specified index position
198 (0 is the head of the list). Any existing items at and beyond that
199 position are pushed back past the newly added items:
200 $q->enqueue(1, 2, 3, 4);
202 $q->insert(1, qw/foo bar/);
203 # Queue now contains: 1, foo, bar, 2, 3, 4
204 Specifying an index position greater than the number of items in
206 the queue just adds the list to the end.
207 Negative index positions are supported:
209 $q->enqueue(1, 2, 3, 4);
211 $q->insert(-2, qw/foo bar/);
212 # Queue now contains: 1, 2, foo, bar, 3, 4
213 Specifying a negative index position greater than the number of
215 items in the queue adds the list to the head of the queue.
216 ->extract()
218 ->extract(INDEX)
219 ->extract(INDEX, COUNT)
220 Removes and returns the specified number of items (defaults to 1)
221 from the specified index position in the queue (0 is the head of
222 the queue). When called with no arguments, "extract" operates the
223 same as "dequeue_nb".
224 This method is non-blocking, and will return only as many items as
226 are available to fulfill the request:
227 $q->enqueue(1, 2, 3, 4);
229 my $item = $q->extract(2) # Returns 3
230 # Queue now contains: 1, 2, 4
231 my @items = $q->extract(1, 3) # Returns (2, 4)
232 # Queue now contains: 1
233 Specifying an index position greater than the number of items in
235 the queue results in "undef" or an empty list being returned.
236 $q->enqueue('foo');
238 my $nada = $q->extract(3) # Returns undef
239 my @nada = $q->extract(1, 3) # Returns ()
240 Negative index positions are supported. Specifying a negative
242 index position greater than the number of items in the queue may
243 return items from the head of the queue (similar to "dequeue_nb")
244 if the count overlaps the head of the queue from the specified
245 position (i.e. if queue size + index + count is greater than zero):
246 $q->enqueue(qw/foo bar baz/);
248 my @nada = $q->extract(-6, 2); # Returns () - (3+(-6)+2) <= 0
249 my @some = $q->extract(-6, 4); # Returns (foo) - (3+(-6)+4) > 0
250 # Queue now contains: bar, baz
251 my @rest = $q->extract(-3, 4); # Returns (bar, baz) - (2+(-3)+4) > 0
252
254 Queues created by Thread::Queue can be used in both threaded and non-
255 threaded applications.
256
258 Passing objects on queues may not work if the objects' classes do not
259 support sharing. See "BUGS AND LIMITATIONS" in threads::shared for
260 more.
261 Passing array/hash refs that contain objects may not work for Perl
263 prior to 5.10.0.
264
266 Thread::Queue Discussion Forum on CPAN:
267 <http://www.cpanforum.com/dist/Thread-Queue>
268 threads, threads::shared
270 Sample code in the examples directory of this distribution on CPAN.
272
274 Jerry D. Hedden, <jdhedden AT cpan DOT org>
275
277 This program is free software; you can redistribute it and/or modify it
278 under the same terms as Perl itself.
279perl v5.16.3 2013-02-19 Thread::Queue(3)