Next: , Previous: Basic Thread Operations, Up: POSIX Threads


34.2 Thread Attributes

Threads have a number of attributes that may be set at creation time. This is done by filling a thread attribute object attr of type pthread_attr_t, then passing it as second argument to pthread_create. Passing NULL is equivalent to passing a thread attribute object with all attributes set to their default values.

Attribute objects are consulted only when creating a new thread. The same attribute object can be used for creating several threads. Modifying an attribute object after a call to pthread_create does not change the attributes of the thread previously created.

— Function: int pthread_attr_init (pthread_attr_t *attr)

pthread_attr_init initializes the thread attribute object attr and fills it with default values for the attributes. (The default values are listed below for each attribute.)

Each attribute attrname (see below for a list of all attributes) can be individually set using the function pthread_attr_setattrname and retrieved using the function pthread_attr_getattrname.

— Function: int pthread_attr_destroy (pthread_attr_t *attr)

pthread_attr_destroy destroys the attribute object pointed to by attr releasing any resources associated with it. attr is left in an undefined state, and you must not use it again in a call to any pthreads function until it has been reinitialized.

— Function: int pthread_attr_setattr (pthread_attr_t *obj, int value)

Set attribute attr to value in the attribute object pointed to by obj. See below for a list of possible attributes and the values they can take.

On success, these functions return 0. If value is not meaningful for the attr being modified, they will return the error code EINVAL. Some of the functions have other failure modes; see below.

— Function: int pthread_attr_getattr (const pthread_attr_t *obj, int *value)

Store the current setting of attr in obj into the variable pointed to by value.

These functions always return 0.

The following thread attributes are supported:

detachstate
Choose whether the thread is created in the joinable state (value PTHREAD_CREATE_JOINABLE) or in the detached state (PTHREAD_CREATE_DETACHED). The default is PTHREAD_CREATE_JOINABLE.

In the joinable state, another thread can synchronize on the thread termination and recover its termination code using pthread_join, but some of the thread resources are kept allocated after the thread terminates, and reclaimed only when another thread performs pthread_join on that thread.

In the detached state, the thread resources are immediately freed when it terminates, but pthread_join cannot be used to synchronize on the thread termination.

A thread created in the joinable state can later be put in the detached thread using pthread_detach.

schedpolicy
Select the scheduling policy for the thread: one of SCHED_OTHER (regular, non-realtime scheduling), SCHED_RR (realtime, round-robin) or SCHED_FIFO (realtime, first-in first-out). The default is SCHED_OTHER.

The realtime scheduling policies SCHED_RR and SCHED_FIFO are available only to processes with superuser privileges. pthread_attr_setschedparam will fail and return ENOTSUP if you try to set a realtime policy when you are unprivileged.

The scheduling policy of a thread can be changed after creation with pthread_setschedparam.

schedparam
Change the scheduling parameter (the scheduling priority) for the thread. The default is 0.

This attribute is not significant if the scheduling policy is SCHED_OTHER; it only matters for the realtime policies SCHED_RR and SCHED_FIFO.

The scheduling priority of a thread can be changed after creation with pthread_setschedparam.

inheritsched
Choose whether the scheduling policy and scheduling parameter for the newly created thread are determined by the values of the schedpolicy and schedparam attributes (value PTHREAD_EXPLICIT_SCHED) or are inherited from the parent thread (value PTHREAD_INHERIT_SCHED). The default is PTHREAD_EXPLICIT_SCHED.
scope
Choose the scheduling contention scope for the created thread. The default is PTHREAD_SCOPE_SYSTEM, meaning that the threads contend for CPU time with all processes running on the machine. In particular, thread priorities are interpreted relative to the priorities of all other processes on the machine. The other possibility, PTHREAD_SCOPE_PROCESS, means that scheduling contention occurs only between the threads of the running process: thread priorities are interpreted relative to the priorities of the other threads of the process, regardless of the priorities of other processes.

PTHREAD_SCOPE_PROCESS is not supported in LinuxThreads. If you try to set the scope to this value, pthread_attr_setscope will fail and return ENOTSUP.

stackaddr
Provide an address for an application managed stack. The size of the stack must be at least PTHREAD_STACK_MIN.
stacksize
Change the size of the stack created for the thread. The value defines the minimum stack size, in bytes.

If the value exceeds the system's maximum stack size, or is smaller than PTHREAD_STACK_MIN, pthread_attr_setstacksize will fail and return EINVAL.

stack
Provide both the address and size of an application managed stack to use for the new thread. The base of the memory area is stackaddr with the size of the memory area, stacksize, measured in bytes.

If the value of stacksize is less than PTHREAD_STACK_MIN, or greater than the system's maximum stack size, or if the value of stackaddr lacks the proper alignment, pthread_attr_setstack will fail and return EINVAL.

guardsize
Change the minimum size in bytes of the guard area for the thread's stack. The default size is a single page. If this value is set, it will be rounded up to the nearest page size. If the value is set to 0, a guard area will not be created for this thread. The space allocated for the guard area is used to catch stack overflow. Therefore, when allocating large structures on the stack, a larger guard area may be required to catch a stack overflow.

If the caller is managing their own stacks (if the stackaddr attribute has been set), then the guardsize attribute is ignored.

If the value exceeds the stacksize, pthread_atrr_setguardsize will fail and return EINVAL.