Commit | Line | Data |
d21067e0 |
1 | package Thread::Queue; |
28b605d8 |
2 | |
3d1f1caf |
3 | use strict; |
28b605d8 |
4 | |
3d1f1caf |
5 | our $VERSION = '1.00'; |
9c6f8578 |
6 | |
d21067e0 |
7 | use Thread qw(cond_wait cond_broadcast); |
8 | |
9c6f8578 |
9 | BEGIN { |
10 | use Config; |
3d1f1caf |
11 | if ($Config{useithreads}) { |
9c6f8578 |
12 | require 'threads/shared/queue.pm'; |
3d1f1caf |
13 | for my $meth (qw(new enqueue dequeue dequeue_nb pending)) { |
9c6f8578 |
14 | no strict 'refs'; |
3d1f1caf |
15 | *{"Thread::Queue::$meth"} = \&{"threads::shared::queue::$meth"}; |
9c6f8578 |
16 | } |
3d1f1caf |
17 | } elsif ($Config{use5005threads}) { |
18 | for my $meth (qw(new enqueue dequeue dequeue_nb pending)) { |
9c6f8578 |
19 | no strict 'refs'; |
3d1f1caf |
20 | *{"Thread::Queue::$meth"} = \&{"Thread::Queue::${meth}_othread"}; |
9c6f8578 |
21 | } |
3d1f1caf |
22 | } else { |
23 | require Carp; |
24 | Carp::croak("This Perl has neither ithreads nor 5005threads"); |
9c6f8578 |
25 | } |
26 | } |
27 | |
28 | |
d516a115 |
29 | =head1 NAME |
30 | |
3d1f1caf |
31 | Thread::Queue - thread-safe queues (for old code only) |
32 | |
33 | =head1 CAVEAT |
34 | |
35 | For new code the use of the C<Thread::Queue> module is discouraged and |
36 | the direct use of the C<threads>, C<threads::shared> and |
37 | C<threads::shared::queue> modules is encouraged instead. |
38 | |
39 | For the whole story about the development of threads in Perl, and why you |
40 | should B<not> be using this module unless you know what you're doing, see the |
41 | CAVEAT of the C<Thread> module. |
d516a115 |
42 | |
43 | =head1 SYNOPSIS |
44 | |
45 | use Thread::Queue; |
46 | my $q = new Thread::Queue; |
47 | $q->enqueue("foo", "bar"); |
a99072da |
48 | my $foo = $q->dequeue; # The "bar" is still in the queue. |
49 | my $foo = $q->dequeue_nb; # returns "bar", or undef if the queue was |
50 | # empty |
51 | my $left = $q->pending; # returns the number of items still in the queue |
d516a115 |
52 | |
a99072da |
53 | =head1 DESCRIPTION |
54 | |
55 | A queue, as implemented by C<Thread::Queue> is a thread-safe data structure |
56 | much like a list. Any number of threads can safely add elements to the end |
57 | of the list, or remove elements from the head of the list. (Queues don't |
58 | permit adding or removing elements from the middle of the list) |
59 | |
60 | =head1 FUNCTIONS AND METHODS |
61 | |
62 | =over 8 |
63 | |
64 | =item new |
65 | |
66 | The C<new> function creates a new empty queue. |
67 | |
68 | =item enqueue LIST |
69 | |
70 | The C<enqueue> method adds a list of scalars on to the end of the queue. |
71 | The queue will grow as needed to accomodate the list. |
72 | |
73 | =item dequeue |
74 | |
75 | The C<dequeue> method removes a scalar from the head of the queue and |
76 | returns it. If the queue is currently empty, C<dequeue> will block the |
77 | thread until another thread C<enqueue>s a scalar. |
78 | |
79 | =item dequeue_nb |
80 | |
81 | The C<dequeue_nb> method, like the C<dequeue> method, removes a scalar from |
82 | the head of the queue and returns it. Unlike C<dequeue>, though, |
83 | C<dequeue_nb> won't block if the queue is empty, instead returning |
84 | C<undef>. |
85 | |
86 | =item pending |
87 | |
88 | The C<pending> method returns the number of items still in the queue. (If |
89 | there can be multiple readers on the queue it's best to lock the queue |
90 | before checking to make sure that it stays in a consistent state) |
91 | |
92 | =back |
93 | |
94 | =head1 SEE ALSO |
95 | |
96 | L<Thread> |
bbc7dcd2 |
97 | |
d516a115 |
98 | =cut |
99 | |
9c6f8578 |
100 | sub new_othread { |
d21067e0 |
101 | my $class = shift; |
102 | return bless [@_], $class; |
103 | } |
104 | |
9c6f8578 |
105 | sub dequeue_othread : locked : method { |
d21067e0 |
106 | my $q = shift; |
107 | cond_wait $q until @$q; |
108 | return shift @$q; |
109 | } |
110 | |
9c6f8578 |
111 | sub dequeue_nb_othread : locked : method { |
a99072da |
112 | my $q = shift; |
113 | if (@$q) { |
114 | return shift @$q; |
115 | } else { |
116 | return undef; |
117 | } |
118 | } |
119 | |
9c6f8578 |
120 | sub enqueue_othread : locked : method { |
d21067e0 |
121 | my $q = shift; |
122 | push(@$q, @_) and cond_broadcast $q; |
123 | } |
124 | |
9c6f8578 |
125 | sub pending_othread : locked : method { |
3d1f1caf |
126 | return scalar(@{(shift)}); |
a99072da |
127 | } |
128 | |
d21067e0 |
129 | 1; |