Debian Codegraph @

lib_maint/Thread/Queue/Any.pm_maint

raw
1 package Thread::Queue::Any;
2
3 # initializations
4 @ISA= qw( Thread::Queue );
5 $VERSION= '0.16';
6
7 # be as strict as possble
8 use strict;
9
10 # modules that we need
11 use Storable (); # no need to pollute namespace
12 use Thread::Queue (); # no need to pollute namespace
13
14 # synonym for dequeue_dontwait
15 {
16 no warnings 'once';
17 *dequeue_nb = \&dequeue_dontwait;
18 }
19
20 # satisfy -require-
21 1;
22
23 #-------------------------------------------------------------------------------
24 # IN: 1 instantiated object
25 # 2..N parameters to be passed as a set onto the queue
26
27 sub enqueue {
28 return shift->SUPER::enqueue( Storable::freeze( \@_ ) );
29 } #enqueue
30
31 #-------------------------------------------------------------------------------
32 # IN: 1 instantiated object
33 # OUT: 1..N parameters returned from a set on the queue
34
35 sub dequeue {
36 return @{ Storable::thaw( shift->SUPER::dequeue ) };
37 } #dequeue
38
39 #-------------------------------------------------------------------------------
40 # IN: 1 instantiated object
41 # OUT: 1..N parameters returned from a set on the queue
42
43 sub dequeue_dontwait {
44 my $ref= shift->SUPER::dequeue_nb or return;
45 return @{ Storable::thaw($ref) };
46 } #dequeue_dontwait
47
48 #-------------------------------------------------------------------------------
49 # IN: 1 instantiated object
50 # OUT: 1..N parameters returned from a set on the queue
51
52 sub dequeue_keep {
53 lock( @{ $_[0] } ); # make sure we're the only
54 my $ref= shift->[0] or return;
55 return @{ Storable::thaw($ref) };
56 } #dequeue_keep
57
58 #-------------------------------------------------------------------------------
59
60 __END__
61
62 =head1 NAME
63
64 Thread::Queue::Any - thread-safe queues for any data-structure
65
66 =head1 SYNOPSIS
67
68 use Thread::Queue::Any;
69 my $q= Thread::Queue::Any->new;
70 $q->enqueue("foo", ["bar"], {"zoo"});
71 my ( $foo, $bar, $zoo )= $q->dequeue;
72 my ( $foo, $bar, $zoo )= $q->dequeue_dontwait;
73 my ( $iffoo, $ifbar, $ifzoo)= $q->dequeue_keep;
74 my $left= $q->pending;
75
76 =head1 VERSION
77
78 This documentation describes version 0.16.
79
80 =head1 DESCRIPTION
81
82 *** A note of CAUTION ***
83
84 This module only functions on threaded perl or an unthreaded perl
85 with the "forks" module installed.
86
87 Please also note that this documentation describes the "maint" version
88 of this code. This version is essentially frozen. Please use a 5.14
89 or higher version of perl for the "blead" version of this code.
90
91 *************************
92
93 A queue, as implemented by C<Thread::Queue::Any> is a thread-safe
94 data structure that inherits from C<Thread::Queue>. But unlike the
95 standard C<Thread::Queue>, you can pass (a reference to) any data
96 structure to the queue.
97
98 Apart from the fact that the parameters to C<enqueue> are considered to be
99 a set that needs to be enqueued together and that C<dequeue> returns all of
100 the parameters that were enqueued together, this module is a drop-in
101 replacement for C<Thread::Queue> in every other aspect.
102
103 Any number of threads can safely add elements to the end of the list, or
104 remove elements from the head of the list. (Queues don't permit adding or
105 removing elements from the middle of the list).
106
107 =head1 CLASS METHODS
108
109 =head2 new
110
111 $queue= Thread::Queue::Any->new;
112
113 The C<new> function creates a new empty queue.
114
115 =head1 OBJECT METHODS
116
117 =head2 enqueue LIST
118
119 $queue->enqueue( 'string', $scalar, [], {} );
120
121 The C<enqueue> method adds a reference to all the specified parameters on to
122 the end of the queue. The queue will grow as needed.
123
124 =head2 dequeue
125
126 ( $string, $scalar, $listref, $hashref )= $queue->dequeue;
127
128 The C<dequeue> method removes a reference from the head of the queue,
129 dereferences it and returns the resulting values. If the queue is currently
130 empty, C<dequeue> will block the thread until another thread C<enqueue>s.
131
132 =head2 dequeue_dontwait
133
134 ( $string, $scalar, $listref, $hashref )= $queue->dequeue_dontwait;
135
136 The C<dequeue_dontwait> method, like the C<dequeue> method, removes a
137 reference from the head of the queue, dereferences it and returns the
138 resulting values. Unlike C<dequeue>, though, C<dequeue_dontwait> won't wait
139 if the queue is empty, instead returning an empty list if the queue is empty.
140
141 For compatibility with L<Thread::Queue>, the name "dequeue_nb" is available
142 as a synonym for this method.
143
144 =head2 dequeue_keep
145
146 ( $string, $scalar, $listref, $hashref )= $queue->dequeue_keep;
147
148 The C<dequeue_keep> method, like the C<dequeue_dontwait> method, takes a
149 reference from the head of the queue, dereferences it and returns the
150 resulting values. Unlike C<dequeue_dontwait>, though, the C<dequeue_keep>
151 B<won't remove> the set from the queue. It can therefore be used to test if
152 the next set to be returned from the queue with C<dequeue> or
153 C<dequeue_dontwait> will have a specific value.
154
155 =head2 pending
156
157 $pending= $queue->pending;
158
159 The C<pending> method returns the number of items still in the queue.
160
161 =head1 REQUIRED MODULES
162
163 Thread::Queue (any)
164
165 =head1 CAVEATS
166
167 Passing unshared values between threads is accomplished by serializing the
168 specified values using C<Storable> when enqueuing and de-serializing the queued
169 value on dequeuing. This allows for great flexibility at the expense of more
170 CPU usage. It also limits what can be passed, as e.g. code references can
171 B<not> be serialized and therefore not be passed.
172
173 =head1 AUTHOR
174
175 Elizabeth Mattijsen, <[email protected]>.
176
177 Please report bugs to <[email protected]>.
178
179 =head1 COPYRIGHT
180
181 Copyright (c) 2002, 2003, 2007, 2012 Elizabeth Mattijsen <[email protected]>.
182 All rights reserved. This program is free software; you can redistribute it
183 and/or modify it under the same terms as Perl itself.
184
185 =head1 SEE ALSO
186
187 L<threads>, L<threads::shared>, L<Thread::Queue>, L<Storable>.
188
189 =cut