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.6 by root, Tue Jul 17 15:42:28 2001 UTC vs.
Revision 1.94 by root, Tue Jun 23 23:40:06 2009 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::Semaphore;
8 8
… …
14 14
15 $sig->up; 15 $sig->up;
16 16
17=head1 DESCRIPTION 17=head1 DESCRIPTION
18 18
19This module implements counting semaphores. You can initialize a mutex
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
22associated with semaphores, so one coroutine can C<down> it while another
23can C<up> it.
24
25Counting semaphores are typically used to coordinate access to
26resources, with the semaphore count initialized to the number of free
27resources. Coroutines then increment the count when resources are added
28and decrement the count when resources are removed.
29
19=over 4 30=over 4
20 31
21=cut 32=cut
22 33
23package Coro::Semaphore; 34package Coro::Semaphore;
24 35
36no warnings;
37
25use Coro (); 38use Coro ();
26 39
27$VERSION = 0.07; 40$VERSION = 5.14;
28 41
29=item new [inital count, default zero] 42=item new [inital count]
30 43
31Creates a new sempahore object with the given initial lock count. The 44Creates a new sempahore object with the given initial lock count. The
32default lock count is 1, which means it is unlocked by default. 45default lock count is 1, which means it is unlocked by default. Zero (or
46negative values) are also allowed, in which case the semaphore is locked
47by default.
33 48
34=cut 49=item $sem->count
35 50
36sub new { 51Returns the current semaphore count.
37 bless [defined $_[1] ? $_[1] : 1], $_[0]; 52
38} 53=item $sem->adjust ($diff)
54
55Atomically adds the amount given to the current semaphore count. If the
56count becomes positive, wakes up any waiters. Does not block if the count
57becomes negative, however.
39 58
40=item $sem->down 59=item $sem->down
41 60
42Decrement the counter, therefore "locking" the semaphore. This method 61Decrement the counter, therefore "locking" the semaphore. This method
43waits until the semaphore is available if the counter is zero. 62waits until the semaphore is available if the counter is zero.
44 63
64=item $sem->wait
65
66Similar 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
68guaranteed to succeed without blocking, until the next coroutine switch
69(C<cede> etc.).
70
71Note that using C<wait> is much less efficient than using C<down>, so try
72to prefer C<down> whenever possible.
73
74=item $sem->wait ($callback)
75
76If you pass a callback argument to C<wait>, it will not wait, but
77immediately return. The callback will be called as soon as the semaphore
78becomes available (which might be instantly), and gets passed the
79semaphore as first argument.
80
81The callback might C<down> the semaphore exactly once, might wake up other
82coroutines, but is I<NOT> allowed to block (switch to other coroutines).
83
45=cut 84=cut
46 85
47sub down { 86#=item $status = $sem->timed_down ($timeout)
48 my $self = shift; 87#
88#Like C<down>, but returns false if semaphore couldn't be acquired within
89#$timeout seconds, otherwise true.
90
91#sub timed_down {
92# require Coro::Timer;
93# my $timeout = Coro::Timer::timeout ($_[1]);
94#
49 while ($self->[0] <= 0) { 95# while ($_[0][0] <= 0) {
50 push @{$self->[1]}, $Coro::current; 96# push @{$_[0][1]}, $Coro::current;
51 Coro::schedule; 97# &Coro::schedule;
98# if ($timeout) {
99# # ugly as hell. slow, too, btw!
100# for (0..$#{$_[0][1]}) {
101# if ($_[0][1][$_] == $Coro::current) {
102# splice @{$_[0][1]}, $_, 1;
103# return;
104# }
105# }
106# die;
107# }
52 } 108# }
53 --$self->[0]; 109#
54} 110# --$_[0][0];
111# return 1;
112#}
55 113
56=item $sem->up 114=item $sem->up
57 115
58Unlock the semaphore again. 116Unlock the semaphore again.
59
60=cut
61
62sub up {
63 my $self = shift;
64 if (++$self->[0] > 0) {
65 (shift @{$self->[1]})->ready if @{$self->[1]};
66 }
67}
68 117
69=item $sem->try 118=item $sem->try
70 119
71Try to C<down> the semaphore. Returns true when this was possible, 120Try to C<down> the semaphore. Returns true when this was possible,
72otherwise return false and leave the semaphore unchanged. 121otherwise return false and leave the semaphore unchanged.
73 122
123=item $sem->waiters
124
125In scalar context, returns the number of coroutines waiting for this
126semaphore.
127
128=item $guard = $sem->guard
129
130This method calls C<down> and then creates a guard object. When the guard
131object is destroyed it automatically calls C<up>.
132
74=cut 133=cut
75 134
76sub try { 135sub guard {
77 my $self = shift; 136 &down;
78 if ($self->[0] > 0) { 137 bless [$_[0]], Coro::Semaphore::guard::
79 --$self->[0];
80 return 1;
81 } else {
82 return 0;
83 }
84} 138}
85 139
861; 140#=item $guard = $sem->timed_guard ($timeout)
141#
142#Like C<guard>, but returns undef if semaphore couldn't be acquired within
143#$timeout seconds, otherwise the guard object.
144
145#sub timed_guard {
146# &timed_down
147# ? bless \\$_[0], Coro::Semaphore::guard::
148# : ();
149#}
150
151sub Coro::Semaphore::guard::DESTROY {
152 &up($_[0][0]);
153}
87 154
88=back 155=back
89 156
90=head1 AUTHOR 157=head1 AUTHOR
91 158
92 Marc Lehmann <pcg@goof.com> 159 Marc Lehmann <schmorp@schmorp.de>
93 http://www.goof.com/pcg/marc/ 160 http://home.schmorp.de/
94 161
95=cut 162=cut
96 163
1641
165

Diff Legend

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