File Coverage

blib/lib/Coro/Semaphore.pm
Criterion Covered Total %
statement 8 9 88.8
branch n/a
condition n/a
subroutine 3 4 75.0
pod 1 1 100.0
total 12 14 85.7


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Coro::Semaphore - counting semaphores
4              
5             =head1 SYNOPSIS
6              
7             use Coro;
8              
9             $sig = new Coro::Semaphore [initial value];
10              
11             $sig->down; # wait for signal
12              
13             # ... some other "thread"
14              
15             $sig->up;
16              
17             =head1 DESCRIPTION
18              
19             This module implements counting semaphores. You can initialize a mutex
20             with any level of parallel users, that is, you can initialize a sempahore
21             that can be Ced more than once until it blocks. There is no owner
22             associated with semaphores, so one thread can C it while another can
23             C it (or vice versa), C can be called before C and so on:
24             the semaphore is really just an integer counter that optionally blocks
25             when it is 0.
26              
27             Counting semaphores are typically used to coordinate access to
28             resources, with the semaphore count initialized to the number of free
29             resources. Threads then increment the count when resources are added
30             and decrement the count when resources are removed.
31              
32             You don't have to load C manually, it will be loaded
33             automatically when you C and call the C constructor.
34              
35             =over 4
36              
37             =cut
38              
39             package Coro::Semaphore;
40              
41 5     5   411 use common::sense;
  5         13  
  5         42  
42              
43 5     5   266 use Coro ();
  5         12  
  5         834  
44              
45             our $VERSION = 6.512;
46              
47             =item new [initial count]
48              
49             Creates a new sempahore object with the given initial lock count. The
50             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              
54             =item $sem->count
55              
56             Returns the current semaphore count. The semaphore can be down'ed without
57             blocking when the count is strictly higher than C<0>.
58              
59             =item $sem->adjust ($diff)
60              
61             Atomically adds the amount given to the current semaphore count. If the
62             count becomes positive, wakes up any waiters. Does not block if the count
63             becomes negative, however.
64              
65             =item $sem->down
66              
67             Decrement the counter, therefore "locking" the semaphore. This method
68             waits until the semaphore is available if the counter is zero or less.
69              
70             =item $sem->wait
71              
72             Similar to C, but does not actually decrement the counter. Instead,
73             when this function returns, a following call to C or C is
74             guaranteed to succeed without blocking, until the next thread switch
75             (C etc.).
76              
77             Note that using C is much less efficient than using C, so try
78             to prefer C whenever possible.
79              
80             =item $sem->wait ($callback)
81              
82             If you pass a callback argument to C, it will not wait, but
83             immediately return. The callback will be called as soon as the semaphore
84             becomes available (which might be instantly), and gets passed the
85             semaphore as first argument.
86              
87             The callback might C the semaphore exactly once, might wake up other
88             threads, but is I allowed to block (switch to other threads).
89              
90             =cut
91              
92             #=item $status = $sem->timed_down ($timeout)
93             #
94             #Like C, but returns false if semaphore couldn't be acquired within
95             #$timeout seconds, otherwise true.
96              
97             #sub timed_down {
98             # require Coro::Timer;
99             # my $timeout = Coro::Timer::timeout ($_[1]);
100             #
101             # while ($_[0][0] <= 0) {
102             # push @{$_[0][1]}, $Coro::current;
103             # &Coro::schedule;
104             # if ($timeout) {
105             # # ugly as hell. slow, too, btw!
106             # for (0..$#{$_[0][1]}) {
107             # if ($_[0][1][$_] == $Coro::current) {
108             # splice @{$_[0][1]}, $_, 1;
109             # return;
110             # }
111             # }
112             # die;
113             # }
114             # }
115             #
116             # --$_[0][0];
117             # return 1;
118             #}
119              
120             =item $sem->up
121              
122             Unlock the semaphore again.
123              
124             =item $sem->try
125              
126             Try to C the semaphore. Returns true when this was possible,
127             otherwise return false and leave the semaphore unchanged.
128              
129             =item $sem->waiters
130              
131             In scalar context, returns the number of threads waiting for this
132             semaphore. Might accidentally cause WW3 if called in other contexts, so
133             don't use these.
134              
135             =item $guard = $sem->guard
136              
137             This method calls C and then creates a guard object. When the guard
138             object is destroyed it automatically calls C.
139              
140             =cut
141              
142             sub guard {
143 9     9 1 293 &down;
144 2         14 bless [$_[0]], Coro::Semaphore::guard::
145             }
146              
147             #=item $guard = $sem->timed_guard ($timeout)
148             #
149             #Like C, but returns undef if semaphore couldn't be acquired within
150             #$timeout seconds, otherwise the guard object.
151              
152             #sub timed_guard {
153             # &timed_down
154             # ? bless \\$_[0], Coro::Semaphore::guard::
155             # : ();
156             #}
157              
158             sub Coro::Semaphore::guard::DESTROY {
159 0     0     &up($_[0][0]);
160             }
161              
162             =back
163              
164             =head1 AUTHOR/SUPPORT/CONTACT
165              
166             Marc A. Lehmann
167             http://software.schmorp.de/pkg/Coro.html
168              
169             =cut
170              
171             1
172