Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 215 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/Thread::Semaphore.3pm b/upstream/mageia-cauldron/man3pm/Thread::Semaphore.3pm
new file mode 100644
index 00000000..7e0ba5f2
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/Thread::Semaphore.3pm
@@ -0,0 +1,215 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" 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
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    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 "Thread::Semaphore 3pm"
+.TH Thread::Semaphore 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+Thread::Semaphore \- Thread\-safe semaphores
+.SH VERSION
+.IX Header "VERSION"
+This document describes Thread::Semaphore version 2.13
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 5
+\&    use Thread::Semaphore;
+\&    my $s = Thread::Semaphore\->new();
+\&    $s\->down();   # Also known as the semaphore P operation.
+\&    # The guarded section is here
+\&    $s\->up();     # Also known as the semaphore V operation.
+\&
+\&    # Decrement the semaphore only if it would immediately succeed.
+\&    if ($s\->down_nb()) {
+\&        # The guarded section is here
+\&        $s\->up();
+\&    }
+\&
+\&    # Forcefully decrement the semaphore even if its count goes below 0.
+\&    $s\->down_force();
+\&
+\&    # The default value for semaphore operations is 1
+\&    my $s = Thread::Semaphore\->new($initial_value);
+\&    $s\->down($down_value);
+\&    $s\->up($up_value);
+\&    if ($s\->down_nb($down_value)) {
+\&        ...
+\&        $s\->up($up_value);
+\&    }
+\&    $s\->down_force($down_value);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Semaphores provide a mechanism to regulate access to resources.  Unlike
+locks, semaphores aren't tied to particular scalars, and so may be used to
+control access to anything you care to use them for.
+.PP
+Semaphores don't limit their values to zero and one, so they can be used to
+control access to some resource that there may be more than one of (e.g.,
+filehandles).  Increment and decrement amounts aren't fixed at one either,
+so threads can reserve or return multiple resources at once.
+.SH METHODS
+.IX Header "METHODS"
+.IP \->\fBnew()\fR 8
+.IX Item "->new()"
+.PD 0
+.IP \->new(NUMBER) 8
+.IX Item "->new(NUMBER)"
+.PD
+\&\f(CW\*(C`new\*(C'\fR creates a new semaphore, and initializes its count to the specified
+number (which must be an integer).  If no number is specified, the
+semaphore's count defaults to 1.
+.IP \->\fBdown()\fR 8
+.IX Item "->down()"
+.PD 0
+.IP \->down(NUMBER) 8
+.IX Item "->down(NUMBER)"
+.PD
+The \f(CW\*(C`down\*(C'\fR method decreases the semaphore's count by the specified number
+(which must be an integer >= 1), or by one if no number is specified.
+.Sp
+If the semaphore's count would drop below zero, this method will block
+until such time as the semaphore's count is greater than or equal to the
+amount you're \f(CW\*(C`down\*(C'\fRing the semaphore's count by.
+.Sp
+This is the semaphore "P operation" (the name derives from the Dutch
+word "pak", which means "capture" \-\- the semaphore operations were
+named by the late Dijkstra, who was Dutch).
+.IP \->\fBdown_nb()\fR 8
+.IX Item "->down_nb()"
+.PD 0
+.IP \->down_nb(NUMBER) 8
+.IX Item "->down_nb(NUMBER)"
+.PD
+The \f(CW\*(C`down_nb\*(C'\fR method attempts to decrease the semaphore's count by the
+specified number (which must be an integer >= 1), or by one if no number
+is specified.
+.Sp
+If the semaphore's count would drop below zero, this method will return
+\&\fIfalse\fR, and the semaphore's count remains unchanged.  Otherwise, the
+semaphore's count is decremented and this method returns \fItrue\fR.
+.IP \->\fBdown_force()\fR 8
+.IX Item "->down_force()"
+.PD 0
+.IP \->down_force(NUMBER) 8
+.IX Item "->down_force(NUMBER)"
+.PD
+The \f(CW\*(C`down_force\*(C'\fR method decreases the semaphore's count by the specified
+number (which must be an integer >= 1), or by one if no number is specified.
+This method does not block, and may cause the semaphore's count to drop
+below zero.
+.IP \->down_timed(TIMEOUT) 8
+.IX Item "->down_timed(TIMEOUT)"
+.PD 0
+.IP "\->down_timed(TIMEOUT, NUMBER)" 8
+.IX Item "->down_timed(TIMEOUT, NUMBER)"
+.PD
+The \f(CW\*(C`down_timed\*(C'\fR method attempts to decrease the semaphore's count by 1
+or by the specified number within the specified timeout period given in
+seconds (which must be an integer >= 0).
+.Sp
+If the semaphore's count would drop below zero, this method will block
+until either the semaphore's count is greater than or equal to the
+amount you're \f(CW\*(C`down\*(C'\fRing the semaphore's count by, or until the timeout is
+reached.
+.Sp
+If the timeout is reached, this method will return \fIfalse\fR, and the
+semaphore's count remains unchanged.  Otherwise, the semaphore's count is
+decremented and this method returns \fItrue\fR.
+.IP \->\fBup()\fR 8
+.IX Item "->up()"
+.PD 0
+.IP \->up(NUMBER) 8
+.IX Item "->up(NUMBER)"
+.PD
+The \f(CW\*(C`up\*(C'\fR method increases the semaphore's count by the number specified
+(which must be an integer >= 1), or by one if no number is specified.
+.Sp
+This will unblock any thread that is blocked trying to \f(CW\*(C`down\*(C'\fR the
+semaphore if the \f(CW\*(C`up\*(C'\fR raises the semaphore's count above the amount that
+the \f(CW\*(C`down\*(C'\fR is trying to decrement it by.  For example, if three threads
+are blocked trying to \f(CW\*(C`down\*(C'\fR a semaphore by one, and another thread \f(CW\*(C`up\*(C'\fRs
+the semaphore by two, then two of the blocked threads (which two is
+indeterminate) will become unblocked.
+.Sp
+This is the semaphore "V operation" (the name derives from the Dutch
+word "vrij", which means "release").
+.SH NOTES
+.IX Header "NOTES"
+Semaphores created by Thread::Semaphore can be used in both threaded and
+non-threaded applications.  This allows you to write modules and packages
+that potentially make use of semaphores, and that will function in either
+environment.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Thread::Semaphore on MetaCPAN:
+<https://metacpan.org/release/Thread\-Semaphore>
+.PP
+Code repository for CPAN distribution:
+<https://github.com/Dual\-Life/Thread\-Semaphore>
+.PP
+threads, threads::shared
+.PP
+Sample code in the \fIexamples\fR directory of this distribution on CPAN.
+.SH MAINTAINER
+.IX Header "MAINTAINER"
+Jerry D. Hedden, <jdhedden\ AT\ cpan\ DOT\ org>
+.SH LICENSE
+.IX Header "LICENSE"
+This program is free software; you can redistribute it and/or modify it under
+the same terms as Perl itself.