HP OpenVMS Systems Documentation

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

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.

Associated Routines

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

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

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.

Associated Routines

pthread_attr_getname_np()
pthread_getname_np()
pthread_setname_np()

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

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.)

Associated Routines

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

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

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.)

Associated Routines

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

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

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.

Associated Routines

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

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

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:

• Your program must allocate the memory that will be used for the new thread's stack.
• On Tru64 UNIX, to create a new thread using a thread attributes object, the stackaddr attribute must be an address that points to the high-memory end of the memory region allocated for the stack. This address must point to the highest even-boundary quadword in the allocated memory region.

Also note that:

• If you use the pthread_attr_setstackaddr() routine to set a thread attributes object's stack address attribute and use that attributes object to create a new thread, the Threads Library ignores the attributes object's guardsize attribute and provides no thread stack guard area or overflow warning area for the new thread.
• If you use the same thread attributes object to create more than one thread and each created thread uses a nondefault stack address, you must use the pthread_attr_setstackaddr() routine to set a unique stack address attribute value for each new thread created using that attributes object.

Associated Routines

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