semaphore.3

多线程库

.\" Copyright (c) 1999-2000 Orn E. Hansen <[e-mail]>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\"                                                                            
.TH THREADS 3 "10 Feb 2000" "Threads 2.0" "Threads C++ Library"
.SH NAME
semaphore \- A class, for process synchronisation.
.SH SYNOPSIS
.B        #include <thread.h>
.sp 2
.B        ....
.sp 0
.B        semaphore sem(attributes::process_private);
,so 0
.B        ....
.SH DESCRIPTION
The
.I semaphore
class is a part of the threads C++ library that focuses on
simplifying program threading.

The semaphore class is a complete class, that provides the primitive
method of semaphore synchronisation of processes.  It can work in
a shared, as well as local environment.

Semaphores can be created using either
.I attributes::process_shared
initialisation or
.I attributes::process_private
each of which will give it a different working scope.  In a shared
environment, the scope of the semaphore, is open to all processes
who have permission and address it at equal resource identification.

A semaphore, is a class that initially has a count of zero and where
other processes or threads, can wait until it enters a state of 
non zero.  Thus synchronizing the state of the waiting process
with the one posting the value to the semaphore.  A few methods
are provided to create this functionality.

.LP
These methods are listed here, with some explanation on how they
function.

.TP 12
.B post()
This will post incriment the count of the semaphore, by one.  If any
processes are waiting on the semaphore, when its state is updated, they
will be awakened.

.TP 12
.B wait()
Wait for the semaphore to reach a value of non-zero, and then decriment
its count by one.  Return the actual count of the semaphore, upon return.

.TP 12
.B trywait()
This will evaluate the state of the semaphore, and if it is non-zero
the semaphore will be decremented by one.  In each case, the process
will return immediately with the actual semaphore count.  A value of
-1 means, that the semaphore is already at zero.

.LP
In a shared environment, it may be desired that semaphore
resources be addressed differently from other resources belonging
to a process.

.TP 12
.B project_part(const char *)
Give all resources that are of type semaphore, a name
that identifies them seperately, yet still branched from the
main process.  The passed arguement is a branch name, that will
identify all created semaphores.  This is a static
method, that will apply to all semaphores created after
the call.

.LP
Maybe the most useful case for a semaphore, is in the initalization
of a threaded class.

One should note, that a threaded class will upon creation run its
initalization method and the
.I thread(void *)
method at the same time.  This will mean, that upon start some 
variables that will be initialized in the constructor are not
available at the beginning of the thread.  To make the thread
actually wait for the constructor, a
.I semaphore
is a good choice.  A simple example follows:

.nf
       #include <thread.h>

       class mythread : public pthread {
         private:
            semaphore sem;
            int variable;

         public:
           mythread() {
             variable = <some value>;
             sem.post();     // Last instruction in constructor
         };
         ~mythread() { };

         int thread(void *) {
           sem.wait();       // wait for constructor
           // variables are now initialized
         }
       }
.fi

.LP
In the above example, the thread has secured that its local variables
are initialized before it continues its processing.  In many cases, the
thread doesn't need any global variables, it may be using local
variables that it doesn't want to share.  In this case, the user may
want the thread to run off immediately, where the above method
is redunant.

But in many cases, there are several variables that will be shared
between threads.  In these cases, synchronized access to these
variables are a necessity for a successful operation.

.LP
Suggestions and questions about the threads library should be
directed to
.IP
[e-mail]

.LP
Ir, to the specified author below. The threads home page is located at:

.IP
http://user.tninet.se/~dpn659b/threads.html

.LP
.SH AUTHOR
Version 2.0
Copyright (C) 1999-2000 Orn E. Hansen <[e-mail]>.
.LP
Thanks to those who reported their suggestions on how to
improve the threads library.