HP OpenVMS Systems Documentation

Changes the guardsize attribute of the specified thread attributes object.

Syntax

pthread_attr_setguardsize_np(
attr ,
guardsize );

Argument	Data Type	Access
attr	opaque pthread_attr_t	write
guardsize	size_t	read

C Binding

Arguments

attr

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

guardsize

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

Description

This routine uses the value specified in the guardsize argument to set the guardsize 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 guardsize attribute of a thread attributes object specifies the minimum size (in bytes) of the guard area for the stack of a new thread.

A guard area can help a multithreaded program detect overflow of a thread's stack. A guard area is a region of no-access memory that DECthreads allocates at the overflow end of the thread's stack. When any thread attempts to access a memory location within this region, a memory addressing violation occurs.

A new thread can be created with a default guardsize attribute value. This value is platform dependent, but will always be at least one "hardware protection unit" (that is, at least one page). For more information, see this guide's platform-specific appendixes.

After this routine is called, due to platform-specific factors DECthreads might reserve a larger guard area for the new thread than was specified in the guardsize argument. See this guide's platform-specific appendixes for more information.

DECthreads allows your program to specify the size of a thread stack's guard area for two reasons:

• When a thread allocates large data structures on its stack, a guard area with a size greater than the default size might be required to detect stack overflow.
• Overflow protection of a thread's stack can potentially waste system resources, such as for an application that creates a large number of threads that will never overflow their stacks. Your multithreaded program can conserve system resources by "turning off" a thread's stack guard area---that is, by specifying a guardsize attribute of zero.

If a thread is created using a thread attributes object whose stackaddr attribute is set (using the pthread_attr_setstackaddr() routine), this routine ignores the object's guardsize attribute and provides no thread stack guard area for the new thread.

Note This routine has been superseded by the pthread_attr_setguardsize() routine, as specified by the Single UNIX Specification, Version 2.

Return Values

Associated Routines

• pthread_attr_init()
• pthread_attr_getguardsize_np()
• pthread_attr_setstacksize()
• pthread_create()

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

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(), pthread_attr_setschedpolicy(), and pthread_attr_setscope() routines for more information on valid priority values, valid scheduling policy values, and valid contention scopes, respectively.

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

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

C Binding

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

(Must be zero) Argument for use by DECthreads.

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 based on DECthreads. 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

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

C Binding

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 DECthreads provides only the sched_priority scheduling parameter. It allows specifying the scheduling priority. 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 accessing shared data. With a sufficient number of processors present, all ready threads, regardless of priority, execute simultaneously.

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, DECthreads 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 DECthreads platform. On DIGITAL 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

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

C Binding

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.

Never attempt to use scheduling as a mechanism for synchronization. (Refer to Chapter 1 and Chapter 2.)

Return Values

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

C Binding

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. The specified attributes object must already be initialized at the time this routine is called.

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 DIGITAL UNIX, DECthreads supports both process contention scope and system contention scope threads. On OpenVMS, DECthreads supports only process contention scope threads. On Windows NT, DECthreads supports only system contention scope threads.

DECthreads selects at most one thread to execute on each processor at any point in time. DECthreads 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 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

Associated Routines

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