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

The cond class, provides means to pass conditions over to a different
thread or process.  It can be initialized as working only within the
process of its creation, and associated threads.  Or to share its
resources with other processes that so desire.  This can be accomplished
by specifying either
.I attributes::process_shared
as the initializing parameter, to create a shared condition variable,
or
.I attributes::process_private
as shown in the synopsis above, to create a variable that is only
viewable within the current process tree.

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

.TP 12
.B wait(mutex&)
The mutex passed, is assumed locked on entry and owned by the
calling process.  The method then unlocks the mutex, and enters
a state of suspension, until a signal is received through the
.I signal()
method, when it will relock the mutex and return to the calling
process.

.TP 12
.B timedwait(mutex&, struct timespec *)
Again, as in above, the mutex is assumed locked and owned by the
calling process ( it is upon the user to make sure that this is
the case ).  The process immediately unlocks the mutex, and enters
a state of slumber until a signal is recieved, as in the case
of
.I wait(mutex&)
However, the difference here is that the method will only wait until
a specified timetick has been reached.  If this timetick is
reached before the condition variable is able to achieve a
signal, it will return with a ETIMEDOUT, or a EINTR if it received
a cancel signal while inside the wait loop.  If a signal occurs,
the returned value will be 0.

.TP 12
.B timedwait_rel(mutex&, struct timespec *)
This method is very similar to the above, it only differs from the
above method in that the
.I struct timespec *
actually points to a specification of a relative time.  Giving the
period, that the method is supposed to wait, instead of the
actual moment.  In all other respects, including the returned
values, it is equivalent to the above.

.TP 12
.B signal()
All processes that are waiting on a given condition variable, are
put into a buffer, and when this method is called, the process
that first enter the wait state on the variable will be awakened,
in a FIFO manner.

.TP 12
.B broadcast()
This method will awaken all processes, that are waiting on the
given condition variable.  Effectively emptying the buffer.

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

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

.LP
Or, to the author specified 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.