Return Values
pthread_getschedparam() returns zero after completing successfully. Any other return value indicates that an error occurred. When the following condition occurs, the function fails and returns the corresponding value.
The value specified by tid does not refer to an existing thread.
Send a Signal to a Thread
pthread_kill(3THR)
Use pthread_kill(3THR) to send a signal to a thread.
Prototype: int pthread_kill(thread_t tid, int sig); |
#include <pthread.h> #include <signal.h> int sig; pthread_t tid; int ret; ret = pthread_kill(tid, sig); |
pthread_kill() sends the signal sig to the thread specified by tid. tid must be a thread within the same process as the calling thread. The sig argument must be from the list given in signal(5).
When sig is zero, error checking is performed but no signal is actually sent. This can be used to check the validity of tid.
Return Values
pthread_kill() returns zero after completing successfully. Any other return value indicates that an error occurred. When either of the following conditions occurs, pthread_kill() fails and returns the corresponding value.
sig is not a valid signal number.
tid cannot be found in the current process.
Access the Signal Mask of the Calling Thread
pthread_sigmask(3THR)
Use pthread_sigmask(3THR) to change or examine the signal mask of the calling thread.
Prototype: int pthread_sigmask(int how, const sigset_t *new, sigset_t *old); |
how determines how the signal set is changed. It can have one of the following values:
SIG_UNBLOCK--Delete new from the current signal mask, where new indicates the set of signals to unblock.
When the value of new is NULL, the value of how is not significant and the signal mask of the thread is unchanged. So, to inquire about currently blocked signals, assign a NULL value to the new argument.
The old variable points to the space where the previous signal mask is stored, unless it is NULL.
Return Values
pthread_sigmask() returns zero when it completes successfully. Any other return value indicates that an error occurred. When the following condition occurs, pthread_sigmask() fails and returns the corresponding value.
The value of how is not defined.
Forking Safely
pthread_atfork(3THR)
See the discussion about pthread_atfork(3THR) in "The Solution--pthread_atfork(3THR)".
Prototype:
int pthread_atfork(void (*prepare) (void), void (*parent) (void),
void (*child) (void) );
|
Terminate a Thread
pthread_exit(3THR)
Use pthread_exit(3THR) to terminate a thread.
Prototype: void pthread_exit(void *status); |
#include <pthread.h> void *status; pthread_exit(status); /* exit with status */ |
The pthread_exit() function terminates the calling thread. All thread-specific data bindings are released. If the calling thread is not detached, then the thread's ID and the exit status specified by status are retained until the thread is waited for via pthread_join(). Otherwise, status is ignored and the thread's ID can be reclaimed immediately. For information on thread detachment, see "Set Detach State".
Return Values
The calling thread terminates with its exit status set to the contents of status.
Finishing Up
A thread can terminate its execution in the following ways:
By returning from its first (outermost) procedure, the threads start routine; see pthread_create(3THR)
By termination with POSIX cancel functions; see pthread_cancel()
The default behavior of a thread is to linger until some other thread has acknowledged its demise by "joining" with it. This is the same as the default pthread_create() attribute being nondetached; see pthread_detach(3THR). The result of the join is that the joining thread picks up the exit status of the dying thread and the dying thread vanishes.
An important special case arises when the initial thread -- the one calling main(),-- returns from calling main() or calls exit(3C). This action causes the entire process to be terminated, along with all its threads. So take care to ensure that the initial thread does not return from main() prematurely.
Note that when the main thread merely calls pthread_exit(3THR), it terminates only itself--the other threads in the process, as well as the process, continue to exist. (The process terminates when all threads terminate.)
Cancellation
Cancellation allows a thread to terminate the execution of any other thread, or all threads, in the process. Cancellation is an option when all further operations of a related set of threads are undesirable or unnecessary.
One example of thread cancellation is an asynchronously generated cancel condition, such as, when a user requesting to close or exit some running application. Another example is the completion of a task undertaken by a number of threads. One of the threads might ultimately complete the task while the others continue to operate. Since they are serving no purpose at that point, they all should be cancelled.
There are dangers in performing cancellations. Most deal with properly restoring invariants and freeing shared resources. A thread that is cancelled without care might leave a mutex in a locked state, leading to a deadlock. Or it might leave a region of memory allocated with no way to identify it and therefore no way to free it.
The pthreads library specifies a cancellation interface that permits or forbids cancellation programmatically. The library defines the set of points at which cancellation can occur (cancellation points). It also allows the scope of cancellation handlers, which provide clean up services, to be defined so that they are sure to operate when and where intended.
Placement of cancellation points and the effects of cancellation handlers must be based on an understanding of the application. A mutex is explicitly not a cancellation point and should be held only the minimal essential time.
Limit regions of asynchronous cancellation to sequences with no external dependencies that could result in dangling resources or unresolved state conditions. Take care to restore cancellation state when returning from some alternate, nested cancellation state. The interface provides features to facilitate restoration: pthread_setcancelstate(3THR) preserves the current cancel state in a referenced variable; pthread_setcanceltype(3THR) preserves the current cancel type in the same way.
Cancellations can occur under three different circumstances:
Asynchronously
At various points in the execution sequence as defined by the standard