1Thread::Queue(3pm) Perl Programmers Reference Guide Thread::Queue(3pm)
2
6 Thread::Queue - Thread-safe queues
7
9 This document describes Thread::Queue version 2.11
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(sub {
22 while (my $item = $q->dequeue()) {
23 # Do work on $item
24 }
25 })->detach();
26 # Send work to the thread
28 $q->enqueue($item1, ...);
29 # Count of items in the queue
32 my $left = $q->pending();
33 # Non-blocking dequeue
35 if (defined(my $item = $q->dequeue_nb())) {
36 # Work on $item
37 }
38 # Get the second item in the queue without dequeuing anything
40 my $item = $q->peek(1);
41 # Insert two items into the queue just behind the head
43 $q->insert(1, $item1, $item2);
44 # Extract the last two items on the queue
46 my ($item1, $item2) = $q->extract(-2, 2);
47
49 This module provides thread-safe FIFO queues that can be accessed
50 safely by any number of threads.
51 Any data types supported by threads::shared can be passed via queues:
53 Ordinary scalars
55 Array refs
56 Hash refs
57 Scalar refs
58 Objects based on the above
59 Ordinary scalars are added to queues as they are.
61 If not already thread-shared, the other complex data types will be
63 cloned (recursively, if needed, and including any "bless"ings and read-
64 only settings) into thread-shared structures before being placed onto a
65 queue.
66 For example, the following would cause Thread::Queue to create a empty,
68 shared array reference via "&shared([])", copy the elements 'foo',
69 'bar' and 'baz' from @ary into it, and then place that shared reference
70 onto the queue:
71 my @ary = qw/foo bar baz/;
73 $q->enqueue(\@ary);
74 However, for the following, the items are already shared, so their
76 references are added directly to the queue, and no cloning takes place:
77 my @ary :shared = qw/foo bar baz/;
79 $q->enqueue(\@ary);
80 my $obj = &shared({});
82 $$obj{'foo'} = 'bar';
83 $$obj{'qux'} = 99;
84 bless($obj, 'My::Class');
85 $q->enqueue($obj);
86 See "LIMITATIONS" for caveats related to passing objects via queues.
88
90 ->new()
91 Creates a new empty queue.
92 ->new(LIST)
94 Creates a new queue pre-populated with the provided list of items.
95
97 The following methods deal with queues on a FIFO basis.
98 ->enqueue(LIST)
100 Adds a list of items onto the end of the queue.
101 ->dequeue()
103 ->dequeue(COUNT)
104 Removes the requested number of items (default is 1) from the head
105 of the queue, and returns them. If the queue contains fewer than
106 the requested number of items, then the thread will be blocked
107 until the requisite number of items are available (i.e., until
108 other threads <enqueue> more items).
109 ->dequeue_nb()
111 ->dequeue_nb(COUNT)
112 Removes the requested number of items (default is 1) from the head
113 of the queue, and returns them. If the queue contains fewer than
114 the requested number of items, then it immediately (i.e., non-
115 blocking) returns whatever items there are on the queue. If the
116 queue is empty, then "undef" is returned.
117 ->pending()
119 Returns the number of items still in the queue.
120
122 The following methods can be used to manipulate items anywhere in a
123 queue.
124 To prevent the contents of a queue from being modified by another
126 thread while it is being examined and/or changed, lock the queue inside
127 a local block:
128 {
130 lock($q); # Keep other threads from changing the queue's contents
131 my $item = $q->peek();
132 if ($item ...) {
133 ...
134 }
135 }
136 # Queue is now unlocked
137 ->peek()
139 ->peek(INDEX)
140 Returns an item from the queue without dequeuing anything.
141 Defaults to the the head of queue (at index position 0) if no index
142 is specified. Negative index values are supported as with arrays
143 (i.e., -1 is the end of the queue, -2 is next to last, and so on).
144 If no items exists at the specified index (i.e., the queue is
146 empty, or the index is beyond the number of items on the queue),
147 then "undef" is returned.
148 Remember, the returned item is not removed from the queue, so
150 manipulating a "peek"ed at reference affects the item on the queue.
151 ->insert(INDEX, LIST)
153 Adds the list of items to the queue at the specified index position
154 (0 is the head of the list). Any existing items at and beyond that
155 position are pushed back past the newly added items:
156 $q->enqueue(1, 2, 3, 4);
158 $q->insert(1, qw/foo bar/);
159 # Queue now contains: 1, foo, bar, 2, 3, 4
160 Specifying an index position greater than the number of items in
162 the queue just adds the list to the end.
163 Negative index positions are supported:
165 $q->enqueue(1, 2, 3, 4);
167 $q->insert(-2, qw/foo bar/);
168 # Queue now contains: 1, 2, foo, bar, 3, 4
169 Specifying a negative index position greater than the number of
171 items in the queue adds the list to the head of the queue.
172 ->extract()
174 ->extract(INDEX)
175 ->extract(INDEX, COUNT)
176 Removes and returns the specified number of items (defaults to 1)
177 from the specified index position in the queue (0 is the head of
178 the queue). When called with no arguments, "extract" operates the
179 same as "dequeue_nb".
180 This method is non-blocking, and will return only as many items as
182 are available to fulfill the request:
183 $q->enqueue(1, 2, 3, 4);
185 my $item = $q->extract(2) # Returns 3
186 # Queue now contains: 1, 2, 4
187 my @items = $q->extract(1, 3) # Returns (2, 4)
188 # Queue now contains: 1
189 Specifying an index position greater than the number of items in
191 the queue results in "undef" or an empty list being returned.
192 $q->enqueue('foo');
194 my $nada = $q->extract(3) # Returns undef
195 my @nada = $q->extract(1, 3) # Returns ()
196 Negative index positions are supported. Specifying a negative
198 index position greater than the number of items in the queue may
199 return items from the head of the queue (similar to "dequeue_nb")
200 if the count overlaps the head of the queue from the specified
201 position (i.e. if queue size + index + count is greater than zero):
202 $q->enqueue(qw/foo bar baz/);
204 my @nada = $q->extract(-6, 2); # Returns () - (3+(-6)+2) <= 0
205 my @some = $q->extract(-6, 4); # Returns (foo) - (3+(-6)+4) > 0
206 # Queue now contains: bar, baz
207 my @rest = $q->extract(-3, 4); # Returns (bar, baz) - (2+(-3)+4) > 0
208
210 Queues created by Thread::Queue can be used in both threaded and non-
211 threaded applications.
212
214 Passing objects on queues may not work if the objects' classes do not
215 support sharing. See "BUGS AND LIMITATIONS" in threads::shared for
216 more.
217 Passing array/hash refs that contain objects may not work for Perl
219 prior to 5.10.0.
220
222 Thread::Queue Discussion Forum on CPAN:
223 http://www.cpanforum.com/dist/Thread-Queue
224 <http://www.cpanforum.com/dist/Thread-Queue>
225 Annotated POD for Thread::Queue:
227 http://annocpan.org/~JDHEDDEN/Thread-Queue-2.11/lib/Thread/Queue.pm
228 <http://annocpan.org/~JDHEDDEN/Thread-Queue-2.11/lib/Thread/Queue.pm>
229 Source repository: http://code.google.com/p/thread-queue/
231 <http://code.google.com/p/thread-queue/>
232 threads, threads::shared
234
236 Jerry D. Hedden, <jdhedden AT cpan DOT org>
237
239 This program is free software; you can redistribute it and/or modify it
240 under the same terms as Perl itself.
241perl v5.12.4 2011-06-07 Thread::Queue(3pm)