Coro/Coro/Semaphore.pm

=head1 NAME

Coro::Semaphore - counting semaphores

=head1 SYNOPSIS

 use Coro;

 $sig = new Coro::Semaphore [initial value];

 $sig->down; # wait for signal

 # ... some other "thread"

 $sig->up;

=head1 DESCRIPTION

This module implements counting semaphores. You can initialize a mutex
with any level of parallel users, that is, you can intialize a sempahore
that can be C<down>ed more than once until it blocks. There is no owner
associated with semaphores, so one thread can C<down> it while another can
C<up> it (or vice versa), C<up> can be called before C<down> and so on:
the semaphore is really just an integer counter that optionally blocks
when it is 0.

Counting semaphores are typically used to coordinate access to
resources, with the semaphore count initialized to the number of free
resources. Threads then increment the count when resources are added
and decrement the count when resources are removed.

You don't have to load C<Coro::Semaphore> manually, it will be loaded
automatically when you C<use Coro> and call the C<new> constructor.

=over 4

=cut

package Coro::Semaphore;

use common::sense;

use Coro ();

our $VERSION = 6.29;

=item new [inital count]

Creates a new sempahore object with the given initial lock count. The
default lock count is 1, which means it is unlocked by default. Zero (or
negative values) are also allowed, in which case the semaphore is locked
by default.

=item $sem->count

Returns the current semaphore count.

=item $sem->adjust ($diff)

Atomically adds the amount given to the current semaphore count. If the
count becomes positive, wakes up any waiters. Does not block if the count
becomes negative, however.

=item $sem->down

Decrement the counter, therefore "locking" the semaphore. This method
waits until the semaphore is available if the counter is zero.

=item $sem->wait

Similar to C<down>, but does not actually decrement the counter. Instead,
when this function returns, a following call to C<down> or C<try> is
guaranteed to succeed without blocking, until the next thread switch
(C<cede> etc.).

Note that using C<wait> is much less efficient than using C<down>, so try
to prefer C<down> whenever possible.

=item $sem->wait ($callback)

If you pass a callback argument to C<wait>, it will not wait, but
immediately return. The callback will be called as soon as the semaphore
becomes available (which might be instantly), and gets passed the
semaphore as first argument.

The callback might C<down> the semaphore exactly once, might wake up other
threads, but is I<NOT> allowed to block (switch to other threads).

=cut

#=item $status = $sem->timed_down ($timeout)
#
#Like C<down>, but returns false if semaphore couldn't be acquired within
#$timeout seconds, otherwise true.

#sub timed_down {
#   require Coro::Timer;
#   my $timeout = Coro::Timer::timeout ($_[1]);
# 
#   while ($_[0][0] <= 0) {
#      push @{$_[0][1]}, $Coro::current;
#      &Coro::schedule;
#      if ($timeout) {
#         # ugly as hell. slow, too, btw!
#         for (0..$#{$_[0][1]}) {
#            if ($_[0][1][$_] == $Coro::current) {
#               splice @{$_[0][1]}, $_, 1;
#               return;
#            }
#         }
#         die;
#      }
#   }
# 
#   --$_[0][0];
#   return 1;
#}

=item $sem->up

Unlock the semaphore again.

=item $sem->try

Try to C<down> the semaphore. Returns true when this was possible,
otherwise return false and leave the semaphore unchanged.

=item $sem->waiters

In scalar context, returns the number of threads waiting for this
semaphore. Might accidentally cause WW3 if called in other contexts, so
don't use these.

=item $guard = $sem->guard

This method calls C<down> and then creates a guard object. When the guard
object is destroyed it automatically calls C<up>.

=cut

sub guard {
   &down;
   bless [$_[0]], Coro::Semaphore::guard::
}

#=item $guard = $sem->timed_guard ($timeout)
#
#Like C<guard>, but returns undef if semaphore couldn't be acquired within
#$timeout seconds, otherwise the guard object.

#sub timed_guard {
#   &timed_down
#      ? bless \\$_[0], Coro::Semaphore::guard::
#      : ();
#}

sub Coro::Semaphore::guard::DESTROY {
   &up($_[0][0]);
}

=back

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

1

Revision:	1.130
Committed:	Wed May 8 00:55:41 2013 UTC (11 years, 1 month ago) by root
Branch:	MAIN
CVS Tags:	rel-6_29
Changes since 1.129:	+1 -1 lines
Log Message:	6.29
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3	root	1.84	Coro::Semaphore - counting semaphores
4	root	1.1
5			=head1 SYNOPSIS
6
7	root	1.110	use Coro;
8	root	1.1
9	root	1.3	$sig = new Coro::Semaphore [initial value];
10	root	1.1
11			$sig->down; # wait for signal
12
13			# ... some other "thread"
14
15			$sig->up;
16
17			=head1 DESCRIPTION
18
19	root	1.16	This module implements counting semaphores. You can initialize a mutex
20	root	1.11	with any level of parallel users, that is, you can intialize a sempahore
21			that can be C<down>ed more than once until it blocks. There is no owner
22	root	1.127	associated with semaphores, so one thread can C<down> it while another can
23			C<up> it (or vice versa), C<up> can be called before C<down> and so on:
24			the semaphore is really just an integer counter that optionally blocks
25			when it is 0.
26	root	1.11
27			Counting semaphores are typically used to coordinate access to
28			resources, with the semaphore count initialized to the number of free
29	root	1.95	resources. Threads then increment the count when resources are added
30	root	1.11	and decrement the count when resources are removed.
31
32	root	1.127	You don't have to load C<Coro::Semaphore> manually, it will be loaded
33			automatically when you C<use Coro> and call the C<new> constructor.
34	root	1.109
35	root	1.1	=over 4
36
37			=cut
38
39			package Coro::Semaphore;
40
41	root	1.102	use common::sense;
42	root	1.20
43	root	1.5	use Coro ();
44	root	1.1
45	root	1.130	our $VERSION = 6.29;
46	root	1.1
47	root	1.16	=item new [inital count]
48	root	1.3
49			Creates a new sempahore object with the given initial lock count. The
50	root	1.11	default lock count is 1, which means it is unlocked by default. Zero (or
51			negative values) are also allowed, in which case the semaphore is locked
52			by default.
53	root	1.3
54	root	1.55	=item $sem->count
55
56			Returns the current semaphore count.
57
58	root	1.56	=item $sem->adjust ($diff)
59
60			Atomically adds the amount given to the current semaphore count. If the
61			count becomes positive, wakes up any waiters. Does not block if the count
62			becomes negative, however.
63
64	root	1.3	=item $sem->down
65
66			Decrement the counter, therefore "locking" the semaphore. This method
67			waits until the semaphore is available if the counter is zero.
68
69	root	1.81	=item $sem->wait
70
71			Similar to C<down>, but does not actually decrement the counter. Instead,
72			when this function returns, a following call to C<down> or C<try> is
73	root	1.95	guaranteed to succeed without blocking, until the next thread switch
74	root	1.81	(C<cede> etc.).
75
76			Note that using C<wait> is much less efficient than using C<down>, so try
77			to prefer C<down> whenever possible.
78
79	root	1.82	=item $sem->wait ($callback)
80
81			If you pass a callback argument to C<wait>, it will not wait, but
82			immediately return. The callback will be called as soon as the semaphore
83			becomes available (which might be instantly), and gets passed the
84			semaphore as first argument.
85
86			The callback might C<down> the semaphore exactly once, might wake up other
87	root	1.95	threads, but is I<NOT> allowed to block (switch to other threads).
88	root	1.82
89	root	1.3	=cut
90
91	root	1.80	#=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			#
100			# while ($_[0][0] <= 0) {
101			# push @{$_[0][1]}, $Coro::current;
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			# }
113			# }
114			#
115			# --$_[0][0];
116			# return 1;
117			#}
118	root	1.1
119	root	1.3	=item $sem->up
120
121			Unlock the semaphore again.
122
123			=item $sem->try
124
125			Try to C<down> the semaphore. Returns true when this was possible,
126			otherwise return false and leave the semaphore unchanged.
127
128	root	1.15	=item $sem->waiters
129
130	root	1.95	In scalar context, returns the number of threads waiting for this
131	root	1.128	semaphore. Might accidentally cause WW3 if called in other contexts, so
132			don't use these.
133	root	1.15
134	root	1.12	=item $guard = $sem->guard
135
136			This method calls C<down> and then creates a guard object. When the guard
137			object is destroyed it automatically calls C<up>.
138
139			=cut
140
141			sub guard {
142	root	1.16	&down;
143	root	1.90	bless [$_[0]], Coro::Semaphore::guard::
144	root	1.25	}
145
146	root	1.80	#=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	root	1.12
157	root	1.25	sub Coro::Semaphore::guard::DESTROY {
158	root	1.90	&up($_[0][0]);
159	root	1.1	}
160
161			=back
162
163			=head1 AUTHOR
164
165	root	1.44	Marc Lehmann <schmorp@schmorp.de>
166	root	1.42	http://home.schmorp.de/
167	root	1.1
168			=cut
169
170	root	1.51	1
171