pthread.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
pthread \- An abstract class, to create a threaded program.
.SH SYNOPSIS
.B        #include <thread.h>
.sp 2
.B         class threaded : public pthread {
.sp 0
.B           threaded() { };
.sp 0
.B           ~threaded() { };
.sp 1
.B           int thread(void *) { // threaded execution happens here };
.sp 0
.B          }
.SH DESCRIPTION
The
.I pthread
class is a part of the threads C++ library that focuses on
simplifying program threading.

By providing an abstract class, like the pthread class, the user is
presented with a simple method of starting a program threaded and
is able to select wether the thread is an application by itself or
merely a thread in one.
.LP
The class provides numerous methods to control the thread, that
is associated with the class.  These methods are focused on
synchronizing the threads execution with the parent thread, and
providing access to local variables, as well as changes the runtime
state of the thread itself.
.LP
These methods are listed here, with some explanation on how they
function.

.TP 12
.B retval()
A thread can exeit in two ways, it can do a 'return' from the
thread function, or do exit through the 'exit' function call.  Both
of which provide a means to return a value.  To make the
library provide similar return means, as the posix threads do,
it is possible to do a
.I exit(void *)
where a pointer to a value is registered as a return value.  In
such cases, the means in accessing the returned value is through
this method.

.TP 12
.B joining()
This will tell if the thread being executed under the class, will
join any other process on termination.  If this is the case, the
process id returned, is an id of a process that is suspended and
will be woken up, when the thread terminates.

.TP 12
.B gerrno()
Each thread has its own errno variable, that the threaded program
can set to an error value, with the help of
.B error()
class method.  It is then possible to read this error value, from
a parallel or parent thread with this method.

.TP 12
.B id()
Each thread, is started with its own process id.  This is to make
certain that they are separable from the main thread, if ever
needed.  This method provides means, to obtain the process id of
the thread running inside the class.

.TP 12
.B signal()
After having received a signal, either a restart or a suspend
signal.  The thread will store it, for others to retreive and
examine its state.  With this method, the user can see if the
signal has been suspended or revived.

.TP 12
.B signal(int)
Beyond merely obtaining the signal status, this methd provides
the means of sending a signal to the thread.  It will return the
signal last processed by the thread, which may not be the signal
passed to this function.

.TP 12
.B canceled()
This method will report, wether the thread has been canceled with
the
.B cancel()
method.

.TP 12
.B detached()
With this method, parent threads can obtain the status of any
child threads, to see if they are stilled attached (child threads)
of it.

.TP 12
.B joinable()
When a thread has been detached, for instance... or it is the
intention to detach a thread from its parent.  It is not desirable
that it be joined with by other sibling threads.  This method
provides a means to obtain the status of wether the thread is
joinable by other sibling threads.

.TP 12
.B terminated()
If a thread has terminated, this will return a true value to
signify a termination state.

.TP 12
.B exited()
If a thread has been exited with the 'exit' call, this will
signify that status.

.TP 12
.B cancelstate()
This method will tell the current cancelstate of the thread.  A
cancel state can be one of following enumerated items:
.IP
.I cancel_enable
- Cancelations are enabled.
.sp 0
.I cancel_disable
- Cancelations are not allowed.

.TP 12
.B canceltype()
Threads can be canceled in different ways, it can be terminated
by means of forcing them through the 'exit(-1)' state, upon
receiving a cancel signal.  Or they can be made to jump to a
predefined location upon receiving that signal.  Both of which
predetermine that the cancel state is
.I cancel_enable
and if not, no cancelation will occur.
.IP
.I cancel_deferred 
- jump to a user definable location.
.sp 0
.I cancel_asynchronous 
- exit through the 'exit' method.

.TP 12
.B joining(int)
This method is provided to tell the thread to join with a given
process upon termination.  The process is assumed to be in slumber,
and will be revived when the thread exits.  It is upon the users
responsibility to ensure that the process being joined with is
actually a running process.

.TP 12
.B set(cancel_state)
Change the cancel state, to the given parameter.

.TP 12
.B set(cancel_type)
Change the cancel type, to the given parameter.

.TP 12
.B set(jumps,sigjump_buf *)
Set either of two possible jump locations, the signal jump or the
cancel jump, to the jump buffer associated with the method
call.  Possible values for
.I jumps
are:
.IP
.I cancel_jump 
- When cancel is received.
.sp 0
.I signal_jump 
- When restart signal is received

.TP 12
.B set(booleans,bool)
Set any of the boolean values, to the state given.  The booleans parameter
is an enumeration code, for the numerous boolean variables that
are located inside the class.  The ones settable are:
.IP
.I set_canceled   
- set the cancel state value.
.sp 0
.I set_terminated 
- set the terminated state.
.sp 0
.I set_detached 
- set the detached state.
.sp 0
.I set_exited 
- set the exited state.

.TP 12
.B cancel()
Send the thread, a cancel signal that will cancel it if cancellation
is enabled.  If the cancel type is deferred, the cancelation will
jump to a location, that has been previously set with set(jumps,...)
or exit the thread, if the cancel type is asynchronous.

.TP 12
.B suspend()
This is a static method, that will suspend the calling process until
a
.I restart()
signal is received.  Inside this method, cancelations will be ignored
by the thread, except program exits will terminate the process.

.TP 12
.B suspend_with_cancelation()
This will suspend the process, until a cancelation has been received,
or the process is revived.  Whichever comes first.  The method is
static, and will work on the process that calls it, and not the
thread associated with the class.

.TP 12
.B restart()
Send a restart signal to a thread, that has been suspended with
either one of the above methods.  This method is not static, which
means that it will restart the thread associated with the class.

.TP 12
.B jump(jumps)
Make a jump to either of the registered jump locations, for signal
or cancel jumps.  See
.I set(jumps,sigjump_buf)

.TP 12
.B exit(void *)
The normal posix threads, use a void * as an exit value to return
to parent threads.  This method is provided as an historical means
for programs that desire to be constructively equivalent to the
posix treads.  The value will be accessable with the
.I retval()
method.

.TP 12
.B exit(int)
This way in exiting an application is the one that is usually used
by a program.  It will mark the value passed to the method, as an
exit value that will be retrievable with the
.I retcode()
method.

.TP 12
.B exit()
This will effectively be the same as if calling
.I exit(0)

.TP 12
.B retcode()
See the method
.I exit(int)
For a way to create a value that is retrievable through this method,
but it will simply obtain the return value, registered by a thread.  It
will only be usable after the thread has terminated.

.TP 12
.B running()
This method will tell the caller, whether the scheduler has the
thread on running schedule or not.  Its not really usable, since
a zombie process is still on the schedulers list.  Use
.I terminated()
or
.I canceled()
to determine if the program is running or not.

.TP 12
.B join()
This method will suspend the calling process, until the thread
associated with the call terminates.  When it terminates, it will
send the calling process a restart signal, restoring it to a
running state and returning from this method.

.LP
The next methods, are provided for shared memory and process
scoping.  Process scoping, is when two distinct processes share
memory or variables for synchronisation.

.TP 12
.B set_project(const char *)
A program that want's to share its resources must have a way for all
other programs to identify its resources.  The way for this to
happen, is to create a name that will identify it... which is
upto the user to define.  This method provides a way to
set the name of the programs resources.

.TP 12
.B set_permissions(int)
When resources are shared, the user can define the permissions
that will be given to other programs.  A program can allow others
to read it's pages, or to read and write them depending on the
normal unix protection methods for user/gropu/others.  The
parameter passed to this method, is the permissions that should
be used when creating shared resources.

.TP 12
.B shalloc(size_t)
Allocate a specified amount of shared memory for users use.  This
memory is taken from the systme is pages, where each page is
of
.I PAGE_SIZE
size.  The memory returned to the user, is only a fragment of this
page, that is
.B size_t
in size.  It is recomended that the user keep to the same
principles with this method, as normally is done with the
.I malloc()
system call, as the
.I threads library
provides for management of the shared memory.

.TP 12
.B shdealloc(void *)
Return memory retrieved with the above method, back to the
shared memory pool.  This method will collect the shared memory
page back, and upon receiving a whole free page, it will
immediately return it back to the system and destroy it
from the users address space.

.LP
The library installs signal handlers for all terminating signals,
to ensure that shared memory is destroyed when they aren't needed
anymore.

.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 those who reported their suggestions on how to
improve the threads library.