Commit | Line | Data |
---|---|---|
83272a45 JH |
1 | package Thread::Queue; |
2 | use Thread qw(cond_wait cond_broadcast); | |
3 | ||
f7229ad3 JH |
4 | use vars qw($VERSION); |
5 | $VERSION = '1.00'; | |
6 | ||
83272a45 JH |
7 | =head1 NAME |
8 | ||
9 | Thread::Queue - thread-safe queues (5.005-threads) | |
10 | ||
11 | =head1 CAVEAT | |
12 | ||
13 | This Perl installation is using the old unsupported "5.005 threads". | |
14 | Use of the old threads model is discouraged. | |
15 | ||
16 | For the whole story about the development of threads in Perl, and why | |
17 | you should B<not> be using "old threads" unless you know what you're | |
18 | doing, see the CAVEAT of the C<Thread> module. | |
19 | ||
20 | =head1 SYNOPSIS | |
21 | ||
22 | use Thread::Queue; | |
23 | my $q = new Thread::Queue; | |
24 | $q->enqueue("foo", "bar"); | |
25 | my $foo = $q->dequeue; # The "bar" is still in the queue. | |
26 | my $foo = $q->dequeue_nb; # returns "bar", or undef if the queue was | |
27 | # empty | |
28 | my $left = $q->pending; # returns the number of items still in the queue | |
29 | ||
30 | =head1 DESCRIPTION | |
31 | ||
32 | A queue, as implemented by C<Thread::Queue> is a thread-safe data structure | |
33 | much like a list. Any number of threads can safely add elements to the end | |
34 | of the list, or remove elements from the head of the list. (Queues don't | |
35 | permit adding or removing elements from the middle of the list) | |
36 | ||
37 | =head1 FUNCTIONS AND METHODS | |
38 | ||
39 | =over 8 | |
40 | ||
41 | =item new | |
42 | ||
43 | The C<new> function creates a new empty queue. | |
44 | ||
45 | =item enqueue LIST | |
46 | ||
47 | The C<enqueue> method adds a list of scalars on to the end of the queue. | |
48 | The queue will grow as needed to accomodate the list. | |
49 | ||
50 | =item dequeue | |
51 | ||
52 | The C<dequeue> method removes a scalar from the head of the queue and | |
53 | returns it. If the queue is currently empty, C<dequeue> will block the | |
54 | thread until another thread C<enqueue>s a scalar. | |
55 | ||
56 | =item dequeue_nb | |
57 | ||
58 | The C<dequeue_nb> method, like the C<dequeue> method, removes a scalar from | |
59 | the head of the queue and returns it. Unlike C<dequeue>, though, | |
60 | C<dequeue_nb> won't block if the queue is empty, instead returning | |
61 | C<undef>. | |
62 | ||
63 | =item pending | |
64 | ||
65 | The C<pending> method returns the number of items still in the queue. (If | |
66 | there can be multiple readers on the queue it's best to lock the queue | |
67 | before checking to make sure that it stays in a consistent state) | |
68 | ||
69 | =back | |
70 | ||
71 | =head1 SEE ALSO | |
72 | ||
73 | L<Thread> | |
74 | ||
75 | =cut | |
76 | ||
77 | sub new { | |
78 | my $class = shift; | |
79 | return bless [@_], $class; | |
80 | } | |
81 | ||
82 | sub dequeue : locked : method { | |
83 | my $q = shift; | |
84 | cond_wait $q until @$q; | |
85 | return shift @$q; | |
86 | } | |
87 | ||
88 | sub dequeue_nb : locked : method { | |
89 | my $q = shift; | |
90 | if (@$q) { | |
91 | return shift @$q; | |
92 | } else { | |
93 | return undef; | |
94 | } | |
95 | } | |
96 | ||
97 | sub enqueue : locked : method { | |
98 | my $q = shift; | |
99 | push(@$q, @_) and cond_broadcast $q; | |
100 | } | |
101 | ||
102 | sub pending : locked : method { | |
103 | my $q = shift; | |
104 | return scalar(@$q); | |
105 | } | |
106 | ||
107 | 1; |