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.21 by root, Mon Sep 24 01:36:20 2001 UTC vs.
Revision 1.128 by root, Fri Feb 8 22:29:18 2013 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 qw(uninitialized); 41use common::sense;
37 42
38use Coro (); 43use Coro ();
39 44
40$VERSION = 0.5; 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
46negative values) are also allowed, in which case the semaphore is locked 51negative values) are also allowed, in which case the semaphore is locked
47by default. 52by default.
48 53
49=cut 54=item $sem->count
50 55
51sub new { 56Returns the current semaphore count.
52 bless [defined $_[1] ? $_[1] : 1], $_[0]; 57
53} 58=item $sem->adjust ($diff)
59
60Atomically adds the amount given to the current semaphore count. If the
61count becomes positive, wakes up any waiters. Does not block if the count
62becomes negative, however.
54 63
55=item $sem->down 64=item $sem->down
56 65
57Decrement the counter, therefore "locking" the semaphore. This method 66Decrement the counter, therefore "locking" the semaphore. This method
58waits until the semaphore is available if the counter is zero. 67waits until the semaphore is available if the counter is zero.
59 68
69=item $sem->wait
70
71Similar to C<down>, but does not actually decrement the counter. Instead,
72when this function returns, a following call to C<down> or C<try> is
73guaranteed to succeed without blocking, until the next thread switch
74(C<cede> etc.).
75
76Note that using C<wait> is much less efficient than using C<down>, so try
77to prefer C<down> whenever possible.
78
79=item $sem->wait ($callback)
80
81If you pass a callback argument to C<wait>, it will not wait, but
82immediately return. The callback will be called as soon as the semaphore
83becomes available (which might be instantly), and gets passed the
84semaphore as first argument.
85
86The callback might C<down> the semaphore exactly once, might wake up other
87threads, but is I<NOT> allowed to block (switch to other threads).
88
60=cut 89=cut
61 90
62sub down { 91#=item $status = $sem->timed_down ($timeout)
92#
93#Like C<down>, but returns false if semaphore couldn't be acquired within
94#$timeout seconds, otherwise true.
95
96#sub timed_down {
97# require Coro::Timer;
98# my $timeout = Coro::Timer::timeout ($_[1]);
99#
63 while ($_[0][0] <= 0) { 100# while ($_[0][0] <= 0) {
64 push @{$_[0][1]}, $Coro::current; 101# push @{$_[0][1]}, $Coro::current;
65 Coro::schedule; 102# &Coro::schedule;
103# if ($timeout) {
104# # ugly as hell. slow, too, btw!
105# for (0..$#{$_[0][1]}) {
106# if ($_[0][1][$_] == $Coro::current) {
107# splice @{$_[0][1]}, $_, 1;
108# return;
109# }
110# }
111# die;
112# }
66 } 113# }
114#
67 --$_[0][0]; 115# --$_[0][0];
68} 116# return 1;
117#}
69 118
70=item $sem->up 119=item $sem->up
71 120
72Unlock the semaphore again. 121Unlock the semaphore again.
73
74=cut
75
76sub up {
77 if (++$_[0][0] > 0) {
78 (shift @{$_[0][1]})->ready if @{$_[0][1]};
79 }
80}
81 122
82=item $sem->try 123=item $sem->try
83 124
84Try to C<down> the semaphore. Returns true when this was possible, 125Try to C<down> the semaphore. Returns true when this was possible,
85otherwise return false and leave the semaphore unchanged. 126otherwise return false and leave the semaphore unchanged.
86 127
87=cut
88
89sub try {
90 if ($_[0][0] > 0) {
91 --$_[0][0];
92 return 1;
93 } else {
94 return 0;
95 }
96}
97
98=item $sem->waiters 128=item $sem->waiters
99 129
100In scalar context, returns the number of coroutines waiting for this 130In scalar context, returns the number of threads waiting for this
101semaphore. 131semaphore. Might accidentally cause WW3 if called in other contexts, so
102 132don't use these.
103=cut
104
105sub waiters {
106 @{$_[0][1]};
107}
108 133
109=item $guard = $sem->guard 134=item $guard = $sem->guard
110 135
111This method calls C<down> and then creates a guard object. When the guard 136This method calls C<down> and then creates a guard object. When the guard
112object is destroyed it automatically calls C<up>. 137object is destroyed it automatically calls C<up>.
113 138
114=cut 139=cut
115 140
116sub guard { 141sub guard {
117 &down; 142 &down;
118 # double indirection because bless works on the referenced
119 # object, not (only) on the reference itself.
120 bless \\$_[0], Coro::Semaphore::Guard::; 143 bless [$_[0]], Coro::Semaphore::guard::
121} 144}
122 145
146#=item $guard = $sem->timed_guard ($timeout)
147#
148#Like C<guard>, but returns undef if semaphore couldn't be acquired within
149#$timeout seconds, otherwise the guard object.
150
151#sub timed_guard {
152# &timed_down
153# ? bless \\$_[0], Coro::Semaphore::guard::
154# : ();
155#}
156
123sub Coro::Semaphore::Guard::DESTROY { 157sub Coro::Semaphore::guard::DESTROY {
124 &up(${${$_[0]}}); 158 &up($_[0][0]);
125} 159}
126
1271;
128 160
129=back 161=back
130 162
131=head1 AUTHOR 163=head1 AUTHOR
132 164
133 Marc Lehmann <pcg@goof.com> 165 Marc Lehmann <schmorp@schmorp.de>
134 http://www.goof.com/pcg/marc/ 166 http://home.schmorp.de/
135 167
136=cut 168=cut
137 169
1701
171

Diff Legend

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