Commit | Line | Data |
---|---|---|
6d1f61ba AB |
1 | package threads::shared::queue; |
2 | ||
3 | use threads::shared; | |
4 | use strict; | |
5 | ||
78f7020a | 6 | our $VERSION = '1.00'; |
6d1f61ba | 7 | |
54934ab5 AB |
8 | =head1 NAME |
9 | ||
10 | threads::shared::queue - thread-safe queues | |
11 | ||
12 | =head1 SYNOPSIS | |
13 | ||
14 | use threads::shared::queue; | |
15 | my $q = new threads::shared::queue; | |
16 | $q->enqueue("foo", "bar"); | |
17 | my $foo = $q->dequeue; # The "bar" is still in the queue. | |
18 | my $foo = $q->dequeue_nb; # returns "bar", or undef if the queue was | |
19 | # empty | |
20 | my $left = $q->pending; # returns the number of items still in the queue | |
21 | ||
22 | =head1 DESCRIPTION | |
23 | ||
24 | A queue, as implemented by C<threads::shared::queue> is a thread-safe | |
25 | data structure much like a list. Any number of threads can safely | |
26 | add elements to the end of the list, or remove elements from the head | |
27 | of the list. (Queues don't permit adding or removing elements from | |
4cab98c0 | 28 | the middle of the list). |
54934ab5 AB |
29 | |
30 | =head1 FUNCTIONS AND METHODS | |
31 | ||
32 | =over 8 | |
33 | ||
34 | =item new | |
35 | ||
36 | The C<new> function creates a new empty queue. | |
37 | ||
38 | =item enqueue LIST | |
39 | ||
40 | The C<enqueue> method adds a list of scalars on to the end of the queue. | |
4cab98c0 | 41 | The queue will grow as needed to accommodate the list. |
54934ab5 AB |
42 | |
43 | =item dequeue | |
44 | ||
45 | The C<dequeue> method removes a scalar from the head of the queue and | |
46 | returns it. If the queue is currently empty, C<dequeue> will block the | |
47 | thread until another thread C<enqueue>s a scalar. | |
48 | ||
49 | =item dequeue_nb | |
50 | ||
51 | The C<dequeue_nb> method, like the C<dequeue> method, removes a scalar from | |
52 | the head of the queue and returns it. Unlike C<dequeue>, though, | |
53 | C<dequeue_nb> won't block if the queue is empty, instead returning | |
54 | C<undef>. | |
55 | ||
56 | =item pending | |
57 | ||
58 | The C<pending> method returns the number of items still in the queue. | |
59 | ||
60 | =back | |
61 | ||
62 | =head1 SEE ALSO | |
63 | ||
4cab98c0 | 64 | L<threads>, L<threads::shared> |
54934ab5 AB |
65 | |
66 | =cut | |
67 | ||
78f7020a JH |
68 | sub new { |
69 | my $class = shift; | |
70 | my @q : shared = @_; | |
71 | my $q = \@q; | |
72 | return bless $q, $class; | |
73 | } | |
74 | ||
75 | sub dequeue { | |
76 | my $q = shift; | |
77 | lock(@$q); | |
78 | until(@$q) { | |
79 | cond_wait(@$q); | |
80 | } | |
81 | return shift @$q; | |
82 | } | |
83 | ||
84 | sub dequeue_nb { | |
85 | my $q = shift; | |
86 | lock(@$q); | |
87 | if (@$q) { | |
88 | return shift @$q; | |
89 | } else { | |
90 | return undef; | |
91 | } | |
92 | } | |
93 | ||
94 | sub enqueue { | |
95 | my $q = shift; | |
96 | lock(@$q); | |
97 | push(@$q, @_) and cond_broadcast @$q; | |
98 | } | |
99 | ||
100 | sub pending { | |
101 | my $q = shift; | |
102 | lock(@$q); | |
103 | return scalar(@$q); | |
104 | } | |
105 | ||
106 | 1; | |
107 | ||
108 |