November 10 2006

 pthread_cancel

  Cancellation is tha mechanism by which a thread can terminate the execution of another
thread.  More precisely, a thread can send a cancellation request to another thread.  Depending
on its settings, the target thread can then either ignore the request, honor it immediately,
or defer it till it reaches a cancellation point.

  When a thread eventually honors a cancellation request, it performs as if  pthread_exit(PTHREAD_CANCELED)
has been called at that point: all cleanup handlers are executed in reverse order, finalization
functions for thread-specific data are called, and finally the thread stops executing
with the return value PTHREAD_CANCELED.

  pthread_cancel() sends a cancellation request to the thread denoted by the "thread" argument.

  pthread_setcancelstate() changes the cancellation state for the calling thread -- that  is,
whether cancellation requests are ignored or not.  The "state" argument is the new cancellation
state: either PTHREAD_CANCEL_ENABLE to enable cancellation, or PTHREAD_CANCEL_DEFERRED to disable
cancellation (cancellation requests are ignored).  If "oldstate" is not NULL, the previous cancellation
state is stored in the location  pointed to by "oldstate", and can thus be restored later by another
call to pthread_setcancelstate().

  pthread_setcanceltype() changes the type of responses to cancellation requests for the calling thread:
asynchronous (immediate) or deferred.  The "type" argument is the new cancellation type:  either
PTHREAD_CANCEL_ASYNCHRONOUS to cancel the calling thread as soon as the cancellation request
is received, or PTHREAD_CANCEL_DEFERRED to keep the cancellation request pending until the next
cancellation point.  If "oldtype" is not NULL, the previous cancellation state is stored in the
location pointed to by "oldtype", and can thus be restored later by another call to pthread_setcanceltype().

  Threads are always created by pthread_create() with cancellation enabled and deferred. That is,
the initial cancellation state is PTHREAD_CANCEL_ENABLE and the initial type is PTHREAD_CANCEL_DEFERRED.

  Cancellation points are those points in the program execution where a test for  pending cancellation
requests is performed and cancellation is executed if positive.  The following POSIX threads functions
are cancellation points:

  pthread_join()
  pthread_cond_wait()
  pthread_cond_timedwait()
  pthread_testcancel()
  sem_wait()
  sigwait()

  All other POSIX threads functions are guaranteed not to be cancellation points.  That is,
they never perform cancellation in deferred cancellation mode.

  pthread_testcancel() does nothing except testing for pending cancellation and executing it. Its
purpose is to introduce explicit checks for cancellation in long sequences of code that
do not call cancellation point functions otherwise.

  pthread_exit()

  pthread_exit() terminates the execution of the calling thread.  All cleanup handlers
that have been set for the calling thread with pthread_cleanup_push() are executed in reverse order
(the most recently pushed handler is executed first).  Finalization functions for thread-specific
data are then called for all keys that have non-NULL values associated with them in the
calling thread.  Finally, execution of the calling thread is stopped.

  The "retval" argument is the return value of the thread.  It can be consulted from
another thread using pthread_exit().

  pthread_mutex_lock()

  pthread_mutex_init() initializes the mutex object pointed to by "mutex" according  to
the mutex attributes specified in "mutexattr".  If "mutexattr" is NULL, default attributes
are used instead.

  The LinuxThreads implementation supports only one mutex attributes, the "mutex kind",
which is either  "fast", "recursive",  or "error checking".  The kind of a mutex determines
whether it can be locked again by a thread that already owns it.  The default kind is "fast".

  Variables  of type "pthread_mutex" can also be initialized statically, using the constants
PTHREAD_RECURSIVE_MUTEX_INITIALIZER (for fast mutexes), PTHREAD_MUTEX_INITIALIZER_NP (for
recursive mutexes), and PTHREAD_ERRORCHECK_MUTEX_INITIALIZER (for error checking mutexes).

  pthread_mutex_lock() locks the given mutex.  If the mutex is currently unlocked, it becomes
locked and owned by the calling thread, and pthread_mutex_lock() returns immediately.
If the mutex is already locked by another thread, pthread_mutex_lock() suspends the calling
thread until the mutex is unlocked.

  If the mutex is already locked by the calling thread, the behavior of pthread_mutex_lock()
depends on the kind of the mutex.  If the mutex is of the "fast" kind, the calling thread
is suspended until the mutex is unlocked, thus effectively causing the calling thread to
deadlock.  If the mutex is of the "error checking" kind, pthread_mutex_lock() returns immediately
with the error code EDEADLK.  If the mutex is of the "recursive" kind, pthread_mutex_lock() succeeds
and returns immediately, recording the number of times the calling thread has locked the mutex.
An equal number of pthread_mutex_unlock() operations must be performed before the mutex returns to
the unlocked state.

  pthread_mutex_trylock() behaves identically to pthread_mutex_lock(), except that it does not block
the calling thread if the mutex is already locked by another thread (or by the calling thread in the
case of a "fast" mutex).  Instead, pthread_mutex_trylock() returns immediately with the error code EBUSY.

  pthread_mutex_unlock() unlocks the given mutex.  The mutex is assumed to be locked and owned by the
calling thread on entrance to pthread_mutex_unlock().  If the mutex is of the "fast" kind,
pthread_mutex_unlock() always returns it to the unlocked state.  If it is of the "recursive" kind, it
decrements the locking count of the mutex (number of pthread_mutex_lock() operations performed on it
by the calling thread), and only when this count reaches zero is the mutex actually unlocked.

  On "error checking" mutexes, pthread_mutex_unlock() actually checks at run-time that the mutex is
locked on entrance, and that it was locked by the same thread that is now calling pthread_mutex_unlock().
If these conditions are not met, an error code is returned and the mutex remains unchanged.
"Fast" and "recursive"  mutexes perform no such checks, thus allowing a locked mutex to be unlocked
by a thread other than its owner.  This is non-portable behavior and must not be relied upon.

  pthread_mutex_destroy() destroys a mutex object, freeing the resources it might hold.  The mutex
must be unlocked on entrance.  In the LinuxThreads implementation, no resources are associated with
mutex objects, thus pthread_mutex_destroy() actually does nothing except checking that the mutex is unlocked.