.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Semaphore 3pm"
.TH Semaphore 3pm "2020-11-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Coro::Semaphore \- counting semaphores
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Coro;
\&
\& $sig = new Coro::Semaphore [initial value];
\&
\& $sig\->down; # wait for signal
\&
\& # ... some other "thread"
\&
\& $sig\->up;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements counting semaphores. You can initialize a mutex
with any level of parallel users, that is, you can initialize a semaphore
that can be \f(CW\*(C`down\*(C'\fRed more than once until it blocks. There is no owner
associated with semaphores, so one thread can \f(CW\*(C`down\*(C'\fR it while another can
\&\f(CW\*(C`up\*(C'\fR it (or vice versa), \f(CW\*(C`up\*(C'\fR can be called before \f(CW\*(C`down\*(C'\fR and so on:
the semaphore is really just an integer counter that optionally blocks
when it is 0.
.PP
Counting semaphores are typically used to coordinate access to
resources, with the semaphore count initialized to the number of free
resources. Threads then increment the count when resources are added
and decrement the count when resources are removed.
.PP
You don't have to load \f(CW\*(C`Coro::Semaphore\*(C'\fR manually, it will be loaded
automatically when you \f(CW\*(C`use Coro\*(C'\fR and call the \f(CW\*(C`new\*(C'\fR constructor.
.IP "new [initial count]" 4
.IX Item "new [initial count]"
Creates a new semaphore object with the given initial lock count. The
default lock count is 1, which means it is unlocked by default. Zero (or
negative values) are also allowed, in which case the semaphore is locked
by default.
.ie n .IP "$sem\->count" 4
.el .IP "\f(CW$sem\fR\->count" 4
.IX Item "$sem->count"
Returns the current semaphore count. The semaphore can be down'ed without
blocking when the count is strictly higher than \f(CW0\fR.
.ie n .IP "$sem\->adjust ($diff)" 4
.el .IP "\f(CW$sem\fR\->adjust ($diff)" 4
.IX Item "$sem->adjust ($diff)"
Atomically adds the amount given to the current semaphore count. If the
count becomes positive, wakes up any waiters. Does not block if the count
becomes negative, however.
.ie n .IP "$sem\->down" 4
.el .IP "\f(CW$sem\fR\->down" 4
.IX Item "$sem->down"
Decrement the counter, therefore \*(L"locking\*(R" the semaphore. This method
waits until the semaphore is available if the counter is zero or less.
.ie n .IP "$sem\->wait" 4
.el .IP "\f(CW$sem\fR\->wait" 4
.IX Item "$sem->wait"
Similar to \f(CW\*(C`down\*(C'\fR, but does not actually decrement the counter. Instead,
when this function returns, a following call to \f(CW\*(C`down\*(C'\fR or \f(CW\*(C`try\*(C'\fR is
guaranteed to succeed without blocking, until the next thread switch
(\f(CW\*(C`cede\*(C'\fR etc.).
.Sp
Note that using \f(CW\*(C`wait\*(C'\fR is much less efficient than using \f(CW\*(C`down\*(C'\fR, so try
to prefer \f(CW\*(C`down\*(C'\fR whenever possible.
.ie n .IP "$sem\->wait ($callback)" 4
.el .IP "\f(CW$sem\fR\->wait ($callback)" 4
.IX Item "$sem->wait ($callback)"
If you pass a callback argument to \f(CW\*(C`wait\*(C'\fR, it will not wait, but
immediately return. The callback will be called as soon as the semaphore
becomes available (which might be instantly), and gets passed the
semaphore as first argument.
.Sp
The callback might \f(CW\*(C`down\*(C'\fR the semaphore exactly once, might wake up other
threads, but is \fI\s-1NOT\s0\fR allowed to block (switch to other threads).
.ie n .IP "$sem\->up" 4
.el .IP "\f(CW$sem\fR\->up" 4
.IX Item "$sem->up"
Unlock the semaphore again.
.ie n .IP "$sem\->try" 4
.el .IP "\f(CW$sem\fR\->try" 4
.IX Item "$sem->try"
Try to \f(CW\*(C`down\*(C'\fR the semaphore. Returns true when this was possible,
otherwise return false and leave the semaphore unchanged.
.ie n .IP "$sem\->waiters" 4
.el .IP "\f(CW$sem\fR\->waiters" 4
.IX Item "$sem->waiters"
In scalar context, returns the number of threads waiting for this
semaphore. Might accidentally cause \s-1WW3\s0 if called in other contexts, so
don't use these.
.ie n .IP "$guard = $sem\->guard" 4
.el .IP "\f(CW$guard\fR = \f(CW$sem\fR\->guard" 4
.IX Item "$guard = $sem->guard"
This method calls \f(CW\*(C`down\*(C'\fR and then creates a guard object. When the guard
object is destroyed it automatically calls \f(CW\*(C`up\*(C'\fR.
.SH "AUTHOR/SUPPORT/CONTACT"
.IX Header "AUTHOR/SUPPORT/CONTACT"
.Vb 2
\&   Marc A. Lehmann <schmorp@schmorp.de>
\&   http://software.schmorp.de/pkg/Coro.html
.Ve