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.82 by root, Wed Nov 19 11:11:10 2008 UTC vs.
Revision 1.127 by root, Thu Dec 13 01:50:29 2012 UTC

1=head1 NAME 1=head1 NAME
2 2
3Coro::Semaphore - non-binary semaphores 3Coro::Semaphore - counting semaphores
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use Coro::Semaphore; 7 use Coro;
8 8
9 $sig = new Coro::Semaphore [initial value]; 9 $sig = new Coro::Semaphore [initial value];
10 10
11 $sig->down; # wait for signal 11 $sig->down; # wait for signal
12 12
… …
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 coroutine 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. Coroutines 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.
31
32You don't have to load C<Coro::Semaphore> manually, it will be loaded
33automatically when you C<use Coro> and call the C<new> constructor.
29 34
30=over 4 35=over 4
31 36
32=cut 37=cut
33 38
34package Coro::Semaphore; 39package Coro::Semaphore;
35 40
36no warnings; 41use common::sense;
37 42
38use Coro (); 43use Coro ();
39 44
40$VERSION = 5.0; 45our $VERSION = 6.23;
41 46
42=item new [inital count] 47=item new [inital count]
43 48
44Creates a new sempahore object with the given initial lock count. The 49Creates a new sempahore object with the given initial lock count. The
45default 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
… …
63 68
64=item $sem->wait 69=item $sem->wait
65 70
66Similar to C<down>, but does not actually decrement the counter. Instead, 71Similar to C<down>, but does not actually decrement the counter. Instead,
67when this function returns, a following call to C<down> or C<try> is 72when this function returns, a following call to C<down> or C<try> is
68guaranteed to succeed without blocking, until the next coroutine switch 73guaranteed to succeed without blocking, until the next thread switch
69(C<cede> etc.). 74(C<cede> etc.).
70 75
71Note that using C<wait> is much less efficient than using C<down>, so try 76Note that using C<wait> is much less efficient than using C<down>, so try
72to prefer C<down> whenever possible. 77to prefer C<down> whenever possible.
73 78
… …
77immediately return. The callback will be called as soon as the semaphore 82immediately return. The callback will be called as soon as the semaphore
78becomes available (which might be instantly), and gets passed the 83becomes available (which might be instantly), and gets passed the
79semaphore as first argument. 84semaphore as first argument.
80 85
81The callback might C<down> the semaphore exactly once, might wake up other 86The callback might C<down> the semaphore exactly once, might wake up other
82coroutines, but is I<NOT> allowed to block (switch to other coroutines). 87threads, but is I<NOT> allowed to block (switch to other threads).
83
84This is considered a rather experimental interface, and is subject to
85change.
86 88
87=cut 89=cut
88 90
89#=item $status = $sem->timed_down ($timeout) 91#=item $status = $sem->timed_down ($timeout)
90# 92#
… …
123Try to C<down> the semaphore. Returns true when this was possible, 125Try to C<down> the semaphore. Returns true when this was possible,
124otherwise return false and leave the semaphore unchanged. 126otherwise return false and leave the semaphore unchanged.
125 127
126=item $sem->waiters 128=item $sem->waiters
127 129
128In scalar context, returns the number of coroutines waiting for this 130In scalar context, returns the number of threads waiting for this
129semaphore. 131semaphore.
130 132
131=item $guard = $sem->guard 133=item $guard = $sem->guard
132 134
133This method calls C<down> and then creates a guard object. When the guard 135This method calls C<down> and then creates a guard object. When the guard
… …
135 137
136=cut 138=cut
137 139
138sub guard { 140sub guard {
139 &down; 141 &down;
140 # double indirection because bless works on the referenced
141 # object, not (only) on the reference itself.
142 bless \\$_[0], Coro::Semaphore::guard::; 142 bless [$_[0]], Coro::Semaphore::guard::
143} 143}
144 144
145#=item $guard = $sem->timed_guard ($timeout) 145#=item $guard = $sem->timed_guard ($timeout)
146# 146#
147#Like C<guard>, but returns undef if semaphore couldn't be acquired within 147#Like C<guard>, but returns undef if semaphore couldn't be acquired within
… …
152# ? bless \\$_[0], Coro::Semaphore::guard:: 152# ? bless \\$_[0], Coro::Semaphore::guard::
153# : (); 153# : ();
154#} 154#}
155 155
156sub Coro::Semaphore::guard::DESTROY { 156sub Coro::Semaphore::guard::DESTROY {
157 &up(${${$_[0]}}); 157 &up($_[0][0]);
158} 158}
159 159
160=back 160=back
161 161
162=head1 AUTHOR 162=head1 AUTHOR

Diff Legend

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