Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Thread::Semaphore.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Thread::Semaphore 3pm"
61 .TH Thread::Semaphore 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Thread::Semaphore \- Thread\-safe semaphores
68 .SH VERSION
69 .IX Header "VERSION"
70 This document describes Thread::Semaphore version 2.13
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 5
74 \& use Thread::Semaphore;
75 \& my $s = Thread::Semaphore\->new();
76 \& $s\->down(); # Also known as the semaphore P operation.
77 \& # The guarded section is here
78 \& $s\->up(); # Also known as the semaphore V operation.
79 \&
80 \& # Decrement the semaphore only if it would immediately succeed.
81 \& if ($s\->down_nb()) {
82 \& # The guarded section is here
83 \& $s\->up();
84 \& }
85 \&
86 \& # Forcefully decrement the semaphore even if its count goes below 0.
87 \& $s\->down_force();
88 \&
89 \& # The default value for semaphore operations is 1
90 \& my $s = Thread::Semaphore\->new($initial_value);
91 \& $s\->down($down_value);
92 \& $s\->up($up_value);
93 \& if ($s\->down_nb($down_value)) {
94 \& ...
95 \& $s\->up($up_value);
96 \& }
97 \& $s\->down_force($down_value);
98 .Ve
99 .SH DESCRIPTION
100 .IX Header "DESCRIPTION"
101 Semaphores provide a mechanism to regulate access to resources. Unlike
102 locks, semaphores aren\*(Aqt tied to particular scalars, and so may be used to
103 control access to anything you care to use them for.
104 .PP
105 Semaphores don\*(Aqt limit their values to zero and one, so they can be used to
106 control access to some resource that there may be more than one of (e.g.,
107 filehandles). Increment and decrement amounts aren\*(Aqt fixed at one either,
108 so threads can reserve or return multiple resources at once.
109 .SH METHODS
110 .IX Header "METHODS"
111 .IP \->\fBnew()\fR 8
112 .IX Item "->new()"
113 .PD 0
114 .IP \->new(NUMBER) 8
115 .IX Item "->new(NUMBER)"
116 .PD
117 \&\f(CW\*(C`new\*(C'\fR creates a new semaphore, and initializes its count to the specified
118 number (which must be an integer). If no number is specified, the
119 semaphore\*(Aqs count defaults to 1.
120 .IP \->\fBdown()\fR 8
121 .IX Item "->down()"
122 .PD 0
123 .IP \->down(NUMBER) 8
124 .IX Item "->down(NUMBER)"
125 .PD
126 The \f(CW\*(C`down\*(C'\fR method decreases the semaphore\*(Aqs count by the specified number
127 (which must be an integer >= 1), or by one if no number is specified.
128 .Sp
129 If the semaphore\*(Aqs count would drop below zero, this method will block
130 until such time as the semaphore\*(Aqs count is greater than or equal to the
131 amount you\*(Aqre \f(CW\*(C`down\*(C'\fRing the semaphore\*(Aqs count by.
132 .Sp
133 This is the semaphore "P operation" (the name derives from the Dutch
134 word "pak", which means "capture" \-\- the semaphore operations were
135 named by the late Dijkstra, who was Dutch).
136 .IP \->\fBdown_nb()\fR 8
137 .IX Item "->down_nb()"
138 .PD 0
139 .IP \->down_nb(NUMBER) 8
140 .IX Item "->down_nb(NUMBER)"
141 .PD
142 The \f(CW\*(C`down_nb\*(C'\fR method attempts to decrease the semaphore\*(Aqs count by the
143 specified number (which must be an integer >= 1), or by one if no number
144 is specified.
145 .Sp
146 If the semaphore\*(Aqs count would drop below zero, this method will return
147 \&\fIfalse\fR, and the semaphore\*(Aqs count remains unchanged. Otherwise, the
148 semaphore\*(Aqs count is decremented and this method returns \fItrue\fR.
149 .IP \->\fBdown_force()\fR 8
150 .IX Item "->down_force()"
151 .PD 0
152 .IP \->down_force(NUMBER) 8
153 .IX Item "->down_force(NUMBER)"
154 .PD
155 The \f(CW\*(C`down_force\*(C'\fR method decreases the semaphore\*(Aqs count by the specified
156 number (which must be an integer >= 1), or by one if no number is specified.
157 This method does not block, and may cause the semaphore\*(Aqs count to drop
158 below zero.
159 .IP \->down_timed(TIMEOUT) 8
160 .IX Item "->down_timed(TIMEOUT)"
161 .PD 0
162 .IP "\->down_timed(TIMEOUT, NUMBER)" 8
163 .IX Item "->down_timed(TIMEOUT, NUMBER)"
164 .PD
165 The \f(CW\*(C`down_timed\*(C'\fR method attempts to decrease the semaphore\*(Aqs count by 1
166 or by the specified number within the specified timeout period given in
167 seconds (which must be an integer >= 0).
168 .Sp
169 If the semaphore\*(Aqs count would drop below zero, this method will block
170 until either the semaphore\*(Aqs count is greater than or equal to the
171 amount you\*(Aqre \f(CW\*(C`down\*(C'\fRing the semaphore\*(Aqs count by, or until the timeout is
172 reached.
173 .Sp
174 If the timeout is reached, this method will return \fIfalse\fR, and the
175 semaphore\*(Aqs count remains unchanged. Otherwise, the semaphore\*(Aqs count is
176 decremented and this method returns \fItrue\fR.
177 .IP \->\fBup()\fR 8
178 .IX Item "->up()"
179 .PD 0
180 .IP \->up(NUMBER) 8
181 .IX Item "->up(NUMBER)"
182 .PD
183 The \f(CW\*(C`up\*(C'\fR method increases the semaphore\*(Aqs count by the number specified
184 (which must be an integer >= 1), or by one if no number is specified.
185 .Sp
186 This will unblock any thread that is blocked trying to \f(CW\*(C`down\*(C'\fR the
187 semaphore if the \f(CW\*(C`up\*(C'\fR raises the semaphore\*(Aqs count above the amount that
188 the \f(CW\*(C`down\*(C'\fR is trying to decrement it by. For example, if three threads
189 are blocked trying to \f(CW\*(C`down\*(C'\fR a semaphore by one, and another thread \f(CW\*(C`up\*(C'\fRs
190 the semaphore by two, then two of the blocked threads (which two is
191 indeterminate) will become unblocked.
192 .Sp
193 This is the semaphore "V operation" (the name derives from the Dutch
194 word "vrij", which means "release").
195 .SH NOTES
196 .IX Header "NOTES"
197 Semaphores created by Thread::Semaphore can be used in both threaded and
198 non\-threaded applications. This allows you to write modules and packages
199 that potentially make use of semaphores, and that will function in either
200 environment.
201 .SH "SEE ALSO"
202 .IX Header "SEE ALSO"
203 Thread::Semaphore on MetaCPAN:
204 <https://metacpan.org/release/Thread\-Semaphore>
205 .PP
206 Code repository for CPAN distribution:
207 <https://github.com/Dual\-Life/Thread\-Semaphore>
208 .PP
209 threads, threads::shared
210 .PP
211 Sample code in the \fIexamples\fR directory of this distribution on CPAN.
212 .SH MAINTAINER
213 .IX Header "MAINTAINER"
214 Jerry D. Hedden, <jdhedden\ AT\ cpan\ DOT\ org>
215 .SH LICENSE
216 .IX Header "LICENSE"
217 This program is free software; you can redistribute it and/or modify it under
218 the same terms as Perl itself.