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

Diff Legend

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