Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 1232 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man1/perlthrtut.1 b/upstream/debian-unstable/man1/perlthrtut.1
new file mode 100644
index 00000000..9e7a5465
--- /dev/null
+++ b/upstream/debian-unstable/man1/perlthrtut.1
@@ -0,0 +1,1232 @@
+.\" -*- 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 "PERLTHRTUT 1"
+.TH PERLTHRTUT 1 2024-01-12 "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
+perlthrtut \- Tutorial on threads in Perl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This tutorial describes the use of Perl interpreter threads (sometimes
+referred to as \fIithreads\fR).  In this
+model, each thread runs in its own Perl interpreter, and any data sharing
+between threads must be explicit.  The user-level interface for \fIithreads\fR
+uses the threads class.
+.PP
+\&\fBNOTE\fR: There was another older Perl threading flavor called the 5.005 model
+that used the threads class.  This old model was known to have problems, is
+deprecated, and was removed for release 5.10.  You are
+strongly encouraged to migrate any existing 5.005 threads code to the new
+model as soon as possible.
+.PP
+You can see which (or neither) threading flavour you have by
+running \f(CW\*(C`perl \-V\*(C'\fR and looking at the \f(CW\*(C`Platform\*(C'\fR section.
+If you have \f(CW\*(C`useithreads=define\*(C'\fR you have ithreads, if you
+have \f(CW\*(C`use5005threads=define\*(C'\fR you have 5.005 threads.
+If you have neither, you don't have any thread support built in.
+If you have both, you are in trouble.
+.PP
+The threads and threads::shared modules are included in the core Perl
+distribution.  Additionally, they are maintained as a separate modules on
+CPAN, so you can check there for any updates.
+.SH "What Is A Thread Anyway?"
+.IX Header "What Is A Thread Anyway?"
+A thread is a flow of control through a program with a single
+execution point.
+.PP
+Sounds an awful lot like a process, doesn't it? Well, it should.
+Threads are one of the pieces of a process.  Every process has at least
+one thread and, up until now, every process running Perl had only one
+thread.  With 5.8, though, you can create extra threads.  We're going
+to show you how, when, and why.
+.SH "Threaded Program Models"
+.IX Header "Threaded Program Models"
+There are three basic ways that you can structure a threaded
+program.  Which model you choose depends on what you need your program
+to do.  For many non-trivial threaded programs, you'll need to choose
+different models for different pieces of your program.
+.SS Boss/Worker
+.IX Subsection "Boss/Worker"
+The boss/worker model usually has one \fIboss\fR thread and one or more
+\&\fIworker\fR threads.  The boss thread gathers or generates tasks that need
+to be done, then parcels those tasks out to the appropriate worker
+thread.
+.PP
+This model is common in GUI and server programs, where a main thread
+waits for some event and then passes that event to the appropriate
+worker threads for processing.  Once the event has been passed on, the
+boss thread goes back to waiting for another event.
+.PP
+The boss thread does relatively little work.  While tasks aren't
+necessarily performed faster than with any other method, it tends to
+have the best user-response times.
+.SS "Work Crew"
+.IX Subsection "Work Crew"
+In the work crew model, several threads are created that do
+essentially the same thing to different pieces of data.  It closely
+mirrors classical parallel processing and vector processors, where a
+large array of processors do the exact same thing to many pieces of
+data.
+.PP
+This model is particularly useful if the system running the program
+will distribute multiple threads across different processors.  It can
+also be useful in ray tracing or rendering engines, where the
+individual threads can pass on interim results to give the user visual
+feedback.
+.SS Pipeline
+.IX Subsection "Pipeline"
+The pipeline model divides up a task into a series of steps, and
+passes the results of one step on to the thread processing the
+next.  Each thread does one thing to each piece of data and passes the
+results to the next thread in line.
+.PP
+This model makes the most sense if you have multiple processors so two
+or more threads will be executing in parallel, though it can often
+make sense in other contexts as well.  It tends to keep the individual
+tasks small and simple, as well as allowing some parts of the pipeline
+to block (on I/O or system calls, for example) while other parts keep
+going.  If you're running different parts of the pipeline on different
+processors you may also take advantage of the caches on each
+processor.
+.PP
+This model is also handy for a form of recursive programming where,
+rather than having a subroutine call itself, it instead creates
+another thread.  Prime and Fibonacci generators both map well to this
+form of the pipeline model. (A version of a prime number generator is
+presented later on.)
+.SH "What kind of threads are Perl threads?"
+.IX Header "What kind of threads are Perl threads?"
+If you have experience with other thread implementations, you might
+find that things aren't quite what you expect.  It's very important to
+remember when dealing with Perl threads that \fIPerl Threads Are Not X
+Threads\fR for all values of X.  They aren't POSIX threads, or
+DecThreads, or Java's Green threads, or Win32 threads.  There are
+similarities, and the broad concepts are the same, but if you start
+looking for implementation details you're going to be either
+disappointed or confused.  Possibly both.
+.PP
+This is not to say that Perl threads are completely different from
+everything that's ever come before. They're not.  Perl's threading
+model owes a lot to other thread models, especially POSIX.  Just as
+Perl is not C, though, Perl threads are not POSIX threads.  So if you
+find yourself looking for mutexes, or thread priorities, it's time to
+step back a bit and think about what you want to do and how Perl can
+do it.
+.PP
+However, it is important to remember that Perl threads cannot magically
+do things unless your operating system's threads allow it. So if your
+system blocks the entire process on \f(CWsleep()\fR, Perl usually will, as well.
+.PP
+\&\fBPerl Threads Are Different.\fR
+.SH "Thread-Safe Modules"
+.IX Header "Thread-Safe Modules"
+The addition of threads has changed Perl's internals
+substantially. There are implications for people who write
+modules with XS code or external libraries. However, since Perl data is
+not shared among threads by default, Perl modules stand a high chance of
+being thread-safe or can be made thread-safe easily.  Modules that are not
+tagged as thread-safe should be tested or code reviewed before being used
+in production code.
+.PP
+Not all modules that you might use are thread-safe, and you should
+always assume a module is unsafe unless the documentation says
+otherwise.  This includes modules that are distributed as part of the
+core.  Threads are a relatively new feature, and even some of the standard
+modules aren't thread-safe.
+.PP
+Even if a module is thread-safe, it doesn't mean that the module is optimized
+to work well with threads. A module could possibly be rewritten to utilize
+the new features in threaded Perl to increase performance in a threaded
+environment.
+.PP
+If you're using a module that's not thread-safe for some reason, you
+can protect yourself by using it from one, and only one thread at all.
+If you need multiple threads to access such a module, you can use semaphores and
+lots of programming discipline to control access to it.  Semaphores
+are covered in "Basic semaphores".
+.PP
+See also "Thread-Safety of System Libraries".
+.SH "Thread Basics"
+.IX Header "Thread Basics"
+The threads module provides the basic functions you need to write
+threaded programs.  In the following sections, we'll cover the basics,
+showing you what you need to do to create a threaded program.   After
+that, we'll go over some of the features of the threads module that
+make threaded programming easier.
+.SS "Basic Thread Support"
+.IX Subsection "Basic Thread Support"
+Thread support is a Perl compile-time option. It's something that's
+turned on or off when Perl is built at your site, rather than when
+your programs are compiled. If your Perl wasn't compiled with thread
+support enabled, then any attempt to use threads will fail.
+.PP
+Your programs can use the Config module to check whether threads are
+enabled. If your program can't run without them, you can say something
+like:
+.PP
+.Vb 3
+\&    use Config;
+\&    $Config{useithreads} or
+\&        die(\*(AqRecompile Perl with threads to run this program.\*(Aq);
+.Ve
+.PP
+A possibly-threaded program using a possibly-threaded module might
+have code like this:
+.PP
+.Vb 2
+\&    use Config;
+\&    use MyMod;
+\&
+\&    BEGIN {
+\&        if ($Config{useithreads}) {
+\&            # We have threads
+\&            require MyMod_threaded;
+\&            import MyMod_threaded;
+\&        } else {
+\&            require MyMod_unthreaded;
+\&            import MyMod_unthreaded;
+\&        }
+\&    }
+.Ve
+.PP
+Since code that runs both with and without threads is usually pretty
+messy, it's best to isolate the thread-specific code in its own
+module.  In our example above, that's what \f(CW\*(C`MyMod_threaded\*(C'\fR is, and it's
+only imported if we're running on a threaded Perl.
+.SS "A Note about the Examples"
+.IX Subsection "A Note about the Examples"
+In a real situation, care should be taken that all threads are finished
+executing before the program exits.  That care has \fBnot\fR been taken in these
+examples in the interest of simplicity.  Running these examples \fIas is\fR will
+produce error messages, usually caused by the fact that there are still
+threads running when the program exits.  You should not be alarmed by this.
+.SS "Creating Threads"
+.IX Subsection "Creating Threads"
+The threads module provides the tools you need to create new
+threads.  Like any other module, you need to tell Perl that you want to use
+it; \f(CW\*(C`use threads;\*(C'\fR imports all the pieces you need to create basic
+threads.
+.PP
+The simplest, most straightforward way to create a thread is with \f(CWcreate()\fR:
+.PP
+.Vb 1
+\&    use threads;
+\&
+\&    my $thr = threads\->create(\e&sub1);
+\&
+\&    sub sub1 {
+\&        print("In the thread\en");
+\&    }
+.Ve
+.PP
+The \f(CWcreate()\fR method takes a reference to a subroutine and creates a new
+thread that starts executing in the referenced subroutine.  Control
+then passes both to the subroutine and the caller.
+.PP
+If you need to, your program can pass parameters to the subroutine as
+part of the thread startup.  Just include the list of parameters as
+part of the \f(CW\*(C`threads\->create()\*(C'\fR call, like this:
+.PP
+.Vb 1
+\&    use threads;
+\&
+\&    my $Param3 = \*(Aqfoo\*(Aq;
+\&    my $thr1 = threads\->create(\e&sub1, \*(AqParam 1\*(Aq, \*(AqParam 2\*(Aq, $Param3);
+\&    my @ParamList = (42, \*(AqHello\*(Aq, 3.14);
+\&    my $thr2 = threads\->create(\e&sub1, @ParamList);
+\&    my $thr3 = threads\->create(\e&sub1, qw(Param1 Param2 Param3));
+\&
+\&    sub sub1 {
+\&        my @InboundParameters = @_;
+\&        print("In the thread\en");
+\&        print(\*(AqGot parameters >\*(Aq, join(\*(Aq<>\*(Aq,@InboundParameters), "<\en");
+\&    }
+.Ve
+.PP
+The last example illustrates another feature of threads.  You can spawn
+off several threads using the same subroutine.  Each thread executes
+the same subroutine, but in a separate thread with a separate
+environment and potentially separate arguments.
+.PP
+\&\f(CWnew()\fR is a synonym for \f(CWcreate()\fR.
+.SS "Waiting For A Thread To Exit"
+.IX Subsection "Waiting For A Thread To Exit"
+Since threads are also subroutines, they can return values.  To wait
+for a thread to exit and extract any values it might return, you can
+use the \f(CWjoin()\fR method:
+.PP
+.Vb 1
+\&    use threads;
+\&
+\&    my ($thr) = threads\->create(\e&sub1);
+\&
+\&    my @ReturnData = $thr\->join();
+\&    print(\*(AqThread returned \*(Aq, join(\*(Aq, \*(Aq, @ReturnData), "\en");
+\&
+\&    sub sub1 { return (\*(AqFifty\-six\*(Aq, \*(Aqfoo\*(Aq, 2); }
+.Ve
+.PP
+In the example above, the \f(CWjoin()\fR method returns as soon as the thread
+ends.  In addition to waiting for a thread to finish and gathering up
+any values that the thread might have returned, \f(CWjoin()\fR also performs
+any OS cleanup necessary for the thread.  That cleanup might be
+important, especially for long-running programs that spawn lots of
+threads.  If you don't want the return values and don't want to wait
+for the thread to finish, you should call the \f(CWdetach()\fR method
+instead, as described next.
+.PP
+NOTE: In the example above, the thread returns a list, thus necessitating
+that the thread creation call be made in list context (i.e., \f(CW\*(C`my ($thr)\*(C'\fR).
+See "$thr\->\fBjoin()\fR" in threads and "THREAD CONTEXT" in threads for more
+details on thread context and return values.
+.SS "Ignoring A Thread"
+.IX Subsection "Ignoring A Thread"
+\&\f(CWjoin()\fR does three things: it waits for a thread to exit, cleans up
+after it, and returns any data the thread may have produced.  But what
+if you're not interested in the thread's return values, and you don't
+really care when the thread finishes? All you want is for the thread
+to get cleaned up after when it's done.
+.PP
+In this case, you use the \f(CWdetach()\fR method.  Once a thread is detached,
+it'll run until it's finished; then Perl will clean up after it
+automatically.
+.PP
+.Vb 1
+\&    use threads;
+\&
+\&    my $thr = threads\->create(\e&sub1);   # Spawn the thread
+\&
+\&    $thr\->detach();   # Now we officially don\*(Aqt care any more
+\&
+\&    sleep(15);        # Let thread run for awhile
+\&
+\&    sub sub1 {
+\&        my $count = 0;
+\&        while (1) {
+\&            $count++;
+\&            print("\e$count is $count\en");
+\&            sleep(1);
+\&        }
+\&    }
+.Ve
+.PP
+Once a thread is detached, it may not be joined, and any return data
+that it might have produced (if it was done and waiting for a join) is
+lost.
+.PP
+\&\f(CWdetach()\fR can also be called as a class method to allow a thread to
+detach itself:
+.PP
+.Vb 1
+\&    use threads;
+\&
+\&    my $thr = threads\->create(\e&sub1);
+\&
+\&    sub sub1 {
+\&        threads\->detach();
+\&        # Do more work
+\&    }
+.Ve
+.SS "Process and Thread Termination"
+.IX Subsection "Process and Thread Termination"
+With threads one must be careful to make sure they all have a chance to
+run to completion, assuming that is what you want.
+.PP
+An action that terminates a process will terminate \fIall\fR running
+threads.  \fBdie()\fR and \fBexit()\fR have this property,
+and perl does an exit when the main thread exits,
+perhaps implicitly by falling off the end of your code,
+even if that's not what you want.
+.PP
+As an example of this case, this code prints the message
+"Perl exited with active threads: 2 running and unjoined":
+.PP
+.Vb 8
+\&    use threads;
+\&    my $thr1 = threads\->new(\e&thrsub, "test1");
+\&    my $thr2 = threads\->new(\e&thrsub, "test2");
+\&    sub thrsub {
+\&       my ($message) = @_;
+\&       sleep 1;
+\&       print "thread $message\en";
+\&    }
+.Ve
+.PP
+But when the following lines are added at the end:
+.PP
+.Vb 2
+\&    $thr1\->join();
+\&    $thr2\->join();
+.Ve
+.PP
+it prints two lines of output, a perhaps more useful outcome.
+.SH "Threads And Data"
+.IX Header "Threads And Data"
+Now that we've covered the basics of threads, it's time for our next
+topic: Data.  Threading introduces a couple of complications to data
+access that non-threaded programs never need to worry about.
+.SS "Shared And Unshared Data"
+.IX Subsection "Shared And Unshared Data"
+The biggest difference between Perl \fIithreads\fR and the old 5.005 style
+threading, or for that matter, to most other threading systems out there,
+is that by default, no data is shared. When a new Perl thread is created,
+all the data associated with the current thread is copied to the new
+thread, and is subsequently private to that new thread!
+This is similar in feel to what happens when a Unix process forks,
+except that in this case, the data is just copied to a different part of
+memory within the same process rather than a real fork taking place.
+.PP
+To make use of threading, however, one usually wants the threads to share
+at least some data between themselves. This is done with the
+threads::shared module and the \f(CW\*(C`:shared\*(C'\fR attribute:
+.PP
+.Vb 2
+\&    use threads;
+\&    use threads::shared;
+\&
+\&    my $foo :shared = 1;
+\&    my $bar = 1;
+\&    threads\->create(sub { $foo++; $bar++; })\->join();
+\&
+\&    print("$foo\en");  # Prints 2 since $foo is shared
+\&    print("$bar\en");  # Prints 1 since $bar is not shared
+.Ve
+.PP
+In the case of a shared array, all the array's elements are shared, and for
+a shared hash, all the keys and values are shared. This places
+restrictions on what may be assigned to shared array and hash elements: only
+simple values or references to shared variables are allowed \- this is
+so that a private variable can't accidentally become shared. A bad
+assignment will cause the thread to die. For example:
+.PP
+.Vb 2
+\&    use threads;
+\&    use threads::shared;
+\&
+\&    my $var          = 1;
+\&    my $svar :shared = 2;
+\&    my %hash :shared;
+\&
+\&    ... create some threads ...
+\&
+\&    $hash{a} = 1;       # All threads see exists($hash{a})
+\&                        # and $hash{a} == 1
+\&    $hash{a} = $var;    # okay \- copy\-by\-value: same effect as previous
+\&    $hash{a} = $svar;   # okay \- copy\-by\-value: same effect as previous
+\&    $hash{a} = \e$svar;  # okay \- a reference to a shared variable
+\&    $hash{a} = \e$var;   # This will die
+\&    delete($hash{a});   # okay \- all threads will see !exists($hash{a})
+.Ve
+.PP
+Note that a shared variable guarantees that if two or more threads try to
+modify it at the same time, the internal state of the variable will not
+become corrupted. However, there are no guarantees beyond this, as
+explained in the next section.
+.SS "Thread Pitfalls: Races"
+.IX Subsection "Thread Pitfalls: Races"
+While threads bring a new set of useful tools, they also bring a
+number of pitfalls.  One pitfall is the race condition:
+.PP
+.Vb 2
+\&    use threads;
+\&    use threads::shared;
+\&
+\&    my $x :shared = 1;
+\&    my $thr1 = threads\->create(\e&sub1);
+\&    my $thr2 = threads\->create(\e&sub2);
+\&
+\&    $thr1\->join();
+\&    $thr2\->join();
+\&    print("$x\en");
+\&
+\&    sub sub1 { my $foo = $x; $x = $foo + 1; }
+\&    sub sub2 { my $bar = $x; $x = $bar + 1; }
+.Ve
+.PP
+What do you think \f(CW$x\fR will be? The answer, unfortunately, is \fIit
+depends\fR. Both \f(CWsub1()\fR and \f(CWsub2()\fR access the global variable \f(CW$x\fR, once
+to read and once to write.  Depending on factors ranging from your
+thread implementation's scheduling algorithm to the phase of the moon,
+\&\f(CW$x\fR can be 2 or 3.
+.PP
+Race conditions are caused by unsynchronized access to shared
+data.  Without explicit synchronization, there's no way to be sure that
+nothing has happened to the shared data between the time you access it
+and the time you update it.  Even this simple code fragment has the
+possibility of error:
+.PP
+.Vb 8
+\&    use threads;
+\&    my $x :shared = 2;
+\&    my $y :shared;
+\&    my $z :shared;
+\&    my $thr1 = threads\->create(sub { $y = $x; $x = $y + 1; });
+\&    my $thr2 = threads\->create(sub { $z = $x; $x = $z + 1; });
+\&    $thr1\->join();
+\&    $thr2\->join();
+.Ve
+.PP
+Two threads both access \f(CW$x\fR.  Each thread can potentially be interrupted
+at any point, or be executed in any order.  At the end, \f(CW$x\fR could be 3
+or 4, and both \f(CW$y\fR and \f(CW$z\fR could be 2 or 3.
+.PP
+Even \f(CW\*(C`$x += 5\*(C'\fR or \f(CW\*(C`$x++\*(C'\fR are not guaranteed to be atomic.
+.PP
+Whenever your program accesses data or resources that can be accessed
+by other threads, you must take steps to coordinate access or risk
+data inconsistency and race conditions. Note that Perl will protect its
+internals from your race conditions, but it won't protect you from you.
+.SH "Synchronization and control"
+.IX Header "Synchronization and control"
+Perl provides a number of mechanisms to coordinate the interactions
+between themselves and their data, to avoid race conditions and the like.
+Some of these are designed to resemble the common techniques used in thread
+libraries such as \f(CW\*(C`pthreads\*(C'\fR; others are Perl-specific. Often, the
+standard techniques are clumsy and difficult to get right (such as
+condition waits). Where possible, it is usually easier to use Perlish
+techniques such as queues, which remove some of the hard work involved.
+.SS "Controlling access: \fBlock()\fP"
+.IX Subsection "Controlling access: lock()"
+The \f(CWlock()\fR function takes a shared variable and puts a lock on it.
+No other thread may lock the variable until the variable is unlocked
+by the thread holding the lock. Unlocking happens automatically
+when the locking thread exits the block that contains the call to the
+\&\f(CWlock()\fR function.  Using \f(CWlock()\fR is straightforward: This example has
+several threads doing some calculations in parallel, and occasionally
+updating a running total:
+.PP
+.Vb 2
+\&    use threads;
+\&    use threads::shared;
+\&
+\&    my $total :shared = 0;
+\&
+\&    sub calc {
+\&        while (1) {
+\&            my $result;
+\&            # (... do some calculations and set $result ...)
+\&            {
+\&                lock($total);  # Block until we obtain the lock
+\&                $total += $result;
+\&            } # Lock implicitly released at end of scope
+\&            last if $result == 0;
+\&        }
+\&    }
+\&
+\&    my $thr1 = threads\->create(\e&calc);
+\&    my $thr2 = threads\->create(\e&calc);
+\&    my $thr3 = threads\->create(\e&calc);
+\&    $thr1\->join();
+\&    $thr2\->join();
+\&    $thr3\->join();
+\&    print("total=$total\en");
+.Ve
+.PP
+\&\f(CWlock()\fR blocks the thread until the variable being locked is
+available.  When \f(CWlock()\fR returns, your thread can be sure that no other
+thread can lock that variable until the block containing the
+lock exits.
+.PP
+It's important to note that locks don't prevent access to the variable
+in question, only lock attempts.  This is in keeping with Perl's
+longstanding tradition of courteous programming, and the advisory file
+locking that \f(CWflock()\fR gives you.
+.PP
+You may lock arrays and hashes as well as scalars.  Locking an array,
+though, will not block subsequent locks on array elements, just lock
+attempts on the array itself.
+.PP
+Locks are recursive, which means it's okay for a thread to
+lock a variable more than once.  The lock will last until the outermost
+\&\f(CWlock()\fR on the variable goes out of scope. For example:
+.PP
+.Vb 2
+\&    my $x :shared;
+\&    doit();
+\&
+\&    sub doit {
+\&        {
+\&            {
+\&                lock($x); # Wait for lock
+\&                lock($x); # NOOP \- we already have the lock
+\&                {
+\&                    lock($x); # NOOP
+\&                    {
+\&                        lock($x); # NOOP
+\&                        lockit_some_more();
+\&                    }
+\&                }
+\&            } # *** Implicit unlock here ***
+\&        }
+\&    }
+\&
+\&    sub lockit_some_more {
+\&        lock($x); # NOOP
+\&    } # Nothing happens here
+.Ve
+.PP
+Note that there is no \f(CWunlock()\fR function \- the only way to unlock a
+variable is to allow it to go out of scope.
+.PP
+A lock can either be used to guard the data contained within the variable
+being locked, or it can be used to guard something else, like a section
+of code. In this latter case, the variable in question does not hold any
+useful data, and exists only for the purpose of being locked. In this
+respect, the variable behaves like the mutexes and basic semaphores of
+traditional thread libraries.
+.SS "A Thread Pitfall: Deadlocks"
+.IX Subsection "A Thread Pitfall: Deadlocks"
+Locks are a handy tool to synchronize access to data, and using them
+properly is the key to safe shared data.  Unfortunately, locks aren't
+without their dangers, especially when multiple locks are involved.
+Consider the following code:
+.PP
+.Vb 1
+\&    use threads;
+\&
+\&    my $x :shared = 4;
+\&    my $y :shared = \*(Aqfoo\*(Aq;
+\&    my $thr1 = threads\->create(sub {
+\&        lock($x);
+\&        sleep(20);
+\&        lock($y);
+\&    });
+\&    my $thr2 = threads\->create(sub {
+\&        lock($y);
+\&        sleep(20);
+\&        lock($x);
+\&    });
+.Ve
+.PP
+This program will probably hang until you kill it.  The only way it
+won't hang is if one of the two threads acquires both locks
+first.  A guaranteed-to-hang version is more complicated, but the
+principle is the same.
+.PP
+The first thread will grab a lock on \f(CW$x\fR, then, after a pause during which
+the second thread has probably had time to do some work, try to grab a
+lock on \f(CW$y\fR.  Meanwhile, the second thread grabs a lock on \f(CW$y\fR, then later
+tries to grab a lock on \f(CW$x\fR.  The second lock attempt for both threads will
+block, each waiting for the other to release its lock.
+.PP
+This condition is called a deadlock, and it occurs whenever two or
+more threads are trying to get locks on resources that the others
+own.  Each thread will block, waiting for the other to release a lock
+on a resource.  That never happens, though, since the thread with the
+resource is itself waiting for a lock to be released.
+.PP
+There are a number of ways to handle this sort of problem.  The best
+way is to always have all threads acquire locks in the exact same
+order.  If, for example, you lock variables \f(CW$x\fR, \f(CW$y\fR, and \f(CW$z\fR, always lock
+\&\f(CW$x\fR before \f(CW$y\fR, and \f(CW$y\fR before \f(CW$z\fR.  It's also best to hold on to locks for
+as short a period of time to minimize the risks of deadlock.
+.PP
+The other synchronization primitives described below can suffer from
+similar problems.
+.SS "Queues: Passing Data Around"
+.IX Subsection "Queues: Passing Data Around"
+A queue is a special thread-safe object that lets you put data in one
+end and take it out the other without having to worry about
+synchronization issues.  They're pretty straightforward, and look like
+this:
+.PP
+.Vb 2
+\&    use threads;
+\&    use Thread::Queue;
+\&
+\&    my $DataQueue = Thread::Queue\->new();
+\&    my $thr = threads\->create(sub {
+\&        while (my $DataElement = $DataQueue\->dequeue()) {
+\&            print("Popped $DataElement off the queue\en");
+\&        }
+\&    });
+\&
+\&    $DataQueue\->enqueue(12);
+\&    $DataQueue\->enqueue("A", "B", "C");
+\&    sleep(10);
+\&    $DataQueue\->enqueue(undef);
+\&    $thr\->join();
+.Ve
+.PP
+You create the queue with \f(CW\*(C`Thread::Queue\->new()\*(C'\fR.  Then you can
+add lists of scalars onto the end with \f(CWenqueue()\fR, and pop scalars off
+the front of it with \f(CWdequeue()\fR.  A queue has no fixed size, and can grow
+as needed to hold everything pushed on to it.
+.PP
+If a queue is empty, \f(CWdequeue()\fR blocks until another thread enqueues
+something.  This makes queues ideal for event loops and other
+communications between threads.
+.SS "Semaphores: Synchronizing Data Access"
+.IX Subsection "Semaphores: Synchronizing Data Access"
+Semaphores are a kind of generic locking mechanism. In their most basic
+form, they behave very much like lockable scalars, except that they
+can't hold data, and that they must be explicitly unlocked. In their
+advanced form, they act like a kind of counter, and can allow multiple
+threads to have the \fIlock\fR at any one time.
+.SS "Basic semaphores"
+.IX Subsection "Basic semaphores"
+Semaphores have two methods, \f(CWdown()\fR and \f(CWup()\fR: \f(CWdown()\fR decrements the resource
+count, while \f(CWup()\fR increments it. Calls to \f(CWdown()\fR will block if the
+semaphore's current count would decrement below zero.  This program
+gives a quick demonstration:
+.PP
+.Vb 2
+\&    use threads;
+\&    use Thread::Semaphore;
+\&
+\&    my $semaphore = Thread::Semaphore\->new();
+\&    my $GlobalVariable :shared = 0;
+\&
+\&    $thr1 = threads\->create(\e&sample_sub, 1);
+\&    $thr2 = threads\->create(\e&sample_sub, 2);
+\&    $thr3 = threads\->create(\e&sample_sub, 3);
+\&
+\&    sub sample_sub {
+\&        my $SubNumber = shift(@_);
+\&        my $TryCount = 10;
+\&        my $LocalCopy;
+\&        sleep(1);
+\&        while ($TryCount\-\-) {
+\&            $semaphore\->down();
+\&            $LocalCopy = $GlobalVariable;
+\&            print("$TryCount tries left for sub $SubNumber "
+\&                 ."(\e$GlobalVariable is $GlobalVariable)\en");
+\&            sleep(2);
+\&            $LocalCopy++;
+\&            $GlobalVariable = $LocalCopy;
+\&            $semaphore\->up();
+\&        }
+\&    }
+\&
+\&    $thr1\->join();
+\&    $thr2\->join();
+\&    $thr3\->join();
+.Ve
+.PP
+The three invocations of the subroutine all operate in sync.  The
+semaphore, though, makes sure that only one thread is accessing the
+global variable at once.
+.SS "Advanced Semaphores"
+.IX Subsection "Advanced Semaphores"
+By default, semaphores behave like locks, letting only one thread
+\&\f(CWdown()\fR them at a time.  However, there are other uses for semaphores.
+.PP
+Each semaphore has a counter attached to it. By default, semaphores are
+created with the counter set to one, \f(CWdown()\fR decrements the counter by
+one, and \f(CWup()\fR increments by one. However, we can override any or all
+of these defaults simply by passing in different values:
+.PP
+.Vb 2
+\&    use threads;
+\&    use Thread::Semaphore;
+\&
+\&    my $semaphore = Thread::Semaphore\->new(5);
+\&                    # Creates a semaphore with the counter set to five
+\&
+\&    my $thr1 = threads\->create(\e&sub1);
+\&    my $thr2 = threads\->create(\e&sub1);
+\&
+\&    sub sub1 {
+\&        $semaphore\->down(5); # Decrements the counter by five
+\&        # Do stuff here
+\&        $semaphore\->up(5); # Increment the counter by five
+\&    }
+\&
+\&    $thr1\->detach();
+\&    $thr2\->detach();
+.Ve
+.PP
+If \f(CWdown()\fR attempts to decrement the counter below zero, it blocks until
+the counter is large enough.  Note that while a semaphore can be created
+with a starting count of zero, any \f(CWup()\fR or \f(CWdown()\fR always changes the
+counter by at least one, and so \f(CW\*(C`$semaphore\->down(0)\*(C'\fR is the same as
+\&\f(CW\*(C`$semaphore\->down(1)\*(C'\fR.
+.PP
+The question, of course, is why would you do something like this? Why
+create a semaphore with a starting count that's not one, or why
+decrement or increment it by more than one? The answer is resource
+availability.  Many resources that you want to manage access for can be
+safely used by more than one thread at once.
+.PP
+For example, let's take a GUI driven program.  It has a semaphore that
+it uses to synchronize access to the display, so only one thread is
+ever drawing at once.  Handy, but of course you don't want any thread
+to start drawing until things are properly set up.  In this case, you
+can create a semaphore with a counter set to zero, and up it when
+things are ready for drawing.
+.PP
+Semaphores with counters greater than one are also useful for
+establishing quotas.  Say, for example, that you have a number of
+threads that can do I/O at once.  You don't want all the threads
+reading or writing at once though, since that can potentially swamp
+your I/O channels, or deplete your process's quota of filehandles.  You
+can use a semaphore initialized to the number of concurrent I/O
+requests (or open files) that you want at any one time, and have your
+threads quietly block and unblock themselves.
+.PP
+Larger increments or decrements are handy in those cases where a
+thread needs to check out or return a number of resources at once.
+.SS "Waiting for a Condition"
+.IX Subsection "Waiting for a Condition"
+The functions \f(CWcond_wait()\fR and \f(CWcond_signal()\fR
+can be used in conjunction with locks to notify
+co-operating threads that a resource has become available. They are
+very similar in use to the functions found in \f(CW\*(C`pthreads\*(C'\fR. However
+for most purposes, queues are simpler to use and more intuitive. See
+threads::shared for more details.
+.SS "Giving up control"
+.IX Subsection "Giving up control"
+There are times when you may find it useful to have a thread
+explicitly give up the CPU to another thread.  You may be doing something
+processor-intensive and want to make sure that the user-interface thread
+gets called frequently.  Regardless, there are times that you might want
+a thread to give up the processor.
+.PP
+Perl's threading package provides the \f(CWyield()\fR function that does
+this. \f(CWyield()\fR is pretty straightforward, and works like this:
+.PP
+.Vb 1
+\&    use threads;
+\&
+\&    sub loop {
+\&        my $thread = shift;
+\&        my $foo = 50;
+\&        while($foo\-\-) { print("In thread $thread\en"); }
+\&        threads\->yield();
+\&        $foo = 50;
+\&        while($foo\-\-) { print("In thread $thread\en"); }
+\&    }
+\&
+\&    my $thr1 = threads\->create(\e&loop, \*(Aqfirst\*(Aq);
+\&    my $thr2 = threads\->create(\e&loop, \*(Aqsecond\*(Aq);
+\&    my $thr3 = threads\->create(\e&loop, \*(Aqthird\*(Aq);
+.Ve
+.PP
+It is important to remember that \f(CWyield()\fR is only a hint to give up the CPU,
+it depends on your hardware, OS and threading libraries what actually happens.
+\&\fBOn many operating systems, yield() is a no-op.\fR  Therefore it is important
+to note that one should not build the scheduling of the threads around
+\&\f(CWyield()\fR calls. It might work on your platform but it won't work on another
+platform.
+.SH "General Thread Utility Routines"
+.IX Header "General Thread Utility Routines"
+We've covered the workhorse parts of Perl's threading package, and
+with these tools you should be well on your way to writing threaded
+code and packages.  There are a few useful little pieces that didn't
+really fit in anyplace else.
+.SS "What Thread Am I In?"
+.IX Subsection "What Thread Am I In?"
+The \f(CW\*(C`threads\->self()\*(C'\fR class method provides your program with a way to
+get an object representing the thread it's currently in.  You can use this
+object in the same way as the ones returned from thread creation.
+.SS "Thread IDs"
+.IX Subsection "Thread IDs"
+\&\f(CWtid()\fR is a thread object method that returns the thread ID of the
+thread the object represents.  Thread IDs are integers, with the main
+thread in a program being 0.  Currently Perl assigns a unique TID to
+every thread ever created in your program, assigning the first thread
+to be created a TID of 1, and increasing the TID by 1 for each new
+thread that's created.  When used as a class method, \f(CW\*(C`threads\->tid()\*(C'\fR
+can be used by a thread to get its own TID.
+.SS "Are These Threads The Same?"
+.IX Subsection "Are These Threads The Same?"
+The \f(CWequal()\fR method takes two thread objects and returns true
+if the objects represent the same thread, and false if they don't.
+.PP
+Thread objects also have an overloaded \f(CW\*(C`==\*(C'\fR comparison so that you can do
+comparison on them as you would with normal objects.
+.SS "What Threads Are Running?"
+.IX Subsection "What Threads Are Running?"
+\&\f(CW\*(C`threads\->list()\*(C'\fR returns a list of thread objects, one for each thread
+that's currently running and not detached.  Handy for a number of things,
+including cleaning up at the end of your program (from the main Perl thread,
+of course):
+.PP
+.Vb 4
+\&    # Loop through all the threads
+\&    foreach my $thr (threads\->list()) {
+\&        $thr\->join();
+\&    }
+.Ve
+.PP
+If some threads have not finished running when the main Perl thread
+ends, Perl will warn you about it and die, since it is impossible for Perl
+to clean up itself while other threads are running.
+.PP
+NOTE:  The main Perl thread (thread 0) is in a \fIdetached\fR state, and so
+does not appear in the list returned by \f(CW\*(C`threads\->list()\*(C'\fR.
+.SH "A Complete Example"
+.IX Header "A Complete Example"
+Confused yet? It's time for an example program to show some of the
+things we've covered.  This program finds prime numbers using threads.
+.PP
+.Vb 10
+\&   1 #!/usr/bin/perl
+\&   2 # prime\-pthread, courtesy of Tom Christiansen
+\&   3
+\&   4 use v5.36;
+\&   5
+\&   6 use threads;
+\&   7 use Thread::Queue;
+\&   8
+\&   9 sub check_num ($upstream, $cur_prime) {
+\&  10     my $kid;
+\&  11     my $downstream = Thread::Queue\->new();
+\&  12     while (my $num = $upstream\->dequeue()) {
+\&  13         next unless ($num % $cur_prime);
+\&  14         if ($kid) {
+\&  15             $downstream\->enqueue($num);
+\&  16         } else {
+\&  17             print("Found prime: $num\en");
+\&  18             $kid = threads\->create(\e&check_num, $downstream, $num);
+\&  19             if (! $kid) {
+\&  20                 warn("Sorry.  Ran out of threads.\en");
+\&  21                 last;
+\&  22             }
+\&  23         }
+\&  24     }
+\&  25     if ($kid) {
+\&  26         $downstream\->enqueue(undef);
+\&  27         $kid\->join();
+\&  28     }
+\&  29 }
+\&  30
+\&  31 my $stream = Thread::Queue\->new(3..1000, undef);
+\&  32 check_num($stream, 2);
+.Ve
+.PP
+This program uses the pipeline model to generate prime numbers.  Each
+thread in the pipeline has an input queue that feeds numbers to be
+checked, a prime number that it's responsible for, and an output queue
+into which it funnels numbers that have failed the check.  If the thread
+has a number that's failed its check and there's no child thread, then
+the thread must have found a new prime number.  In that case, a new
+child thread is created for that prime and stuck on the end of the
+pipeline.
+.PP
+This probably sounds a bit more confusing than it really is, so let's
+go through this program piece by piece and see what it does.  (For
+those of you who might be trying to remember exactly what a prime
+number is, it's a number that's only evenly divisible by itself and 1.)
+.PP
+The bulk of the work is done by the \f(CWcheck_num()\fR subroutine, which
+takes a reference to its input queue and a prime number that it's
+responsible for.  We create a new queue (line 11) and reserve a scalar
+for the thread that we're likely to create later (line 10).
+.PP
+The while loop from line 12 to line 24 grabs a scalar off the input
+queue and checks against the prime this thread is responsible
+for.  Line 13 checks to see if there's a remainder when we divide the
+number to be checked by our prime.  If there is one, the number
+must not be evenly divisible by our prime, so we need to either pass
+it on to the next thread if we've created one (line 15) or create a
+new thread if we haven't.
+.PP
+The new thread creation is line 18.  We pass on to it a reference to
+the queue we've created, and the prime number we've found.  In lines 19
+through 22, we check to make sure that our new thread got created, and
+if not, we stop checking any remaining numbers in the queue.
+.PP
+Finally, once the loop terminates (because we got a 0 or \f(CW\*(C`undef\*(C'\fR in the
+queue, which serves as a note to terminate), we pass on the notice to our
+child, and wait for it to exit if we've created a child (lines 25 and
+28).
+.PP
+Meanwhile, back in the main thread, we first create a queue (line 31) and
+queue up all the numbers from 3 to 1000 for checking, plus a termination
+notice.  Then all we have to do to get the ball rolling is pass the queue
+and the first prime to the \f(CWcheck_num()\fR subroutine (line 32).
+.PP
+That's how it works.  It's pretty simple; as with many Perl programs,
+the explanation is much longer than the program.
+.SH "Different implementations of threads"
+.IX Header "Different implementations of threads"
+Some background on thread implementations from the operating system
+viewpoint.  There are three basic categories of threads: user-mode threads,
+kernel threads, and multiprocessor kernel threads.
+.PP
+User-mode threads are threads that live entirely within a program and
+its libraries.  In this model, the OS knows nothing about threads.  As
+far as it's concerned, your process is just a process.
+.PP
+This is the easiest way to implement threads, and the way most OSes
+start.  The big disadvantage is that, since the OS knows nothing about
+threads, if one thread blocks they all do.  Typical blocking activities
+include most system calls, most I/O, and things like \f(CWsleep()\fR.
+.PP
+Kernel threads are the next step in thread evolution.  The OS knows
+about kernel threads, and makes allowances for them.  The main
+difference between a kernel thread and a user-mode thread is
+blocking.  With kernel threads, things that block a single thread don't
+block other threads.  This is not the case with user-mode threads,
+where the kernel blocks at the process level and not the thread level.
+.PP
+This is a big step forward, and can give a threaded program quite a
+performance boost over non-threaded programs.  Threads that block
+performing I/O, for example, won't block threads that are doing other
+things.  Each process still has only one thread running at once,
+though, regardless of how many CPUs a system might have.
+.PP
+Since kernel threading can interrupt a thread at any time, they will
+uncover some of the implicit locking assumptions you may make in your
+program.  For example, something as simple as \f(CW\*(C`$x = $x + 2\*(C'\fR can behave
+unpredictably with kernel threads if \f(CW$x\fR is visible to other
+threads, as another thread may have changed \f(CW$x\fR between the time it
+was fetched on the right hand side and the time the new value is
+stored.
+.PP
+Multiprocessor kernel threads are the final step in thread
+support.  With multiprocessor kernel threads on a machine with multiple
+CPUs, the OS may schedule two or more threads to run simultaneously on
+different CPUs.
+.PP
+This can give a serious performance boost to your threaded program,
+since more than one thread will be executing at the same time.  As a
+tradeoff, though, any of those nagging synchronization issues that
+might not have shown with basic kernel threads will appear with a
+vengeance.
+.PP
+In addition to the different levels of OS involvement in threads,
+different OSes (and different thread implementations for a particular
+OS) allocate CPU cycles to threads in different ways.
+.PP
+Cooperative multitasking systems have running threads give up control
+if one of two things happen.  If a thread calls a yield function, it
+gives up control.  It also gives up control if the thread does
+something that would cause it to block, such as perform I/O.  In a
+cooperative multitasking implementation, one thread can starve all the
+others for CPU time if it so chooses.
+.PP
+Preemptive multitasking systems interrupt threads at regular intervals
+while the system decides which thread should run next.  In a preemptive
+multitasking system, one thread usually won't monopolize the CPU.
+.PP
+On some systems, there can be cooperative and preemptive threads
+running simultaneously. (Threads running with realtime priorities
+often behave cooperatively, for example, while threads running at
+normal priorities behave preemptively.)
+.PP
+Most modern operating systems support preemptive multitasking nowadays.
+.SH "Performance considerations"
+.IX Header "Performance considerations"
+The main thing to bear in mind when comparing Perl's \fIithreads\fR to other threading
+models is the fact that for each new thread created, a complete copy of
+all the variables and data of the parent thread has to be taken. Thus,
+thread creation can be quite expensive, both in terms of memory usage and
+time spent in creation. The ideal way to reduce these costs is to have a
+relatively short number of long-lived threads, all created fairly early
+on (before the base thread has accumulated too much data). Of course, this
+may not always be possible, so compromises have to be made. However, after
+a thread has been created, its performance and extra memory usage should
+be little different than ordinary code.
+.PP
+Also note that under the current implementation, shared variables
+use a little more memory and are a little slower than ordinary variables.
+.SH "Process-scope Changes"
+.IX Header "Process-scope Changes"
+Note that while threads themselves are separate execution threads and
+Perl data is thread-private unless explicitly shared, the threads can
+affect process-scope state, affecting all the threads.
+.PP
+The most common example of this is changing the current working
+directory using \f(CWchdir()\fR.  One thread calls \f(CWchdir()\fR, and the working
+directory of all the threads changes.
+.PP
+Even more drastic example of a process-scope change is \f(CWchroot()\fR:
+the root directory of all the threads changes, and no thread can
+undo it (as opposed to \f(CWchdir()\fR).
+.PP
+Further examples of process-scope changes include \f(CWumask()\fR and
+changing uids and gids.
+.PP
+Thinking of mixing \f(CWfork()\fR and threads?  Please lie down and wait
+until the feeling passes.  Be aware that the semantics of \f(CWfork()\fR vary
+between platforms.  For example, some Unix systems copy all the current
+threads into the child process, while others only copy the thread that
+called \f(CWfork()\fR. You have been warned!
+.PP
+Similarly, mixing signals and threads may be problematic.
+Implementations are platform-dependent, and even the POSIX
+semantics may not be what you expect (and Perl doesn't even
+give you the full POSIX API).  For example, there is no way to
+guarantee that a signal sent to a multi-threaded Perl application
+will get intercepted by any particular thread.  (However, a recently
+added feature does provide the capability to send signals between
+threads.  See "THREAD SIGNALLING" in threads for more details.)
+.SH "Thread-Safety of System Libraries"
+.IX Header "Thread-Safety of System Libraries"
+Whether various library calls are thread-safe is outside the control
+of Perl.  Calls often suffering from not being thread-safe include:
+\&\f(CWlocaltime()\fR, \f(CWgmtime()\fR,  functions fetching user, group and
+network information (such as \f(CWgetgrent()\fR, \f(CWgethostent()\fR,
+\&\f(CWgetnetent()\fR and so on), \f(CWreaddir()\fR, \f(CWrand()\fR, and \f(CWsrand()\fR. In
+general, calls that depend on some global external state.
+.PP
+If the system Perl is compiled in has thread-safe variants of such
+calls, they will be used.  Beyond that, Perl is at the mercy of
+the thread-safety or \-unsafety of the calls.  Please consult your
+C library call documentation.
+.PP
+On some platforms the thread-safe library interfaces may fail if the
+result buffer is too small (for example the user group databases may
+be rather large, and the reentrant interfaces may have to carry around
+a full snapshot of those databases).  Perl will start with a small
+buffer, but keep retrying and growing the result buffer
+until the result fits.  If this limitless growing sounds bad for
+security or memory consumption reasons you can recompile Perl with
+\&\f(CW\*(C`PERL_REENTRANT_MAXSIZE\*(C'\fR defined to the maximum number of bytes you will
+allow.
+.SH Conclusion
+.IX Header "Conclusion"
+A complete thread tutorial could fill a book (and has, many times),
+but with what we've covered in this introduction, you should be well
+on your way to becoming a threaded Perl expert.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Annotated POD for threads:
+<https://web.archive.org/web/20171028020148/http://annocpan.org/?mode=search&field=Module&name=threads>
+.PP
+Latest version of threads on CPAN:
+<https://metacpan.org/pod/threads>
+.PP
+Annotated POD for threads::shared:
+<https://web.archive.org/web/20171028020148/http://annocpan.org/?mode=search&field=Module&name=threads%3A%3Ashared>
+.PP
+Latest version of threads::shared on CPAN:
+<https://metacpan.org/pod/threads::shared>
+.PP
+Perl threads mailing list:
+<https://lists.perl.org/list/ithreads.html>
+.SH Bibliography
+.IX Header "Bibliography"
+Here's a short bibliography courtesy of Jürgen Christoffel:
+.SS "Introductory Texts"
+.IX Subsection "Introductory Texts"
+Birrell, Andrew D. An Introduction to Programming with
+Threads. Digital Equipment Corporation, 1989, DEC-SRC Research Report
+#35 online as
+<https://www.hpl.hp.com/techreports/Compaq\-DEC/SRC\-RR\-35.pdf>
+(highly recommended)
+.PP
+Robbins, Kay. A., and Steven Robbins. Practical Unix Programming: A
+Guide to Concurrency, Communication, and
+Multithreading. Prentice-Hall, 1996.
+.PP
+Lewis, Bill, and Daniel J. Berg. Multithreaded Programming with
+Pthreads. Prentice Hall, 1997, ISBN 0\-13\-443698\-9 (a well-written
+introduction to threads).
+.PP
+Nelson, Greg (editor). Systems Programming with Modula\-3.  Prentice
+Hall, 1991, ISBN 0\-13\-590464\-1.
+.PP
+Nichols, Bradford, Dick Buttlar, and Jacqueline Proulx Farrell.
+Pthreads Programming. O'Reilly & Associates, 1996, ISBN 156592\-115\-1
+(covers POSIX threads).
+.SS "OS-Related References"
+.IX Subsection "OS-Related References"
+Boykin, Joseph, David Kirschen, Alan Langerman, and Susan
+LoVerso. Programming under Mach. Addison-Wesley, 1994, ISBN
+0\-201\-52739\-1.
+.PP
+Tanenbaum, Andrew S. Distributed Operating Systems. Prentice Hall,
+1995, ISBN 0\-13\-219908\-4 (great textbook).
+.PP
+Silberschatz, Abraham, and Peter B. Galvin. Operating System Concepts,
+4th ed. Addison-Wesley, 1995, ISBN 0\-201\-59292\-4
+.SS "Other References"
+.IX Subsection "Other References"
+Arnold, Ken and James Gosling. The Java Programming Language, 2nd
+ed. Addison-Wesley, 1998, ISBN 0\-201\-31006\-6.
+.PP
+comp.programming.threads FAQ,
+<http://www.serpentine.com/~bos/threads\-faq/>
+.PP
+Le Sergent, T. and B. Berthomieu. "Incremental MultiThreaded Garbage
+Collection on Virtually Shared Memory Architectures" in Memory
+Management: Proc. of the International Workshop IWMM 92, St. Malo,
+France, September 1992, Yves Bekkers and Jacques Cohen, eds. Springer,
+1992, ISBN 3540\-55940\-X (real-life thread applications).
+.PP
+Artur Bergman, "Where Wizards Fear To Tread", June 11, 2002,
+<http://www.perl.com/pub/a/2002/06/11/threads.html>
+.SH Acknowledgements
+.IX Header "Acknowledgements"
+Thanks (in no particular order) to Chaim Frenkel, Steve Fink, Gurusamy
+Sarathy, Ilya Zakharevich, Benjamin Sugars, Jürgen Christoffel, Joshua
+Pritikin, and Alan Burlison, for their help in reality-checking and
+polishing this article.  Big thanks to Tom Christiansen for his rewrite
+of the prime number generator.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Dan Sugalski <dan@sidhe.org>
+.PP
+Slightly modified by Arthur Bergman to fit the new thread model/module.
+.PP
+Reworked slightly by Jörg Walter <jwalt@cpan.org> to be more concise
+about thread-safety of Perl code.
+.PP
+Rearranged slightly by Elizabeth Mattijsen <liz@dijkmat.nl> to put
+less emphasis on \fByield()\fR.
+.SH Copyrights
+.IX Header "Copyrights"
+The original version of this article originally appeared in The Perl
+Journal #10, and is copyright 1998 The Perl Journal. It appears courtesy
+of Jon Orwant and The Perl Journal.  This document may be distributed
+under the same terms as Perl itself.