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 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. |
Changes the scheduling policy attribute of the specified thread attributes object.
C Binding #include <pthread.h>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);
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.
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.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: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 | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by policy is invalid. |
Sets the contention scope attribute of the specified thread attributes object.
C Binding #include <pthread.h>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);
attr
Address of the thread attributes object whose contentions scope attribute is to be modified.scope
New value for the contention scope attribute of the thread attributes object specified by attr.
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.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: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 | Description |
---|---|
0 | Successful completion. |
[ENOSYS] | This routine is not supported by the implementation. |
[EINVAL] | The value of the attribute being set is not valid. |
[ENOTSUP] | An attempt was made to set the attribute to an unsupported value. |
Changes the stack address attribute of the specified thread attributes object.
C Binding #include <pthread.h>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);
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.
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.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: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 DECthreads 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 DIGITAL 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, DECthreads ignores the attributes object's guardsize attribute and provides no thread stack guard 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.
Return | Description |
---|---|
0 | Successful completion. |
Changes the stacksize attribute in the specified thread attributes object.
C Binding #include <pthread.h>pthread_attr_setstacksize(
attr ,
stacksize );
Argument Data Type Access attr opaque pthread_attr_t write stacksize size_t read
int
pthread_attr_setstacksize (
pthread_attr_t *attr,
size_t stacksize);
attr
Threads attributes object to be modified.stacksize
New value for the stacksize attribute of the thread attributes object specified by the attr argument. 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.
This routine sets the stacksize attribute in the thread attributes object specified by the attr argument. Use this routine to adjust the size of the writable area of the stack for a new 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:The size of 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 the new thread's stack is sufficient for the resources required by routines that are called from the thread.
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. |
Allows a thread to request a thread to terminate execution.
C Binding #include <pthread.h>pthread_cancel(
thread );
Argument Data Type Access thread opaque pthread_t read
int
pthread_cancel (
pthread_t thread);
thread
Thread that receives a cancelation request.
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.Return Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows:When the cancelation request is acted on, all active cleanup handler routines for the target thread are called. When the last cleanup handler returns, the thread-specific data destructor routines 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's 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 that for 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 | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The specified thread is invalid. |
[ESRCH] | The thread argument does not specify an existing thread. |
(Macro) Removes the cleanup handler routine from the calling thread's cleanup handler stack and optionally executes it.
C Binding #include <pthread.h>pthread_cleanup_pop(
execute );
Argument Data Type Access execute integer read
void
pthread_cleanup_pop(
int execute);
execute
Integer that specifies whether the cleanup handler routine specified in the matching call to pthread_cleanup_push() is executed. A nonzero value causes the cleanup handler routine to be executed.
This routine removes the cleanup handler routine established by the matching call to pthread_cleanup_push() from the calling thread's cleanup handler stack, then executes it if the value specified in this routine's execute argument is nonzero.Return Values NoneA cleanup handler routine can be used to clean up from a block of code whether exited by normal completion, cancelation, or the raising (or reraising) of an exception. The routine is popped from the calling thread's cleanup handler stack and is executed with the arg argument when any of the following actions occur:
- The thread calls pthread_cleanup_pop() and specifies a nonzero value for the execute argument.
- The thread calls pthread_exit().
- The thread is canceled.
- An exception is raised and is caught when DECthreads unwinds the calling thread's stack to the lexical scope of the pthread_cleanup_push() and pthread_cleanup_pop() pair.
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 (}).
(Macro) Establishes a cleanup handler routine to be executed when the thread exits or is canceled.
C Binding #include <phtread.h>pthread_cleanup_push(
routine,
arg );
Argument Data Type Access routine procedure read arg user_arg read
void
pthread_cleanup_push(
void (*routine)(void *),
void *arg);
routine
Routine executed as the cleanup handler.arg
Argument pass to the cleanup handler routine.
This routine pushes the specified routine onto the calling thread's cleanup handler stack. The cleanup handler routine is popped from the stack and executed with the arg argument when any of the following actions occur:Return Values None
- The thread calls pthread_cleanup_pop() and specifies a nonzero value for the execute argument.
- The thread calls pthread_exit().
- The thread is canceled.
- An exception is raised and is caught when DECthreads unwinds the calling thread's stack to the lexical scope of the pthread_cleanup_push() and pthread_cleanup_pop() pair.
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 (}).
Destroys a condition variable attributes object.
C Binding #include <pthread.h>pthread_condattr_destroy(
attr );
Argument Data Type Access attr opaque pthread_condattr_t write
int
pthread_condattr_destroy (
pthread_condattr_t *attr);
attr
Condition variable attributes object to be destroyed.
This routine destroys the specified condition variable attributes object---that is, the object becomes uninitialized.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:Condition variables that were created using this attributes object are not affected by the deletion of the condition variable attributes object.
After calling this routine, the results of using attr in a call to any routine (other than pthread_condattr_init()) are unpredictable.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The attributes object specified by attr is invalid. |
Initializes a condition variable attributes object.
C Binding #include <pthread.h>pthread_condattr_init(
attr );
Argument Data Type Access attr opaque pthread_condattr_t write
int
pthread_condattr_init (
pthread_condattr_t *attr);
attr
Address of the condition variable attributes object to be initialized.
This routine initializes the condition variable attributes object specified by the attr argument with a set of default attribute 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:When an attributes object is used to create a condition variable, the values of the individual attributes determine the characteristics of the new condition variable. Attributes objects act as additional arguments to condition variable creation. Changing individual attributes in an attributes object does not affect any condition variables that were previously created using that attributes object.
You can use the same condition variable attributes object in successive calls to pthread_condattr_init(), from any thread. If multiple threads can change attributes in a shared attributes object, your program must use a mutex to protect the integrity of that attributes object.
Results are undefined if this routine is called and the attr argument specifies a condition variable attributes object that is already initialized.
Currently, no attributes affecting condition variables are defined. You cannot change any attributes in the condition variable attributes object.
The pthread_condattr_init() and pthread_condattr_destroy() routines are provided for future expandability of the DECthreads pthread interface and to conform with the POSIX.1c standard. These routines serve no useful function, because there are no pthread_condattr_set*() type routines available at this time.
Return | Description |
---|---|
0 | Successful completion. |
[ENOMEM] | Insufficient memory exists to initialize the condition variable attributes object. |
Wakes all threads that are waiting on the specified condition variable.
C Binding #include <pthread.h>pthread_cond_broadcast(
cond );
Argument Data Type Access cond opaque pthread_cond_t modify