[THR] The functionality described in this section is dependent on support of the Threads option (and the rest of this section is not further shaded for this option).
This section defines functionality to support multiple flows of control, called ``threads'', within a process. For the definition of threads, see the Base Definitions volume of IEEE Std 1003.1-2001, Section 3.393, Thread.
The specific functional areas covered by threads and their scope include:
Thread management: the creation, control, and termination of multiple flows of control in the same process under the assumption of a common shared address space
Synchronization primitives optimized for tightly coupled operation of multiple control flows in a common, shared address space
All functions defined by this volume of IEEE Std 1003.1-2001 shall be thread-safe, except that the following functions1 need not be thread-safe.
The ctermid() and tmpnam() functions need not be thread-safe if passed a NULL argument. The wcrtomb() and wcsrtombs() functions need not be thread-safe if passed a NULL ps argument.
Implementations shall provide internal synchronization as necessary in order to satisfy this requirement.
Although implementations may have thread IDs that are unique in a system, applications should only assume that thread IDs are usable and unique within a single process. The effect of calling any of the functions defined in this volume of IEEE Std 1003.1-2001 and passing as an argument the thread ID of a thread from another process is unspecified. A conforming implementation is free to reuse a thread ID after the thread terminates if it was created with the detachstate attribute set to PTHREAD_CREATE_DETACHED or if pthread_detach() or pthread_join() has been called for that thread. If a thread is detached, its thread ID is invalid for use as an argument in a call to pthread_detach() or pthread_join().
A thread that has blocked shall not prevent any unblocked thread that is eligible to use the same processing resources from eventually making forward progress in its execution. Eligibility for processing resources is determined by the scheduling policy.
A thread shall become the owner of a mutex, m, when one of the following occurs:
It returns successfully from pthread_mutex_lock() with m as the mutex argument.
It returns successfully from pthread_mutex_trylock() with m as the mutex argument.
It returns (successfully or not) from pthread_cond_wait() with m as the mutex argument (except as explicitly indicated otherwise for certain errors).
It returns (successfully or not) from pthread_cond_timedwait() with m as the mutex argument (except as explicitly indicated otherwise for certain errors).
The thread shall remain the owner of m until one of the following occurs:
It executes pthread_mutex_unlock() with m as the mutex argument
It blocks in a call to pthread_cond_wait() with m as the mutex argument.
It blocks in a call to pthread_cond_timedwait() with m as the mutex argument.
The implementation shall behave as if at all times there is at most one owner of any mutex.
A thread that becomes the owner of a mutex is said to have ``acquired'' the mutex and the mutex is said to have become ``locked''; when a thread gives up ownership of a mutex it is said to have ``released'' the mutex and the mutex is said to have become ``unlocked''.
[TPS] The functionality described in this section is dependent on support of the Thread Execution Scheduling option (and the rest of this section is not further marked for this option).
In support of the scheduling function, threads have attributes which are accessed through the pthread_attr_t thread creation attributes object.
The contentionscope attribute defines the scheduling contention scope of the thread to be either PTHREAD_SCOPE_PROCESS or PTHREAD_SCOPE_SYSTEM.
The inheritsched attribute specifies whether a newly created thread is to inherit the scheduling attributes of the creating thread or to have its scheduling values set according to the other scheduling attributes in the pthread_attr_t object.
The schedpolicy attribute defines the scheduling policy for the thread. The schedparam attribute defines the scheduling parameters for the thread. The interaction of threads having different policies within a process is described as part of the definition of those policies.
If the Thread Execution Scheduling option is defined, and the schedpolicy attribute specifies one of the priority-based policies defined under this option, the schedparam attribute contains the scheduling priority of the thread. A conforming implementation ensures that the priority value in schedparam is in the range associated with the scheduling policy when the thread attributes object is used to create a thread, or when the scheduling attributes of a thread are dynamically modified. The meaning of the priority value in schedparam is the same as that of priority.
[TSP] If _POSIX_THREAD_SPORADIC_SERVER is defined, the schedparam attribute supports four new members that are used for the sporadic server scheduling policy. These members are sched_ss_low_priority, sched_ss_repl_period, sched_ss_init_budget, and sched_ss_max_repl. The meaning of these attributes is the same as in the definitions that appear under Process Scheduling .
When a process is created, its single thread has a scheduling policy and associated attributes equal to the process' policy and attributes. The default scheduling contention scope value is implementation-defined. The default values of other scheduling attributes are implementation-defined.
The scheduling contention scope of a thread defines the set of threads with which the thread competes for use of the processing resources. The scheduling operation selects at most one thread to execute on each processor at any point in time and the thread's scheduling attributes (for example, priority), whether under process scheduling contention scope or system scheduling contention scope, are the parameters used to determine the scheduling decision.
The scheduling contention scope, in the context of scheduling a mixed scope environment, affects threads as follows:
A thread created with PTHREAD_SCOPE_SYSTEM scheduling contention scope contends for resources with all other threads in the same scheduling allocation domain relative to their system scheduling attributes. The system scheduling attributes of a thread created with PTHREAD_SCOPE_SYSTEM scheduling contention scope are the scheduling attributes with which the thread was created. The system scheduling attributes of a thread created with PTHREAD_SCOPE_PROCESS scheduling contention scope are the implementation-defined mapping into system attribute space of the scheduling attributes with which the thread was created.
Threads created with PTHREAD_SCOPE_PROCESS scheduling contention scope contend directly with other threads within their process that were created with PTHREAD_SCOPE_PROCESS scheduling contention scope. The contention is resolved based on the threads' scheduling attributes and policies. It is unspecified how such threads are scheduled relative to threads in other processes or threads with PTHREAD_SCOPE_SYSTEM scheduling contention scope.
Conforming implementations shall support the PTHREAD_SCOPE_PROCESS scheduling contention scope, the PTHREAD_SCOPE_SYSTEM scheduling contention scope, or both.
Implementations shall support scheduling allocation domains containing one or more processors. It should be noted that the presence of multiple processors does not automatically indicate a scheduling allocation domain size greater than one. Conforming implementations on multi-processors may map all or any subset of the CPUs to one or multiple scheduling allocation domains, and could define these scheduling allocation domains on a per-thread, per-process, or per-system basis, depending on the types of applications intended to be supported by the implementation. The scheduling allocation domain is independent of scheduling contention scope, as the scheduling contention scope merely defines the set of threads with which a thread contends for processor resources, while scheduling allocation domain defines the set of processors for which it contends. The semantics of how this contention is resolved among threads for processors is determined by the scheduling policies of the threads.
The choice of scheduling allocation domain size and the level of application control over scheduling allocation domains is implementation-defined. Conforming implementations may change the size of scheduling allocation domains and the binding of threads to scheduling allocation domains at any time.
For application threads with scheduling allocation domains of size equal to one, the scheduling rules defined for SCHED_FIFO and SCHED_RR shall be used; see Scheduling Policies . All threads with system scheduling contention scope, regardless of the processes in which they reside, compete for the processor according to their priorities. Threads with process scheduling contention scope compete only with other threads with process scheduling contention scope within their process.
For application threads with scheduling allocation domains of size greater than one, the rules defined for SCHED_FIFO, SCHED_RR, [TSP] and SCHED_SPORADIC shall be used in an implementation-defined manner. Each thread with system scheduling contention scope competes for the processors in its scheduling allocation domain in an implementation-defined manner according to its priority. Threads with process scheduling contention scope are scheduled relative to other threads within the same scheduling contention scope in the process.
[TSP] If _POSIX_THREAD_SPORADIC_SERVER is defined, the rules defined for SCHED_SPORADIC in Scheduling Policies shall be used in an implementation-defined manner for application threads whose scheduling allocation domain size is greater than one.
If _POSIX_PRIORITY_SCHEDULING is defined, then any scheduling policies beyond SCHED_OTHER, SCHED_FIFO, SCHED_RR, [TSP] and SCHED_SPORADIC, as well as the effects of the scheduling policies indicated by these other values, and the attributes required in order to support such a policy, are implementation-defined. Furthermore, the implementation shall document the effect of all processor scheduling allocation domain values supported for these policies.
The thread cancelation mechanism allows a thread to terminate the execution of any other thread in the process in a controlled manner. The target thread (that is, the one that is being canceled) is allowed to hold cancelation requests pending in a number of ways and to perform application-specific cleanup processing when the notice of cancelation is acted upon.
Cancelation is controlled by the cancelation control functions. Each thread maintains its own cancelability state. Cancelation may only occur at cancelation points or when the thread is asynchronously cancelable.
The thread cancelation mechanism described in this section depends upon programs having set deferred cancelability state, which is specified as the default. Applications shall also carefully follow static lexical scoping rules in their execution behavior. For example, use of setjmp(), return, goto, and so on, to leave user-defined cancelation scopes without doing the necessary scope pop operation results in undefined behavior.
Use of asynchronous cancelability while holding resources which potentially need to be released may result in resource loss. Similarly, cancelation scopes may only be safely manipulated (pushed and popped) when the thread is in the deferred or disabled cancelability states.
The cancelability state of a thread determines the action taken upon receipt of a cancelation request. The thread may control cancelation in a number of ways.
Each thread maintains its own cancelability state, which may be encoded in two bits:
Cancelability-Enable: When cancelability is PTHREAD_CANCEL_DISABLE (as defined in the Base Definitions volume of IEEE Std 1003.1-2001, <pthread.h>), cancelation requests against the target thread are held pending. By default, cancelability is set to PTHREAD_CANCEL_ENABLE (as defined in <pthread.h>).
Cancelability Type: When cancelability is enabled and the cancelability type is PTHREAD_CANCEL_ASYNCHRONOUS (as defined in <pthread.h>), new or pending cancelation requests may be acted upon at any time. When cancelability is enabled and the cancelability type is PTHREAD_CANCEL_DEFERRED (as defined in <pthread.h>), cancelation requests are held pending until a cancelation point (see below) is reached. If cancelability is disabled, the setting of the cancelability type has no immediate effect as all cancelation requests are held pending; however, once cancelability is enabled again the new type is in effect. The cancelability type is PTHREAD_CANCEL_DEFERRED in all newly created threads including the thread in which main() was first invoked.
Cancelation points shall occur when a thread is executing the following functions:
A cancelation point may also occur when a thread is executing the following functions:
An implementation shall not introduce cancelation points into any other functions specified in this volume of IEEE Std 1003.1-2001.
The side effects of acting upon a cancelation request while suspended during a call of a function are the same as the side effects that may be seen in a single-threaded program when a call to a function is interrupted by a signal and the given function returns [EINTR]. Any such side effects occur before any cancelation cleanup handlers are called.
Whenever a thread has cancelability enabled and a cancelation request has been made with that thread as the target, and the thread then calls any function that is a cancelation point (such as pthread_testcancel() or read()), the cancelation request shall be acted upon before the function returns. If a thread has cancelability enabled and a cancelation request is made with the thread as a target while the thread is suspended at a cancelation point, the thread shall be awakened and the cancelation request shall be acted upon. However, if the thread is suspended at a cancelation point and the event for which it is waiting occurs before the cancelation request is acted upon, it is unspecified whether the cancelation request is acted upon or whether the cancelation request remains pending and the thread resumes normal execution.
Each thread maintains a list of cancelation cleanup handlers. The programmer uses the pthread_cleanup_push() and pthread_cleanup_pop() functions to place routines on and remove routines from this list.
When a cancelation request is acted upon, the routines in the list are invoked one by one in LIFO sequence; that is, the last routine pushed onto the list (Last In) is the first to be invoked (First Out). The thread invokes the cancelation cleanup handler with cancelation disabled until the last cancelation cleanup handler returns. When the cancelation cleanup handler for a scope is invoked, the storage for that scope remains valid. If the last cancelation cleanup handler returns, thread execution is terminated and a status of PTHREAD_CANCELED is made available to any threads joining with the target. The symbolic constant PTHREAD_CANCELED expands to a constant expression of type ( void *) whose value matches no pointer to an object in memory nor the value NULL.
The cancelation cleanup handlers are also invoked when the thread calls pthread_exit().
A side effect of acting upon a cancelation request while in a condition variable wait is that the mutex is re-acquired before calling the first cancelation cleanup handler. In addition, the thread is no longer considered to be waiting for the condition and the thread shall not have consumed any pending condition signals on the condition.
A cancelation cleanup handler cannot exit via longjmp() or siglongjmp().
The pthread_cancel(), pthread_setcancelstate(), and pthread_setcanceltype() functions are defined to be async-cancel safe.
No other functions in this volume of IEEE Std 1003.1-2001 are required to be async-cancel-safe.
Multiple readers, single writer (read-write) locks allow many threads to have simultaneous read-only access to data while allowing only one thread to have exclusive write access at any given time. They are typically used to protect data that is read more frequently than it is changed.
One or more readers acquire read access to the resource by performing a read lock operation on the associated read-write lock. A writer acquires exclusive write access by performing a write lock operation. Basically, all readers exclude any writers and a writer excludes all readers and any other writers.
A thread that has blocked on a read-write lock (for example, has not yet returned from a pthread_rwlock_rdlock() or pthread_rwlock_wrlock() call) shall not prevent any unblocked thread that is eligible to use the same processing resources from eventually making forward progress in its execution. Eligibility for processing resources shall be determined by the scheduling policy.
Read-write locks can be used to synchronize threads in the current process and other processes if they are allocated in memory that is writable and shared among the cooperating processes and have been initialized for this behavior.
All of the functions chmod(), close(), fchmod(), fcntl(), fstat(), ftruncate(), lseek(), open(), read(), readlink(), stat(), symlink(), and write() shall be atomic with respect to each other in the effects specified in IEEE Std 1003.1-2001 when they operate on regular files. If two threads each call one of these functions, each call shall either see all of the specified effects of the other call, or none of them.