Tru64 UNIX
Guide to the POSIX Threads Library


Previous Contents Index


pthread_attr_setinheritsched

Changes the inherit scheduling attribute of the specified thread attributes object.

Syntax

pthread_attr_setinheritsched(
attr ,
inheritsched );

Argument Data Type Access
attr opaque pthread_attr_t write
inheritsched integer read

C Binding #include <pthread.h>

int
pthread_attr_setinheritsched (
pthread_attr_t *attr,
int inheritsched);


Arguments

attr

Thread attributes object whose inherit scheduling attribute is to be modified.

inheritsched

New value for the inherit scheduling attribute. Valid values are as follows:
  PTHREAD_INHERIT_SCHED The created thread inherits the scheduling policy and associated scheduling attributes of the thread calling pthread_create() . Any scheduling attributes in the attributes object specified by the pthread_create() attr argument are ignored during thread creation. This is the default value.
  PTHREAD_EXPLICIT_SCHED The scheduling policy and associated scheduling attributes of the created thread are set to the corresponding values from the attribute object specified by the pthread_create() attr argument.

Description

This routine changes the inherit scheduling attribute of the thread attributes object specified by the attr argument. The inherit scheduling attribute specifies whether a thread created using the specified attributes object inherits the scheduling attributes of the creating thread, or uses the scheduling attributes stored in the attributes object specified by the pthread_create() attr argument.

The first thread in an application has a scheduling policy of SCHED_OTHER . See the pthread_attr_setschedparam() and pthread_attr_setschedpolicy() routines for more information on valid priority values and valid scheduling policy values.

Inheriting scheduling attributes (instead of using the scheduling attributes stored in the attributes object) is useful when a thread is creating several helper threads---that is, threads that are intended to work closely with the creating thread to cooperatively solve the same problem. For example, inherited scheduling attributes ensure that helper threads created in a sort routine execute with the same priority as the calling thread.

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Return Description
0 Successful completion.
[EINVAL] The value specified by the attr argument is not a valid thread attributes object, or the inheritsched argument contains an invalid value.
[ENOTSUP] An attempt was made to set the attribute to an unsupported value.

Associated Routines

pthread_attr_init()
pthread_attr_getinheritsched()
pthread_attr_setschedpolicy()
pthread_attr_setschedparam()
pthread_attr_setscope()
pthread_create()

pthread_attr_setname_np

Changes the object name attribute in a thread attributes object.

Syntax

pthread_attr_setname_np(
attr ,
name ,
mbz );

Argument Data Type Access
attr opaque pthread_attr_t write
name char read
mbz void read

C Binding #include <pthread.h>

int
pthread_attr_setname_np (
pthread_attr_t *attr,
const char *name,
void *mbz);


Arguments

attr

Address of the thread attributes object whose object name attribute is to be changed.

name

Object name value to copy into the thread attributes object's object name attribute.

mbz

Reserved for future use. The value must be zero (0).

Description

This routine changes the object name attribute in the thread attributes object specified by the attr argument to the value specified by the name argument. A new thread created using the thread attributes object is initialized with the object name that was set in that attributes object.

The object name is a C language string and provides an identifier that is meaningful to a person debugging a multithreaded application. The maximum number of characters in the object name is 31.

This routine contrasts with pthread_setname_np() , which changes the object name in the thread object for an existing thread.

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Return Description
0 Successful completion.
[EINVAL] The value specified by attr is not a valid thread attributes object, or the length in characters of name exceeds 31.
[ENOMEM] Insufficient memory exists to create a copy of the object name string.

Associated Routines

pthread_attr_getname_np()
pthread_getname_np()
pthread_setname_np()

pthread_attr_setschedparam

Changes the values of the parameters associated with a scheduling policy of the specified thread attributes object.

Syntax

pthread_attr_setschedparam(
attr ,
param );

Argument Data Type Access
attr opaque pthread_attr_t write
param struct sched_param read

C Binding #include <pthread.h>

int
pthread_attr_setschedparam (
pthread_attr_t *attr,
const struct sched_param *param);


Arguments

attr

Thread attributes object for the scheduling policy attribute whose parameters are to be set.

param

A structure containing new values for scheduling parameters associated with the scheduling policy attribute of the specified thread attributes object.

Note

The Threads Library provides only the sched_priority scheduling parameter. See below for information about this scheduling parameter.

Description

This routine sets the scheduling parameters associated with the scheduling policy attribute of the thread attributes object specified by the attr argument.

Scheduling Priority

Use the sched_priority field of a sched_param structure to set a thread's execution priority. The effect of the scheduling priority you assign depends on the scheduling policy specified for the attributes object specified by the attr argument.

By default, a created thread inherits the priority of the thread calling pthread_create() . To specify a priority using this routine, scheduling inheritance must be disabled at the time the thread is created. Before calling pthread_create() , call pthread_attr_setinheritsched() and specify the value PTHREAD_EXPLICIT_SCHED for the inherit argument.

An application specifies priority only to express the urgency of executing the thread relative to other threads. Do not use priority to control mutual exclusion when you are accessing shared data. With a sufficient number of processors present, all ready threads, regardless of priority, execute simultaneously. Even on a uniprocessor, a lower priority thread could either execute before or be interleaved with a higher priority thread, for example due to page fault behavior. See Chapter 1 and Chapter 2 for more information.

Valid values of the sched_priority scheduling parameter depend on the chosen scheduling policy. Use the POSIX routines sched_get_priority_min() or sched_get_priority_max() to determine the low and high limits of each policy.

Additionally, the Threads Library provides nonportable priority range constants, as follows:
Policy Low High
SCHED_FIFO PRI_FIFO_MIN PRI_FIFO_MAX
SCHED_RR PRI_RR_MIN PRI_RR_MAX
SCHED_OTHER PRI_OTHER_MIN PRI_OTHER_MAX
SCHED_FG_NP PRI_FG_MIN_NP PRI_FG_MAX_NP
SCHED_BG_NP PRI_BG_MIN_NP PRI_BG_MAX_NP

The default priority varies by platform. On Tru64 UNIX, the default is 19 (that is, the POSIX priority of a normal timeshare process). On other platforms, the default priority is the midpoint between PRI_FG_MIN_NP and PRI_FG_MAX_NP . ( Section 2.3.6 describes how to specify priorities between the minimum and maximum values.)

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Return Description
0 Successful completion.
[EINVAL] The value specified by attr is not a valid thread attributes object, or the value specified by param is invalid.
[ENOTSUP] An attempt was made to set the attribute to an unsupported value.

Associated Routines

pthread_attr_init()
pthread_attr_getschedparam()
pthread_attr_setinheritsched()
pthread_attr_setschedpolicy()
pthread_create()
sched_yield()

pthread_attr_setschedpolicy

Changes the scheduling policy attribute of the specified thread attributes object.

Syntax

pthread_attr_setschedpolicy(
attr ,
policy );

Argument Data Type Access
attr opaque pthread_attr_t write
policy integer read

C Binding #include <pthread.h>

int
pthread_attr_setschedpolicy (
pthread_attr_t *attr,
int policy);


Arguments

attr

Thread attributes object to be modified.

policy

New value for the scheduling policy attribute. Valid values are as follows:
SCHED_BG_NP
SCHED_FG_NP (also known as SCHED_OTHER )
SCHED_FIFO
SCHED_RR

SCHED_OTHER is the default value. See Section 2.3.2.2 for a description of the scheduling policies.


Description

This routine sets the scheduling policy of a thread that is created using the attributes object specified by the attr argument. The default value of the scheduling attribute is SCHED_OTHER .

By default, a created thread inherits the policy of the thread calling pthread_create() . To specify a policy using this routine, scheduling inheritance must be disabled at the time the thread is created. Before calling pthread_create() , call pthread_attr_setinheritsched() and specify the value PTHREAD_EXPLICIT_SCHED for the inherit argument.

Preemption is caused by both scheduling and policy. Never attempt to use scheduling as a mechanism for synchronization. (Refer to Chapter 1 and Chapter 2.)

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Return Description
0 Successful completion.
[EINVAL] The value specified by attr is not a valid thread attributes object, or the value specified by policy is invalid.

Associated Routines

pthread_attr_init()
pthread_attr_getschedpolicy()
pthread_attr_setinheritsched()
pthread_attr_setschedparam()
pthread_create()

pthread_attr_setscope

Sets the contention scope attribute of the specified thread attributes object.

Syntax

pthread_attr_setscope(
attr ,
scope );

Argument Data Type Access
attr opaque pthread_attr_t write
scope int read

C Binding #include <pthread.h>

int
pthread_attr_setscope (
pthread_attr_t *attr,
int scope);


Arguments

attr

Address of the thread attributes object whose contention scope attribute is to be modified.

scope

New value for the contention scope attribute of the thread attributes object specified by attr.

Description

This routine uses the value specified in the scope argument to set the contention scope attribute of the thread attributes object specified in the attr argument.

When creating a thread, use a thread attributes object to specify nondefault values for thread attributes. The contention scope attribute specifies the set of threads with which a thread must compete for processing resources. The contention scope attribute specifies whether the new thread competes for processing resources only with other threads in its own process, called process contention scope, or with all threads on the system, called system contention scope.

Note

On Tru64 UNIX, the Threads Library supports both process contention scope and system contention scope threads. On OpenVMS, the Threads Library supports only process contention scope threads.

The Threads Library selects at most one thread to execute on each processor at any point in time. The Threads Library resolves the contention based on each thread's scheduling attributes (for example, priority) and scheduling policy (for example, round-robin).

A thread created using a thread attributes object whose contention scope attribute is set to PTHREAD_SCOPE_PROCESS contends for processing resources with other threads within its own process that also were created with PTHREAD_SCOPE_PROCESS . It is unspecified how such threads are scheduled relative to either threads in other processes or threads in the same process that were created with PTHREAD_SCOPE_SYSTEM contention scope.

A thread created using a thread attributes object whose contention scope attribute is set to PTHREAD_SCOPE_SYSTEM contends for processing resources with other threads in any process that also were created with PTHREAD_SCOPE_SYSTEM .

Note that the value of the contention scope attribute of a particular thread attributes object does not necessarily correspond to the actual scheduling contention scope of any existing thread in your multithreaded program.

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Return Description
0 Successful completion.
[EINVAL] The value specified by attr is not a valid thread attributes value, or the value specified by scope is not valid.
[ENOTSUP] An attempt was made to set the attribute to an unsupported value.

Associated Routines

pthread_attr_destroy()
pthread_attr_init()
pthread_attr_getscope()
pthread_attr_setinheritsched()
pthread_create()

pthread_attr_setstackaddr

Changes the stack address attribute of the specified thread attributes object.

Syntax

pthread_attr_setstackaddr(
attr ,
stackaddr );

Argument Data Type Access
attr opaque pthread_attr_t write
stackaddr void read

C Binding #include <pthread.h>

int
pthread_attr_setstackaddr (
pthread_attr_t *attr,
void *stackaddr);


Arguments

attr

Address of the thread attributes object whose stack address attribute is to be modified.

stackaddr

New value for the stack address attribute of the thread attributes object specified by attr.

Description

This routine uses the value specified in the stackaddr argument to set the stack address attribute of the thread attributes object specified in the attr argument.

When creating a thread, use a thread attributes object to specify nondefault values for thread attributes. The stack address attribute of a thread attributes object points to the origin of the stack for a new thread.

The default value for the stack address attribute of an initialized thread attributes object is NULL.

Note

Correct use of this routine depends upon details of the target platform's stack architecture. Thus, this routine cannot be used in a portable manner.

The size of the stack must be at least PTHREAD_STACK_MIN bytes (see the pthread.h header file). However, because the Threads Library must use a portion of this stack memory to begin thread execution and to maintain thread state, your program's "user thread code" cannot rely on using all of the stack memory allocated.

For your program to calculate a value for the stackaddr attribute, note that:

Also note that:

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Return Description
0 Successful completion.
[EINVAL] The value specified by attr is not a valid thread attributes object.

Associated Routines

pthread_attr_getguardsize()
pthread_attr_getstackaddr()
pthread_attr_getstacksize()
pthread_attr_init()
pthread_attr_setguardsize()
pthread_attr_setstacksize()
pthread_create()


Previous Next Contents Index