Guide to DECthreads

int
pthread_attr_setinheritsched (
pthread_attr_t *attr,
int inheritsched);

ARGUMENTS

attr
Thread attributes object 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 thread creation. The inherit scheduling attribute specifies whether threads created using the specified attributes object inherit the scheduling attributes of the creating thread, or use 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, 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---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]	One or both of the values specified by inherit or by attr is invalid.
[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_create()

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

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 defined for the specified thread attributes object.

Note
DECthreads provides only the sched_priority scheduling parameter. It allows you to specify the scheduling priority. See below for information about this scheduling parameter.

DESCRIPTION

This routine sets the scheduling parameters associated with the scheduling policy attribute for 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. Call pthread_attr_setinheritsched() and specify the value PTHREAD_EXPLICIT_SCHED for the inherit argument before calling pthread_create().
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 executing, all ready threads, regardless of priority, execute simultaneously.
Valid values of the sched_priority scheduling parameter depend on the chosen policy and fall within one of the following ranges:

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 is the midpoint between PRI_OTHER_MIN and PRI_OTHER_MAX for the SCHED_OTHER scheduling policy. (Section 2.3.6 describes how to specify priorities between the minimum and maximum values.)

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

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

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. Call pthread_attr_setinheritsched() and specify the value PTHREAD_EXPLICIT_SCHED for the inherit argument before calling pthread_create().
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 policy is invalid.

Associated Routines

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

pthread_attr_setstacksize

Changes the stacksize attribute in the specified thread attributes object.

Syntax

pthread_attr_setstacksize(
attr ,
stacksize );

Argument Data Type Access

attr opaque pthread_attr_t write

stacksize size_t read

Argument	Data Type	Access
attr	opaque pthread_attr_t	write
stacksize	size_t	read

C Binding #include <pthread.h>

int
pthread_attr_setstacksize (
pthread_attr_t *attr,
size_t stacksize);

ARGUMENTS

attr
Threads attributes object to be modified.
stacksize
New value for the stacksize attribute of the specified thread attributes object. The stacksize argument must be greater than or equal to PTHREAD_STACK_MIN. PTHREAD_STACK_MIN specifies the minimum size in bytes of stack needed for a thread.

DESCRIPTION

This routine sets the stacksize attribute in the attr object. Use this routine to adjust the size of the writable area of the stack for threads that will be created.
A thread's stack is fixed at the time of thread creation. Only the initial thread can dynamically extend its stack.
Many compilers do not check for stack overflow. Ensure that your thread stack is large enough for anything that you call from the 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 invalid, or the value specified by stacksize is less than PTHREAD_STACK_MIN or exceeds a DECthreads-imposed limit.

Associated Routines

pthread_attr_init()
pthread_attr_getstacksize()
pthread_create()

pthread_cancel

Allows a thread to request a thread to terminate execution.

Syntax

pthread_cancel(
thread );

Argument Data Type Access

thread opaque pthread_t read

Argument	Data Type	Access
thread	opaque pthread_t	read

C Binding #include <pthread.h>

int
pthread_cancel (
pthread_t thread);

ARGUMENTS

thread
Thread that receives a cancelation request.

DESCRIPTION

This routine sends a cancelation request to the specified target thread. A cancelation request is a mechanism by which a calling thread requests the target thread to terminate as quickly as possible. Issuing a cancelation request does not guarantee that the target thread will receive or handle the request.
When the cancelation request is acted on, all active cleanup handlers for the target thread are called. When the last cleanup handler returns, the thread-specific data destructor functions are called for each thread-specific data key with a destructor and for which the target thread has a non-NULL value. Finally, the target thread is terminated.
Note that cancelation of the target thread runs asynchronously with respect to the calling thread returning from pthread_cancel(). The target thread's cancelability state and type determine when or if the cancelation takes place, as follows:

The target thread can delay cancelation during critical operations by setting its cancelability state to PTHREAD_CANCEL_DISABLE.
Because of communication delays, the calling thread can only rely on the fact that a cancelation request will eventually become pending in the target thread (provided that the target thread does not terminate beforehand).
The calling thread has no guarantee that a pending cancelation request will be delivered, because delivery is controlled by the target thread.

When a cancelation request is delivered to a thread, termination processing is similar to pthread_exit(). For more information about thread termination, see the Thread Termination section of pthread_create().
This routine is preferred in implementing an Ada abort statement and any other language- or software-defined construct for requesting thread cancelation.
The results of this routine are unpredictable, if the value specified in thread refers to a thread that does not currently exist.

Return Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows:

Return	Description
0	Successful completion.
[EINVAL]	The specified thread is invalid.
[ESRCH]	The thread argument does not specify an existing thread.

Associated Routines

pthread_cleanup_pop()
pthread_cleanup_push()
pthread_create()
pthread_exit()
pthread_join()
pthread_setcancelstate()
pthread_setcanceltype()
pthread_testcancel()

pthread_cleanup_pop

(Macro) Removes the cleanup handler and optionally executes it.

Syntax

pthread_cleanup_pop(
execute );

Argument Data Type Access

execute integer read

Argument	Data Type	Access
execute	integer	read

C Binding #include <pthread.h>

void
pthread_cleanup_pop(
int execute);

ARGUMENTS

execute
Integer that specifies whether the cleanup routine specified in the matching call to pthread_cleanup_push() is executed. A nonzero value will cause the routine to be executed. This routine can be used to clean up from a block of code whether exited by cancelation or normal completion.

DESCRIPTION

This routine removes the cleanup routine and executes it if the value specified in execute is nonzero.
This routine and pthread_cleanup_push() are implemented as macros and must appear as statements and in pairs within the same lexical scope. You can think of the pthread_cleanup_push() macro as expanding to a string whose first character is a left brace ({) and pthread_cleanup_pop() as expanding to a string containing the corresponding right brace (}).

Return Values None

Associated Routines

pthread_cancel()
pthread_cleanup_push()
pthread_create()
pthread_exit()

pthread_cleanup_push

(Macro) Establishes a cleanup handler to be executed when the thread exits or is canceled.

Syntax

pthread_cleanup_push(
routine,
arg );

Argument Data Type Access

routine procedure read

arg user_arg read

Argument	Data Type	Access
routine	procedure	read
arg	user_arg	read

C Binding #include <phtread.h>

void
pthread_cleanup_push(
void (*routine)(void *),
void *arg);

ARGUMENTS

routine
Routine executed as the cleanup handler.
arg
Argument executed with the cleanup routine.

DESCRIPTION

This routine pushes the specified routine onto the calling thread's cleanup stack. The cleanup routine is popped from the stack and executed with the arg argument when any of the following actions occur:

The thread calls pthread_exit().
The thread is canceled.
An exception is raised (while the cleanup routine in is effect) and results in an unwind through the scope of the pthread_cleanup_push() and pthread_cleanup_pop() pair.
The thread calls pthread_cleanup_pop() and specifies a nonzero value for the execute argument.

This routine and pthread_cleanup_pop() are implemented as macros and must appear as statements and in pairs within the same lexical scope. You can think of the pthread_cleanup_push() macro as expanding to a string whose first character is a left brace ({) and pthread_cleanup_pop() as expanding to a string containing the corresponding right brace (}).

Return Values None

Associated Routines

pthread_cancel()
pthread_cleanup_pop()
pthread_create()
pthread_exit()
pthread_testcancel()

pthread_cond_broadcast

Wakes all threads that are waiting on a condition variable.

Syntax

pthread_cond_broadcast(
cond );

Argument Data Type Access

cond opaque pthread_cond_t modify

Argument	Data Type	Access
cond	opaque pthread_cond_t	modify

C Binding #include <pthread.h>

int
pthread_cond_broadcast (
pthread_cond_t *cond);

ARGUMENTS

cond
Condition variable upon which the threads (to be awakened) are waiting.

DESCRIPTION

This routine unblocks all threads waiting on the specified condition variable cond. Calling this routine implies that data guarded by the associated mutex has changed, so that it might be possible for one or more waiting threads to proceed. The threads that are unblocked shall contend for the mutex according to the scheduling policy (if applicable).
If only one of the threads waiting on a condition variable may be able to proceed, but any single thread can proceed, then use pthread_cond_signal() instead.
Whether the associated mutex is locked or unlocked, you can still call this routine. However, if predictable scheduling behavior is required, then that mutex should then be locked by the thread calling the pthread_cond_broadcast() routine.
If no threads are waiting on the specified condition variable, then this routine takes no action. The broadcast does not propagate to the next condition variable wait.

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 cond is invalid.

Associated Routines

pthread_cond_destroy()
pthread_cond_init()
pthread_cond_signal()
pthread_cond_timedwait()
pthread_cond_wait()

pthread_cond_destroy

Destroys a condition variable.

Syntax

pthread_cond_destroy(
cond );

Argument Data Type Access

cond opaque pthread_cond_t write

Argument	Data Type	Access
cond	opaque pthread_cond_t	write

C Binding #include <pthread.h>

int
pthread_cond_destroy (
pthread_cond_t *cond);

ARGUMENTS

cond
Condition variable to destroy.

DESCRIPTION

This routine destroys the condition variable specified by cond. This effectively uninitializes the condition variable. You call this routine when a condition variable will no longer be referenced. Destroying a condition variable allows DECthreads to reclaim internal memory associated with the condition variable.
It is safe to destroy an initialized condition variable upon which no threads are currently blocked. Attempting to destroy a condition variable upon which other threads are blocked results in unpredictable behavior.
The results of this routine are unpredictable, if the condition variable specified in cond does not exist or is not initialized.

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 cond is invalid.
[EBUSY]	The object being referenced by cond is being referenced by another thread that is currently executing a pthread_cond_wait() or pthread_cond_timedwait() on the condition variable specified in cond.

Associated Routines

pthread_cond_broadcast()
pthread_cond_init()
pthread_cond_signal()
pthread_cond_timedwait()
pthread_cond_wait()

pthread_cond_init

Initializes a condition variable.

Syntax

pthread_cond_init(
cond ,
attr );

Argument Data Type Access

cond opaque pthread_cond_t write

attr opaque pthread_condattr_t read

Argument	Data Type	Access
cond	opaque pthread_cond_t	write
attr	opaque pthread_condattr_t	read

C Binding #include <pthread.h>

int
pthread_cond_init (
pthread_cond_t *cond,
const pthread_condattr_t *attr);

ARGUMENTS

cond
Condition variable to initialize.
attr
Condition variable attributes object that defines the characteristics of the condition variable to initialize.

DESCRIPTION

This routine initializes the condition variable cond with attributes referenced by attr. If attr is NULL, the default condition variable attributes are used.
A condition variable is a synchronization object used in conjunction with a mutex. A mutex controls access to shared data; a condition variable allows threads to wait for that data to enter a defined state.
Condition variables are not owned by a particular thread. Any associated storage is not automatically deallocated when the creating thread terminates.
Use the DECthreads macro PTHREAD_COND_INITIALIZER to initialize statically allocated condition variables to the default condition variable attributes. To call this macro, enter:
pthread_cond_t condition = PTHREAD_COND_INITIALIZER
When statically initialized, a condition variable should not also be using pthread_cond_init(). Also, a statically initialized condition variable need not be destroyed using pthread_cond_destroy().
Under certain circumstances it may be impossible to wait upon a statically initialized condition variable when the process virtual address space (or some other memory limit) is nearly exhausted. In such a case pthread_cond_wait() or pthread_cond_timedwait() may return [ENOMEM]. You can avoid this possibility by initializing critical condition variables with pthread_cond_init().

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error, the condition variable is not initialized, and the contents of cond are undefined. Possible return values are as follows:

Return	Description
0	Successful completion.
[EAGAIN]	The system lacks the necessary resources to initialize another condition variable, or The system-imposed limit on the total number of condition variables under execution by a single user is exceeded.
[EBUSY]	The implementation has detected an attempt to reinitialize the object referenced by cond, a previously initialized, but not yet destroyed condition variable.
[EINVAL]	The value specified by attr is invalid.
[ENOMEM]	Insufficient memory exists to initialize the condition variable.

Associated Routines

pthread_cond_broadcast()
pthread_cond_destroy()
pthread_cond_signal()
pthread_cond_timedwait()
pthread_cond_wait()

pthread_cond_signal

Wakes at least one thread that is waiting on a condition variable.

Syntax

pthread_cond_signal(
cond );

Argument Data Type Access

cond opaque pthread_cond_t modify

Argument	Data Type	Access
cond	opaque pthread_cond_t	modify

C Binding #include <pthread.h>

  6493P008.HTM
  OSSG Documentation
  22-NOV-1996 13:20:07.75

Legal

	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.

Guide to DECthreads

ARGUMENTS

attr

inheritsched

DESCRIPTION

Associated Routines

pthread_attr_setschedparam

Syntax

pthread_attr_setschedparam( attr , param );

ARGUMENTS

attr

param

DESCRIPTION

Associated Routines

pthread_attr_setschedpolicy

Syntax

pthread_attr_setschedpolicy( attr , policy );

ARGUMENTS

attr

policy

DESCRIPTION

Associated Routines

pthread_attr_setstacksize

Syntax

pthread_attr_setstacksize( attr , stacksize );

ARGUMENTS

attr

stacksize

DESCRIPTION

Associated Routines

pthread_cancel

Syntax

pthread_cancel( thread );

ARGUMENTS

thread

DESCRIPTION

Associated Routines

pthread_cleanup_pop

Syntax

pthread_cleanup_pop( execute );

ARGUMENTS

execute

DESCRIPTION

Associated Routines

pthread_cleanup_push

Syntax

pthread_cleanup_push( routine, arg );

ARGUMENTS

routine

arg

DESCRIPTION

Associated Routines

pthread_cond_broadcast

Syntax

pthread_cond_broadcast( cond );

ARGUMENTS

cond

DESCRIPTION

Associated Routines

pthread_cond_destroy

Syntax

pthread_cond_destroy( cond );

ARGUMENTS

cond

DESCRIPTION

Associated Routines

pthread_cond_init

Syntax

pthread_cond_init( cond , attr );

ARGUMENTS

cond

attr

DESCRIPTION

Associated Routines

pthread_cond_signal

Syntax

pthread_cond_signal( cond );

pthread_attr_setschedparam(
attr ,
param );

pthread_attr_setschedpolicy(
attr ,
policy );

pthread_attr_setstacksize(
attr ,
stacksize );

pthread_cancel(
thread );

pthread_cleanup_pop(
execute );

pthread_cleanup_push(
routine,
arg );

pthread_cond_broadcast(
cond );

pthread_cond_destroy(
cond );

pthread_cond_init(
cond ,
attr );

pthread_cond_signal(
cond );