This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
threads::shared::queue and semaphore become Thread::Semaphore
[perl5.git] / ext / Thread / Semaphore.pmx
CommitLineData
83272a45
JH
1package Thread::Semaphore;
2use Thread qw(cond_wait cond_broadcast);
0b876b54 3
83272a45 4=head1 NAME
0b876b54 5
83272a45 6Thread::Semaphore - thread-safe semaphores (5.005-threads)
0b876b54 7
83272a45
JH
8=head1 CAVEAT
9
10This Perl installation is using the old unsupported "5.005 threads".
11Use of the old threads model is discouraged.
0b876b54 12
83272a45
JH
13For the whole story about the development of threads in Perl, and why
14you should B<not> be using "old threads" unless you know what you're
15doing, see the CAVEAT of the C<Thread> module.
0b876b54
AB
16
17=head1 SYNOPSIS
18
83272a45
JH
19 use Thread::Semaphore;
20 my $s = new Thread::Semaphore;
0b876b54
AB
21 $s->up; # Also known as the semaphore V -operation.
22 # The guarded section is here
23 $s->down; # Also known as the semaphore P -operation.
24
25 # The default semaphore value is 1.
83272a45 26 my $s = new Thread::Semaphore($initial_value);
0b876b54
AB
27 $s->up($up_value);
28 $s->down($up_value);
29
30=head1 DESCRIPTION
31
32Semaphores provide a mechanism to regulate access to resources. Semaphores,
33unlike locks, aren't tied to particular scalars, and so may be used to
34control access to anything you care to use them for.
35
36Semaphores don't limit their values to zero or one, so they can be used to
83272a45
JH
37control access to some resource that may have more than one of. (For
38example, filehandles) Increment and decrement amounts aren't fixed at one
0b876b54
AB
39either, so threads can reserve or return multiple resources at once.
40
41=head1 FUNCTIONS AND METHODS
42
43=over 8
44
45=item new
46
47=item new NUMBER
48
49C<new> creates a new semaphore, and initializes its count to the passed
50number. If no number is passed, the semaphore's count is set to one.
51
52=item down
53
54=item down NUMBER
55
56The C<down> method decreases the semaphore's count by the specified number,
83272a45 57or one if no number has been specified. If the semaphore's count would drop
0b876b54
AB
58below zero, this method will block until such time that the semaphore's
59count is equal to or larger than the amount you're C<down>ing the
60semaphore's count by.
61
62=item up
63
64=item up NUMBER
65
66The C<up> method increases the semaphore's count by the number specified,
83272a45 67or one if no number's been specified. This will unblock any thread blocked
0b876b54 68trying to C<down> the semaphore if the C<up> raises the semaphore count
83272a45 69above what the C<down>s are trying to decrement it by.
0b876b54
AB
70
71=back
72
73=cut
74
75sub new {
76 my $class = shift;
83272a45 77 my $val = @_ ? shift : 1;
0b876b54
AB
78 bless \$val, $class;
79}
80
83272a45 81sub down : locked : method {
0b876b54 82 my $s = shift;
0b876b54 83 my $inc = @_ ? shift : 1;
83272a45 84 cond_wait $s until $$s >= $inc;
0b876b54
AB
85 $$s -= $inc;
86}
87
83272a45 88sub up : locked : method {
0b876b54 89 my $s = shift;
0b876b54 90 my $inc = @_ ? shift : 1;
83272a45 91 ($$s += $inc) > 0 and cond_broadcast $s;
0b876b54
AB
92}
93
941;