mutex.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
mutex \- A class, for process synchronisation.
.SH SYNOPSIS
.B        #include <thread.h>
.sp 2
.B        ...
.sp 0
.B        mutex mut(attributes::process_private)
.sp 0
.B        ...
.SH DESCRIPTION
The
.I mutex
class is a part of the threads C++ library that focuses on
simplifying program threading.

Mutexes provide the means of exclusive access to shared resources
in a parallel environment.  The mutexes created, can be either
created with the
.I attributes::process_shared
attribute, to make the mutex shared between processes, or with
.I attributes::process_private
as shown in the synopsis.  That will make the mutex private to the
specified process and its threads.

For synchronized access, methods are provided to lock and unlock
the mutex and to test and see if it is locked by another process.

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

.TP 12
.B lock()
This will try and lock the mutex, and return a 0 value to the
calling process if successful.  If not successful, the method
will supsend the calling process, until the mutex is unlocked
and then return.

The behaviour here, is greatly dependant on the kind of mutex
that has been declared.  See
.I kind()
for further information on the mutex kinds available.

.TP 12
.B trylock()
This method will try and lock the mutex, if successful it will
return with a 0 value to signify success.  Else it will return
a EBUSY value, if the mutex is locked by another process.  There
are other return values possible,  such as EDEADLK wich is
possible if the mutex is a
.I mutex_kind::errorcheck
and the process trying to lock it is the same as the one who
already has it locked.

.TP 12
.B unlock()
If the mutex is locked, and the process calling the method is the
owner of the lock, it will be unlocked and a 0 value returned to
signify a successfull unlock operation.  If the mutex is locked
by another process, a EBUSY value will be returned unless the
mutex is a
.I mutex_kind::errorcheck
in which casse the returned value will be EPERM to signify that
there is no permission to unlock it.

.TP 12
.B kind()
This method tells the calling process the kind of mutex, it is
communicating with.  The possible values are:

.RS 12

.TP 12
.I fast 
the mutex can be locked only once.
.TP 12
.I recursive 
the mutex can be locked several times by its owner.
.TP 12
.I errorcheck 
same as fast, but does some simple checking.

.RE

.TP 12
.B kind(mutex::mutex_kind)
Sets the mutex kind to the paremeter passed, and returns the
value the mutex was set to prior to the call.  This enables
a program to set the
.I errorcheck
kind, and returning it to its original state after use.

.LP
In a shared environment, it may be desired that mutex variable
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 mutex, 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 mutexes.  This is a static
method, that will apply to all mutexes created after
the call.

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

.LP
Or, 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.