ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Coro/Coro/Semaphore.pm
(Generate patch)

Comparing Coro/Coro/Semaphore.pm (file contents):
Revision 1.112 by root, Sat Feb 19 06:51:23 2011 UTC vs.
Revision 1.148 by root, Fri Oct 16 23:42:56 2015 UTC

… …
17=head1 DESCRIPTION 17=head1 DESCRIPTION
18 18
19This module implements counting semaphores. You can initialize a mutex 19This module implements counting semaphores. You can initialize a mutex
20with any level of parallel users, that is, you can intialize a sempahore 20with any level of parallel users, that is, you can intialize a sempahore
21that can be C<down>ed more than once until it blocks. There is no owner 21that can be C<down>ed more than once until it blocks. There is no owner
22associated with semaphores, so one thread can C<down> it while another 22associated with semaphores, so one thread can C<down> it while another can
23can C<up> it. 23C<up> it (or vice versa), C<up> can be called before C<down> and so on:
24the semaphore is really just an integer counter that optionally blocks
25when it is 0.
24 26
25Counting semaphores are typically used to coordinate access to 27Counting semaphores are typically used to coordinate access to
26resources, with the semaphore count initialized to the number of free 28resources, with the semaphore count initialized to the number of free
27resources. Threads then increment the count when resources are added 29resources. Threads then increment the count when resources are added
28and decrement the count when resources are removed. 30and decrement the count when resources are removed.
29 31
30You don't have to load C<Coro::Semaphore> manually, it will be loaded 32You don't have to load C<Coro::Semaphore> manually, it will be loaded
31automatically when you C<use Coro> and call the C<new> constructor. 33automatically when you C<use Coro> and call the C<new> constructor.
32 34
33=over 4 35=over 4
34 36
35=cut 37=cut
36 38
… …
38 40
39use common::sense; 41use common::sense;
40 42
41use Coro (); 43use Coro ();
42 44
43our $VERSION = 5.37; 45our $VERSION = 6.49;
44 46
45=item new [inital count] 47=item new [inital count]
46 48
47Creates a new sempahore object with the given initial lock count. The 49Creates a new sempahore object with the given initial lock count. The
48default lock count is 1, which means it is unlocked by default. Zero (or 50default lock count is 1, which means it is unlocked by default. Zero (or
49negative values) are also allowed, in which case the semaphore is locked 51negative values) are also allowed, in which case the semaphore is locked
50by default. 52by default.
51 53
52=item $sem->count 54=item $sem->count
53 55
54Returns the current semaphore count. 56Returns the current semaphore count. The semaphore can be down'ed without
57blocking when the count is strictly higher than C<0>.
55 58
56=item $sem->adjust ($diff) 59=item $sem->adjust ($diff)
57 60
58Atomically adds the amount given to the current semaphore count. If the 61Atomically adds the amount given to the current semaphore count. If the
59count becomes positive, wakes up any waiters. Does not block if the count 62count becomes positive, wakes up any waiters. Does not block if the count
60becomes negative, however. 63becomes negative, however.
61 64
62=item $sem->down 65=item $sem->down
63 66
64Decrement the counter, therefore "locking" the semaphore. This method 67Decrement the counter, therefore "locking" the semaphore. This method
65waits until the semaphore is available if the counter is zero. 68waits until the semaphore is available if the counter is zero or less.
66 69
67=item $sem->wait 70=item $sem->wait
68 71
69Similar to C<down>, but does not actually decrement the counter. Instead, 72Similar to C<down>, but does not actually decrement the counter. Instead,
70when this function returns, a following call to C<down> or C<try> is 73when this function returns, a following call to C<down> or C<try> is
… …
124otherwise return false and leave the semaphore unchanged. 127otherwise return false and leave the semaphore unchanged.
125 128
126=item $sem->waiters 129=item $sem->waiters
127 130
128In scalar context, returns the number of threads waiting for this 131In scalar context, returns the number of threads waiting for this
129semaphore. 132semaphore. Might accidentally cause WW3 if called in other contexts, so
133don't use these.
130 134
131=item $guard = $sem->guard 135=item $guard = $sem->guard
132 136
133This method calls C<down> and then creates a guard object. When the guard 137This method calls C<down> and then creates a guard object. When the guard
134object is destroyed it automatically calls C<up>. 138object is destroyed it automatically calls C<up>.
… …
155 &up($_[0][0]); 159 &up($_[0][0]);
156} 160}
157 161
158=back 162=back
159 163
160=head1 AUTHOR 164=head1 AUTHOR/SUPPORT/CONTACT
161 165
162 Marc Lehmann <schmorp@schmorp.de> 166 Marc A. Lehmann <schmorp@schmorp.de>
163 http://home.schmorp.de/ 167 http://software.schmorp.de/pkg/Coro.html
164 168
165=cut 169=cut
166 170
1671 1711
168 172

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines