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.14
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 # Set a size for a queue
54 $q->limit = 5;
55 # Get the second item in the queue without dequeuing anything
57 my $item = $q->peek(1);
58 # Insert two items into the queue just behind the head
60 $q->insert(1, $item1, $item2);
61 # Extract the last two items on the queue
63 my ($item1, $item2) = $q->extract(-2, 2);
64
66 This module provides thread-safe FIFO queues that can be accessed
67 safely by any number of threads.
68 Any data types supported by threads::shared can be passed via queues:
70 Ordinary scalars
72 Array refs
73 Hash refs
74 Scalar refs
75 Objects based on the above
76 Ordinary scalars are added to queues as they are.
78 If not already thread-shared, the other complex data types will be
80 cloned (recursively, if needed, and including any "bless"ings and read-
81 only settings) into thread-shared structures before being placed onto a
82 queue.
83 For example, the following would cause Thread::Queue to create a empty,
85 shared array reference via &shared([]), copy the elements 'foo', 'bar'
86 and 'baz' from @ary into it, and then place that shared reference onto
87 the queue:
88 my @ary = qw/foo bar baz/;
90 $q->enqueue(\@ary);
91 However, for the following, the items are already shared, so their
93 references are added directly to the queue, and no cloning takes place:
94 my @ary :shared = qw/foo bar baz/;
96 $q->enqueue(\@ary);
97 my $obj = &shared({});
99 $$obj{'foo'} = 'bar';
100 $$obj{'qux'} = 99;
101 bless($obj, 'My::Class');
102 $q->enqueue($obj);
103 See "LIMITATIONS" for caveats related to passing objects via queues.
105
107 ->new()
108 Creates a new empty queue.
109 ->new(LIST)
111 Creates a new queue pre-populated with the provided list of items.
112
114 The following methods deal with queues on a FIFO basis.
115 ->enqueue(LIST)
117 Adds a list of items onto the end of the queue.
118 ->dequeue()
120 ->dequeue(COUNT)
121 Removes the requested number of items (default is 1) from the head
122 of the queue, and returns them. If the queue contains fewer than
123 the requested number of items, then the thread will be blocked
124 until the requisite number of items are available (i.e., until
125 other threads "enqueue" more items).
126 ->dequeue_nb()
128 ->dequeue_nb(COUNT)
129 Removes the requested number of items (default is 1) from the head
130 of the queue, and returns them. If the queue contains fewer than
131 the requested number of items, then it immediately (i.e., non-
132 blocking) returns whatever items there are on the queue. If the
133 queue is empty, then "undef" is returned.
134 ->dequeue_timed(TIMEOUT)
136 ->dequeue_timed(TIMEOUT, COUNT)
137 Removes the requested number of items (default is 1) from the head
138 of the queue, and returns them. If the queue contains fewer than
139 the requested number of items, then the thread will be blocked
140 until the requisite number of items are available, or until the
141 timeout is reached. If the timeout is reached, it returns whatever
142 items there are on the queue, or "undef" if the queue is empty.
143 The timeout may be a number of seconds relative to the current time
145 (e.g., 5 seconds from when the call is made), or may be an absolute
146 timeout in epoch seconds the same as would be used with
147 cond_timedwait(). Fractional seconds (e.g., 2.5 seconds) are also
148 supported (to the extent of the underlying implementation).
149 If "TIMEOUT" is missing, "undef", or less than or equal to 0, then
151 this call behaves the same as "dequeue_nb".
152 ->pending()
154 Returns the number of items still in the queue. Returns "undef" if
155 the queue has been ended (see below), and there are no more items
156 in the queue.
157 ->limit
159 Sets the size of the queue. If set, calls to enqueue() will block
160 until the number of pending items in the queue drops below the
161 "limit". The "limit" does not prevent enqueuing items beyond that
162 count:
163 my $q = Thread::Queue->new(1, 2);
165 $q->limit = 4;
166 $q->enqueue(3, 4, 5); # Does not block
167 $q->enqueue(6); # Blocks until at least 2 items are
168 # dequeued
169 my $size = $q->limit; # Returns the current limit (may return
170 # 'undef')
171 $q->limit = 0; # Queue size is now unlimited
172 Calling any of the dequeue methods with "COUNT" greater than a
174 queue's "limit" will generate an error.
175 ->end()
177 Declares that no more items will be added to the queue.
178 All threads blocking on dequeue() calls will be unblocked with any
180 remaining items in the queue and/or "undef" being returned. Any
181 subsequent calls to dequeue() will behave like dequeue_nb().
182 Once ended, no more items may be placed in the queue.
184
186 The following methods can be used to manipulate items anywhere in a
187 queue.
188 To prevent the contents of a queue from being modified by another
190 thread while it is being examined and/or changed, lock the queue inside
191 a local block:
192 {
194 lock($q); # Keep other threads from changing the queue's contents
195 my $item = $q->peek();
196 if ($item ...) {
197 ...
198 }
199 }
200 # Queue is now unlocked
201 ->peek()
203 ->peek(INDEX)
204 Returns an item from the queue without dequeuing anything.
205 Defaults to the head of queue (at index position 0) if no index is
206 specified. Negative index values are supported as with arrays
207 (i.e., -1 is the end of the queue, -2 is next to last, and so on).
208 If no items exists at the specified index (i.e., the queue is
210 empty, or the index is beyond the number of items on the queue),
211 then "undef" is returned.
212 Remember, the returned item is not removed from the queue, so
214 manipulating a "peek"ed at reference affects the item on the queue.
215 ->insert(INDEX, LIST)
217 Adds the list of items to the queue at the specified index position
218 (0 is the head of the list). Any existing items at and beyond that
219 position are pushed back past the newly added items:
220 $q->enqueue(1, 2, 3, 4);
222 $q->insert(1, qw/foo bar/);
223 # Queue now contains: 1, foo, bar, 2, 3, 4
224 Specifying an index position greater than the number of items in
226 the queue just adds the list to the end.
227 Negative index positions are supported:
229 $q->enqueue(1, 2, 3, 4);
231 $q->insert(-2, qw/foo bar/);
232 # Queue now contains: 1, 2, foo, bar, 3, 4
233 Specifying a negative index position greater than the number of
235 items in the queue adds the list to the head of the queue.
236 ->extract()
238 ->extract(INDEX)
239 ->extract(INDEX, COUNT)
240 Removes and returns the specified number of items (defaults to 1)
241 from the specified index position in the queue (0 is the head of
242 the queue). When called with no arguments, "extract" operates the
243 same as "dequeue_nb".
244 This method is non-blocking, and will return only as many items as
246 are available to fulfill the request:
247 $q->enqueue(1, 2, 3, 4);
249 my $item = $q->extract(2) # Returns 3
250 # Queue now contains: 1, 2, 4
251 my @items = $q->extract(1, 3) # Returns (2, 4)
252 # Queue now contains: 1
253 Specifying an index position greater than the number of items in
255 the queue results in "undef" or an empty list being returned.
256 $q->enqueue('foo');
258 my $nada = $q->extract(3) # Returns undef
259 my @nada = $q->extract(1, 3) # Returns ()
260 Negative index positions are supported. Specifying a negative
262 index position greater than the number of items in the queue may
263 return items from the head of the queue (similar to "dequeue_nb")
264 if the count overlaps the head of the queue from the specified
265 position (i.e. if queue size + index + count is greater than zero):
266 $q->enqueue(qw/foo bar baz/);
268 my @nada = $q->extract(-6, 2); # Returns () - (3+(-6)+2) <= 0
269 my @some = $q->extract(-6, 4); # Returns (foo) - (3+(-6)+4) > 0
270 # Queue now contains: bar, baz
271 my @rest = $q->extract(-3, 4); # Returns (bar, baz) -
272 # (2+(-3)+4) > 0
273
275 Queues created by Thread::Queue can be used in both threaded and non-
276 threaded applications.
277
279 Passing objects on queues may not work if the objects' classes do not
280 support sharing. See "BUGS AND LIMITATIONS" in threads::shared for
281 more.
282 Passing array/hash refs that contain objects may not work for Perl
284 prior to 5.10.0.
285
287 Thread::Queue on MetaCPAN: <https://metacpan.org/release/Thread-Queue>
288 Code repository for CPAN distribution:
290 <https://github.com/Dual-Life/Thread-Queue>
291 threads, threads::shared
293 Sample code in the examples directory of this distribution on CPAN.
295
297 Jerry D. Hedden, <jdhedden AT cpan DOT org>
298
300 This program is free software; you can redistribute it and/or modify it
301 under the same terms as Perl itself.
302perl v5.36.0 2023-01-20 Thread::Queue(3)