Debian Codegraph @

upstream/debian-unstable/man3/Thread::Semaphore.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Thread::Semaphore 3perl"
58 .TH Thread::Semaphore 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Thread::Semaphore \- Thread\-safe semaphores
65 .SH VERSION
66 .IX Header "VERSION"
67 This document describes Thread::Semaphore version 2.13
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 5
71 \& use Thread::Semaphore;
72 \& my $s = Thread::Semaphore\->new();
73 \& $s\->down(); # Also known as the semaphore P operation.
74 \& # The guarded section is here
75 \& $s\->up(); # Also known as the semaphore V operation.
76 \&
77 \& # Decrement the semaphore only if it would immediately succeed.
78 \& if ($s\->down_nb()) {
79 \& # The guarded section is here
80 \& $s\->up();
81 \& }
82 \&
83 \& # Forcefully decrement the semaphore even if its count goes below 0.
84 \& $s\->down_force();
85 \&
86 \& # The default value for semaphore operations is 1
87 \& my $s = Thread::Semaphore\->new($initial_value);
88 \& $s\->down($down_value);
89 \& $s\->up($up_value);
90 \& if ($s\->down_nb($down_value)) {
91 \& ...
92 \& $s\->up($up_value);
93 \& }
94 \& $s\->down_force($down_value);
95 .Ve
96 .SH DESCRIPTION
97 .IX Header "DESCRIPTION"
98 Semaphores provide a mechanism to regulate access to resources. Unlike
99 locks, semaphores aren't tied to particular scalars, and so may be used to
100 control access to anything you care to use them for.
101 .PP
102 Semaphores don't limit their values to zero and one, so they can be used to
103 control access to some resource that there may be more than one of (e.g.,
104 filehandles). Increment and decrement amounts aren't fixed at one either,
105 so threads can reserve or return multiple resources at once.
106 .SH METHODS
107 .IX Header "METHODS"
108 .IP \->\fBnew()\fR 8
109 .IX Item "->new()"
110 .PD 0
111 .IP \->new(NUMBER) 8
112 .IX Item "->new(NUMBER)"
113 .PD
114 \&\f(CW\*(C`new\*(C'\fR creates a new semaphore, and initializes its count to the specified
115 number (which must be an integer). If no number is specified, the
116 semaphore's count defaults to 1.
117 .IP \->\fBdown()\fR 8
118 .IX Item "->down()"
119 .PD 0
120 .IP \->down(NUMBER) 8
121 .IX Item "->down(NUMBER)"
122 .PD
123 The \f(CW\*(C`down\*(C'\fR method decreases the semaphore's count by the specified number
124 (which must be an integer >= 1), or by one if no number is specified.
125 .Sp
126 If the semaphore's count would drop below zero, this method will block
127 until such time as the semaphore's count is greater than or equal to the
128 amount you're \f(CW\*(C`down\*(C'\fRing the semaphore's count by.
129 .Sp
130 This is the semaphore "P operation" (the name derives from the Dutch
131 word "pak", which means "capture" \-\- the semaphore operations were
132 named by the late Dijkstra, who was Dutch).
133 .IP \->\fBdown_nb()\fR 8
134 .IX Item "->down_nb()"
135 .PD 0
136 .IP \->down_nb(NUMBER) 8
137 .IX Item "->down_nb(NUMBER)"
138 .PD
139 The \f(CW\*(C`down_nb\*(C'\fR method attempts to decrease the semaphore's count by the
140 specified number (which must be an integer >= 1), or by one if no number
141 is specified.
142 .Sp
143 If the semaphore's count would drop below zero, this method will return
144 \&\fIfalse\fR, and the semaphore's count remains unchanged. Otherwise, the
145 semaphore's count is decremented and this method returns \fItrue\fR.
146 .IP \->\fBdown_force()\fR 8
147 .IX Item "->down_force()"
148 .PD 0
149 .IP \->down_force(NUMBER) 8
150 .IX Item "->down_force(NUMBER)"
151 .PD
152 The \f(CW\*(C`down_force\*(C'\fR method decreases the semaphore's count by the specified
153 number (which must be an integer >= 1), or by one if no number is specified.
154 This method does not block, and may cause the semaphore's count to drop
155 below zero.
156 .IP \->down_timed(TIMEOUT) 8
157 .IX Item "->down_timed(TIMEOUT)"
158 .PD 0
159 .IP "\->down_timed(TIMEOUT, NUMBER)" 8
160 .IX Item "->down_timed(TIMEOUT, NUMBER)"
161 .PD
162 The \f(CW\*(C`down_timed\*(C'\fR method attempts to decrease the semaphore's count by 1
163 or by the specified number within the specified timeout period given in
164 seconds (which must be an integer >= 0).
165 .Sp
166 If the semaphore's count would drop below zero, this method will block
167 until either the semaphore's count is greater than or equal to the
168 amount you're \f(CW\*(C`down\*(C'\fRing the semaphore's count by, or until the timeout is
169 reached.
170 .Sp
171 If the timeout is reached, this method will return \fIfalse\fR, and the
172 semaphore's count remains unchanged. Otherwise, the semaphore's count is
173 decremented and this method returns \fItrue\fR.
174 .IP \->\fBup()\fR 8
175 .IX Item "->up()"
176 .PD 0
177 .IP \->up(NUMBER) 8
178 .IX Item "->up(NUMBER)"
179 .PD
180 The \f(CW\*(C`up\*(C'\fR method increases the semaphore's count by the number specified
181 (which must be an integer >= 1), or by one if no number is specified.
182 .Sp
183 This will unblock any thread that is blocked trying to \f(CW\*(C`down\*(C'\fR the
184 semaphore if the \f(CW\*(C`up\*(C'\fR raises the semaphore's count above the amount that
185 the \f(CW\*(C`down\*(C'\fR is trying to decrement it by. For example, if three threads
186 are blocked trying to \f(CW\*(C`down\*(C'\fR a semaphore by one, and another thread \f(CW\*(C`up\*(C'\fRs
187 the semaphore by two, then two of the blocked threads (which two is
188 indeterminate) will become unblocked.
189 .Sp
190 This is the semaphore "V operation" (the name derives from the Dutch
191 word "vrij", which means "release").
192 .SH NOTES
193 .IX Header "NOTES"
194 Semaphores created by Thread::Semaphore can be used in both threaded and
195 non-threaded applications. This allows you to write modules and packages
196 that potentially make use of semaphores, and that will function in either
197 environment.
198 .SH "SEE ALSO"
199 .IX Header "SEE ALSO"
200 Thread::Semaphore on MetaCPAN:
201 <https://metacpan.org/release/Thread\-Semaphore>
202 .PP
203 Code repository for CPAN distribution:
204 <https://github.com/Dual\-Life/Thread\-Semaphore>
205 .PP
206 threads, threads::shared
207 .PP
208 Sample code in the \fIexamples\fR directory of this distribution on CPAN.
209 .SH MAINTAINER
210 .IX Header "MAINTAINER"
211 Jerry D. Hedden, <jdhedden\ AT\ cpan\ DOT\ org>
212 .SH LICENSE
213 .IX Header "LICENSE"
214 This program is free software; you can redistribute it and/or modify it under
215 the same terms as Perl itself.