1 package Thread::Semaphore;
9 use Scalar::Util 1.10 qw(looks_like_number);
11 # Create a new semaphore optionally with specified count (count defaults to 1)
14 my $val :shared = @_ ? shift : 1;
16 ! looks_like_number($val) ||
20 $val = 'undef' if (! defined($val));
21 Carp::croak("Semaphore initializer is not an integer: $val");
23 return bless(\$val, $class);
26 # Decrement a semaphore's count (decrement amount defaults to 1)
30 my $dec = @_ ? shift : 1;
31 if (! defined($dec) ||
32 ! looks_like_number($dec) ||
33 (int($dec) != $dec) ||
37 $dec = 'undef' if (! defined($dec));
38 Carp::croak("Semaphore decrement is not a positive integer: $dec");
40 cond_wait($$sema) until ($$sema >= $dec);
44 # Increment a semaphore's count (increment amount defaults to 1)
48 my $inc = @_ ? shift : 1;
49 if (! defined($inc) ||
50 ! looks_like_number($inc) ||
51 (int($inc) != $inc) ||
55 $inc = 'undef' if (! defined($inc));
56 Carp::croak("Semaphore increment is not a positive integer: $inc");
58 ($$sema += $inc) > 0 and cond_broadcast($$sema);
65 Thread::Semaphore - Thread-safe semaphores
69 This document describes Thread::Semaphore version 2.09
73 use Thread::Semaphore;
74 my $s = Thread::Semaphore->new();
75 $s->down(); # Also known as the semaphore P operation.
76 # The guarded section is here
77 $s->up(); # Also known as the semaphore V operation.
79 # The default semaphore value is 1
80 my $s = Thread::Semaphore-new($initial_value);
81 $s->down($down_value);
86 Semaphores provide a mechanism to regulate access to resources. Unlike
87 locks, semaphores aren't tied to particular scalars, and so may be used to
88 control access to anything you care to use them for.
90 Semaphores don't limit their values to zero and one, so they can be used to
91 control access to some resource that there may be more than one of (e.g.,
92 filehandles). Increment and decrement amounts aren't fixed at one either,
93 so threads can reserve or return multiple resources at once.
103 C<new> creates a new semaphore, and initializes its count to the specified
104 number (which must be an integer). If no number is specified, the
105 semaphore's count defaults to 1.
111 The C<down> method decreases the semaphore's count by the specified number
112 (which must be an integer >= 1), or by one if no number is specified.
114 If the semaphore's count would drop below zero, this method will block
115 until such time as the semaphore's count is greater than or equal to the
116 amount you're C<down>ing the semaphore's count by.
118 This is the semaphore "P operation" (the name derives from the Dutch
119 word "pak", which means "capture" -- the semaphore operations were
120 named by the late Dijkstra, who was Dutch).
126 The C<up> method increases the semaphore's count by the number specified
127 (which must be an integer >= 1), or by one if no number is specified.
129 This will unblock any thread that is blocked trying to C<down> the
130 semaphore if the C<up> raises the semaphore's count above the amount that
131 the C<down> is trying to decrement it by. For example, if three threads
132 are blocked trying to C<down> a semaphore by one, and another thread C<up>s
133 the semaphore by two, then two of the blocked threads (which two is
134 indeterminate) will become unblocked.
136 This is the semaphore "V operation" (the name derives from the Dutch
137 word "vrij", which means "release").
143 Semaphores created by L<Thread::Semaphore> can be used in both threaded and
144 non-threaded applications. This allows you to write modules and packages
145 that potentially make use of semaphores, and that will function in either
150 Thread::Semaphore Discussion Forum on CPAN:
151 L<http://www.cpanforum.com/dist/Thread-Semaphore>
153 Annotated POD for Thread::Semaphore:
154 L<http://annocpan.org/~JDHEDDEN/Thread-Semaphore-2.09/lib/Thread/Semaphore.pm>
157 L<http://code.google.com/p/thread-semaphore/>
159 L<threads>, L<threads::shared>
163 Jerry D. Hedden, S<E<lt>jdhedden AT cpan DOT orgE<gt>>
167 This program is free software; you can redistribute it and/or modify it under
168 the same terms as Perl itself.