DESCRIPTION DECthreads, HP's multithreading run-time library, provides a set of interfaces for building multithreaded programs. One of these interfaces provides routines (with the prefix pthread_) that implement the IEEE Std 1003.1c-1995, POSIX System Application Program Interface, also known as POSIX Standard 1003.1c or POSIX.1c. Note that POSIX Standard 1003.1c now supersedes the POSIX draft standard 1003.4a. A thread is a single, sequential flow of control within a program. Within a single thread, there is a single point of execution. Most traditional programs consist of a single thread. Using DECthreads, a programmer can create more than one threads within a program. Threads execute concurrently, and, within a multithreaded pro- gram, there are at any time multiple points of execution. The threads in a given process execute within (and share) a single address space. There- fore, threads read and write the same memory locations. Synchronization elements such as mutexes and condition variables ensure that the shared memory is accessed correctly. DECthreads provides routines that allow you to create and use these synchronization elements. Mutexes and condition variables are discussed in the Guide to DECthreads. Users of previous versions of DECthreads should be aware that applications consistent with the P1003.4a/D4 interface require significant modifications to be upgraded to the DECthreads pthread (POSIX.1c) interface. See the discussion in the Guide to DECthreads. Routine names ending with the _np suffix denote that the routine is "not portable." That is, such a routine might not be available in other vendor implementations of POSIX 1003.1c. Each C module that utilizes DECthreads exceptions must include the pthread_exception.h header file. The Guide to DECthreads describes the use of DECthreads exceptions. The Guide to DECthreads describes important considerations for threaded application development, particularly for the OpenVMS operating system. Threads are packaged with the operating system.
1 – Thread Intro
NAME
intro - Introduction to DCE Threads
DESCRIPTION
DCE Threads are a set of routines that you can call to create a multi-
threaded program. Multithreading is used to improve the performance
of a program. Routines implemented by DCE Threads that are not speci-
fied by Draft 4 of the POSIX 1003.4a standard are indicated by an _np
suffix on the name. These routines are not portable.
The pthread interface routines are grouped in the following functional
categories:
+ General threads routines
+ Thread attributes object routines
+ Thread cancelation routines
+ Thread priority, concurrency, and scheduling routines
+ Thread-specific data routines
+ Mutex routines
+ Mutex attributes object routines
+ Condition variable routines
+ Condition variable attribute object routines
DECthreads also provides routines that implement nonportable extensions
to the POSIX 1003.1c standard. These routines are grouped into these
functional categories:
+ Thread execution routines
+ Thread attributes routines
+ DECthreads global mutex routines
+ Mutex attributes routines
+ Condition variable routines
+ DECthreads exception object routines
1.1 – General Threads Routines
pthread_create Creates a thread object and thread.
pthread_detach Marks a thread object for deletion.
pthread_equal Compares one thread identifier to another
thread identifier.
pthread_exit Terminates the calling thread.
pthread_join Causes the calling thread to wait for the
termination of a specified thread and detach
it.
pthread_once Calls an initialization routine to be
executed only once.
pthread_self Obtains the identifier of the current thread.
1.2 – Thread Attributes Object Routines
pthread_attr_destroy Destroys a thread attributes object.
pthread_attr_getdetachstate
Obtains the detachstate attribute from the
specified thread attributes object.
pthread_attr_getguardsize
Obtains the guardsize attribute of the
specified thread attributes object.
pthread_attr_getinheritsched
Obtains the inherit scheduling attribute
from the specified thread attributes object.
pthread_attr_getschedparam
Obtains the scheduling parameters for an
attribute of the specified thread attributes
object.
pthread_attr_getschedpolicy
Obtains the scheduling policy attribute of
the specified thread attributes object.
pthread_attr_getscope Obtains the contention-scope attribute of
the specified thread attributes object.
pthread_attr_getstackaddr
Obtains the stackaddr attribute of the
specified thread attributes object.
pthread_attr_getstacksize
Obtains the stacksize attribute of the
specified thread attributes object.
pthread_attr_init Initializes a thread attributes object.
pthread_attr_setdetachstate
Changes the detachstate attribute in the
specified thread attributes object.
pthread_attr_setguardsize
Changes the guardsize attribute of the
specified thread attributes object.
pthread_attr_setinheritsched
Changes the inherit scheduling attribute
of the specified thread attributes object.
pthread_attr_setschedparam
Changes the values of the parameters
associated with the scheduling policy
attribute of the specified thread attri-
butes object.
pthread_attr_setschedpolicy
Changes the scheduling policy attribute
of the specified thread attributes object.
pthread_attr_setstackaddr
Changes the stackaddr attribute in the
specified thread attributes object.
pthread_attr_setstacksize
Changes the stacksize attribute in the
specified thread attributes object.
1.3 – Thread Cancellation Routines
pthread_cancel Allows a thread to request that it, or
another thread, terminate execution.
pthread_cleanup_pop Removes a cleanup handler routine from the
top of the cleanup stack and optionally
executes it.
pthread_cleanup_push Establishes a cleanup handler routine to
be executed when the thread exits or is
canceled.
pthread_setcancelstate Sets the current thread's cancelability
state.
pthread_setcanceltype Sets the current thread's cancelability
type.
pthread_testcancel Requests delivery of any pending
cancelation request to the current thread.
1.4 – Thread Priority Concurrency and Scheduling Routines
pthread_getconcurrency Obtains the current concurrency level
parameter for the process.
pthread_getschedparam Obtains the current scheduling policy and
scheduling parameters of a thread.
pthread_getsequence_np Obtains a thread sequence number.
pthread_setconcurrency Changes the current concurrency level
parameter for the process.
pthread_setschedparam Changes the current scheduling policy
and scheduling parameters of a thread.
1.5 – Thread Specific Data Routines
pthread_getspecific Obtains the thread-specific data
associated with the specified key.
pthread_key_create Generates a unique thread-specific data key.
pthread_setspecific Sets the thread-specific data value
associated with the specified key for the
current thread.
pthread_key_delete Deletes a thread-specific data key.
1.6 – Mutex Routines
pthread_mutex_destroy Destroys a mutex.
pthread_mutex_init Initializes a mutex with attributes
specified by the attributes argument.
pthread_mutex_lock Locks an unlocked mutex; if locked, the
caller waits for the mutex to become
available.
pthread_mutex_trylock Attempts to lock a mutex; returns
immediately if mutex is already locked.
pthread_mutex_unlock Unlocks a locked mutex.
1.7 – Mutex Attributes Object Routines
pthread_mutexattr_init Initializes a mutex attributes object.
pthread_mutexattr_destroy
Destroys a mutex attributes object.
pthread_mutexattr_gettype
Obtains the mutex type attribute of a
mutex attributes object.
pthread_mutexattr_settype
Changes the mutex type attribute of a
mutex attributes object.
1.8 – Condition Variable Routines
pthread_cond_broadcast Wakes all threads waiting on a condition
variable.
pthread_cond_destroy Destroys a condition variable.
pthread_cond_init Initializes a condition variable.
pthread_cond_signal Wakes at least one thread that is waiting
on a condition variable.
pthread_cond_timedwait Causes a thread to wait for a specified
period of time for a condition variable
to be signaled or broadcasted.
pthread_cond_wait Causes a thread to wait for a condition
variable to be signaled or broadcasted.
1.9 – Condition Variable Attributes Object Routines
pthread_condattr_destroy
Destroys a condition variable attributes
object.
pthread_condattr_init Initializes a condition variable attributes
object.
1.10 – Non Portable Extensions
DECthreads also provides routines that implement nonportable extensions to the POSIX 1003.1c standard. These routines are grouped into these functional categories:
1.10.1 – Thread Execution Routines
pthread_delay_np Causes a thread to delay execution.
pthread_get_expiration_np
Obtains a value representing a desired
expiration time.
pthread_getsequence_np Obtains the thread sequence number.
1.10.2 – Thread Attributes Routines
pthread_attr_getguardsize_np
Obtains the guardsize attribute of the
specified thread attributes object.
pthread_attr_setguardsize_np
Changes the guardsize attribute of the
specified thread attributes object.
1.10.3 – DECthreads Global Mutex Routines
pthread_lock_global_np Locks the DECthreads global mutex if it
is unlocked.
pthread_unlock_global_np
Unlocks the DECthreads lobal mutex if
it is locked.
1.10.4 – Mutex Attributes Routines
pthread_mutexattr_gettype_np
Obtains the mutex type attribute of a
mutex attributes object.
pthread_mutexattr_settype_np
Changes the mutex type attribute of a
mutex attributes object.
1.10.5 – Condition Variable Routines
pthread_cond_signal_int_np
Wakes one thread that is waiting on a
condition variable (called from interrupt
level only).
1.10.6 – DECthreads Exception Object Routines
pthread_exc_get_status_np
Obtains a system-defined error status
from a DECthreads status exception object.
pthread_exc_matches_np Determines whether two DECthreads exception
objects are identical.
pthread_exc_report_np Produces a message that reports what a
specified DECthreads status exception
object represents.
pthread_exc_set_status_np
Imports a system-defined error status
into a DECthreads address exception object.
2 – Application Routines
2.1 – exceptions
NAME
exceptions - Exception handling in DCE Threads
DESCRIPTION
DCE Threads provides the following two ways to obtain information about
the status of a threads routine:
o The routine returns a status value to the thread.
o The routine raises an exception.
Before you write a multithreaded program, you must choose only one of
the preceding two methods of receiving status. These two methods cannot
be used together in the same code module.
The POSIX P1003.4a (pthreads) draft standard specifies that errors be
reported to the thread by setting the external variable errno to an
error code and returning a function value of -1. The threads reference
pages document this status value-returning interface. However, an
alternative to status values is provided by DCE Threads in the
exception-returning interface.
Access to exceptions from the C language is defined by the macros in the
exc_handling.h file. The exc_handling.h header file is included automat-
ically when you include pthread_exc.h.
To use the exception-returning interface, replace
#include <pthread.h>
with the following include statement:
#include <pthread_exc.h>
The following example shows the syntax for handling exceptions:
TRY
try_block
[CATCH (exception_name)
handler_block]...
[CATCH_ALL
handler_block]
ENDTRY
2.2 – pthread_attr_create
NAME
pthread_attr_create - Creates a thread attributes object
SYNOPSIS
#include <pthread.h>
int pthread_attr_create (pthread_attr_t *attr);
PARAMETERS
attr Thread attributes object created.
DESCRIPTION
The pthread_attr_create() routine creates a thread attributes object
that is used to specify the attributes of threads when they are created.
The attributes object created by this routine is only used in calls to
pthread_create().
The individual attributes (internal fields) of the attributes object are
set to default values. (The default values of each attribute are dis-
cussed in the descriptions of the following services.) Use the following
routines to change the individual attributes:
o pthread_attr_setinheritsched()
o pthread_attr_setprio()
o pthread_attr_setsched()
o pthread_attr_setstacksize()
When an attributes object is used to create a thread, the values of the
individual attributes determine the characteristics of the new object.
Attributes objects perform in a manner similar to additional parameters.
Changing individual attributes does not affect any threads that were
previously created using the attributes object.
RETURN VALUES
If the function fails, -1 is returned and errno may be set to one
of the following values:
Return Error Description
___________________________________________________________
0 Successful completion.
-1 [ENOMEM] Insufficient memory exists to create
the thread attributes object.
-1 [EINVAL] The value specified by attr is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_attr_delete
pthread_attr_setinheritsched
pthread_attr_setprio
pthread_attr_setsched
pthread_attr_setstacksize
pthread_create
2.3 – pthread_attr_delete
NAME
pthread_attr_delete - Deletes a thread attributes object
SYNOPSIS
#include <pthread.h>
int pthread_attr_delete(pthread_attr_t *attr);
PARAMETERS
attr Thread attributes object deleted.
DESCRIPTION
The pthread_attr_delete() routine deletes a thread attributes object and
gives permission to reclaim storage for the thread attributes object.
Threads that were created using this thread attributes object are not
affected by the deletion of the thread attributes object.
The results of calling this routine are unpredictable if the value
specified by the attr parameter refers to a thread attributes object
that does not exist.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by attr is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_attr_create
2.4 – pthread_attr_getinheritsched
NAME
pthread_attr_getinheritsched - Obtains the inherit
scheduling attribute
SYNOPSIS
#include <pthread.h>
int pthread_attr_getinheritsched(pthread_attr_t attr);
PARAMETERS
attr Thread attributes object whose inherit scheduling
attribute is obtained.
DESCRIPTION
The pthread_attr_getinheritsched() routine obtains the value of the
inherit scheduling attribute in the specified thread attributes object.
The inherit scheduling attribute specifies whether threads created using
the attributes object inherit the scheduling attributes of the creating
thread, or use the scheduling attributes stored in the attributes object
that is passed to pthread_create().
The default value of the inherit scheduling attribute is
PTHREAD_INHERIT_SCHED.
RETURN VALUES
On successful completion, this routine returns the inherit scheduling
attribute value.
If the function fails, errno may be set to one of the following values:
Return Error Description
________________________________________________________________
Inherit scheduling Successful completion.
attribute
-1 [EINVAL] The value specified by attr
is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_attr_create
pthread_attr_setinheritsched
pthread_create
2.5 – pthread_attr_getprio
NAME
pthread_attr_getprio - Obtains the scheduling priority attribute
SYNOPSIS
#include <pthread.h>
int pthread_attr_getprio(pthread_attr_t attr);
PARAMETERS
attr Thread attributes object whose priority attribute
is obtained.
DESCRIPTION
The pthread_attr_getprio() routine obtains the value of the scheduling
priority of threads created using the thread attributes object specified
by the attr parameter.
RETURN VALUES
On successful completion, this routine returns the scheduling priority
attribute value.
If the function fails, errno may be set to one of the following values:
Return Error Description
_________________________________________________________
Scheduling priority Successful completion.
attribute
-1 [EINVAL] The value specified by attr
is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_attr_create
pthread_attr_setprio
pthread_create
2.6 – pthread_attr_getsched
NAME
pthread_attr_getsched - Obtains the value of the scheduling
policy attribute
SYNOPSIS
#include <pthread.h>
int pthread_attr_getsched(pthread_attr_t attr);
PARAMETERS
attr Thread attributes object whose scheduling policy
attribute is obtained.
DESCRIPTION
The pthread_attr_getsched() routine obtains the scheduling policy of
threads created using the thread attributes object specified by the attr
parameter. The default value of the scheduling attribute is SCHED_OTHER.
RETURN VALUES
On successful completion, this routine returns the value of the
scheduling policy attribute.
If the function fails, errno may be set to one of the following values:
Return Error Description
________________________________________________________________
Scheduling policy Successful completion.
attribute
-1 [EINVAL] The value specified by attr
is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_attr_create
pthread_attr_setsched
pthread_create
2.7 – pthread_attr_getstacksize
NAME
pthread_attr_getstacksize - Obtains the value of the
stacksize attribute
SYNOPSIS
#include <pthread.h>
long pthread_attr_getstacksize(pthread_attr_t attr);
PARAMETERS
attr Thread attributes object whose stacksize attribute
is obtained.
DESCRIPTION
The pthread_attr_getstacksize() routine obtains the minimum size (in
bytes) of the stack for a thread created using the thread attributes
object specified by the attr parameter.
RETURN VALUES
On successful completion, this routine returns the stacksize attribute
value.
If the function fails, errno may be set to one of the following values:
Return Error Description
__________________________________________________________
Stacksize attribute Successful completion.
-1 [EINVAL] The value specified by
attr is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_attr_create
pthread_attr_setstacksize
pthread_create
2.8 – pthread_attr_setinheritsched
NAME
pthread_attr_setinheritsched - Changes the inherit scheduling
attribute
SYNOPSIS
#include <pthread.h>
int pthread_attr_setinheritsched( pthread_attr_t attr,
int inherit );
PARAMETERS
attr Thread attributes object to be modified.
inherit New value for the inherit scheduling attribute.
Valid values are as follows:
PTHREAD_INHERIT_SCHED
This is the default value. The created
thread inherits the current priority
and scheduling policy of the thread
calling pthread_create().
PTHREAD_DEFAULT_SCHED
The created thread starts execution with
the priority and scheduling policy stored
in the thread attributes object.
DESCRIPTION
The pthread_attr_setinheritsched() routine changes the inherit schedul-
-ing attribute of thread creation. The inherit scheduling attribute spe
cifies whether threads created using the specified thread attributes obj
ect inherit the scheduling attributes of the creating thread, or use the
scheduling attributes stored in the thread attributes object that is
passed to pthread_create().
The first thread in an application that is not created by an explicit
call to pthread_create() has a scheduling policy of SCHED_OTHER. (See
the pthread_attr_setprio() and pthread_attr_setsched() routines for more
information on valid priority values and valid scheduling policy values,
respectively.)
Inheriting scheduling attributes (instead of using the scheduling attri-
butes stored in the attributes object) is useful when a thread is creat-
ing 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 the function fails, -1 is returned, and errno may be set to one of
the following values:
Return Error Description
___________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by attr is invalid.
-1 [EINVAL] The value specified by inherit is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_attr_create
pthread_attr_getinheritsched
pthread_attr_setprio
pthread_attr_setsched
pthread_create
2.9 – pthread_attr_setprio
NAME
pthread_attr_setprio - Changes the scheduling priority attribute of
thread creation
SYNOPSIS
#include <pthread.h>
int pthread_attr_setprio( pthread_attr_t *attr,
int priority );
PARAMETERS
attr Thread attributes object modified.
priority New value for the priority attribute. The
priority attribute depends on scheduling
policy. Valid values fall within one of the
following ranges:
o PRI_OTHER_MIN <= priority <= PRI_OTHER_MAX
(use with the SCHED_OTHER policy)
o PRI_FIFO_MIN <= priority <= PRI_FIFO_MAX
(use with the SCHED_FIFO policy)
o PRI_RR_MIN <= priority <= PRI_RR_MAX
(use with the SCHED_RR policy)
o PRI_FG_MIN_NP <= priority <= PRI_FG_MAX_NP
(use with the SCHED_FG_NP policy)
o PRI_BG_MIN_NP <= priority <= PRI_BG_MAX_NP
(use with the SCHED_BG_NP policy)
The default priority is the midpoint between PRI_OTHER_MIN and
PRI_OTHER_MAX. To specify a minimum or maximum priority, use the
appropriate symbol; for example, PRI_FIFO_MIN or PRI_FIFO_MAX. To
specify a value between the minimum and maximum, use an appropriate
arithmetic expression. For example, to specify a priority midway
between the minimum and maximum for the Round Robin scheduling policy,
specify the following concept using your programming language's syntax:
pri_rr_mid = (PRI_RR_MIN + PRI_RR_MAX)/2
If your expression results in a value outside the range of minimum to
maximum, an error results when you attempt to use it.
DESCRIPTION
The pthread_attr_setprio() routine sets the execution priority of
threads that are created using the attributes object specified by the
attr parameter.
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 this routine and pthread_create(), call
pthread_attr_setinheritsched() and specify the value
PTHREAD_DEFAULT_SCHED for the inherit parameter.
An application specifies priority only to express the urgency of execut-
ing the thread relative to other threads. Priority is not used to con-
trol mutual exclusion when accessing shared data.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by attr is invalid.
-1 [ERANGE] One or more parameters supplied have an
invalid value.
-1 [EPERM] The caller does not have the appropriate
privileges to set the priority of the
specified thread.
RELATED INFORMATION
FUNCTIONS: pthread_attr_create
pthread_attr_getprio
pthread_attr_setinheritsched
pthread_create
2.10 – pthread_attr_setsched
NAME
pthread_attr_setsched - Changes the scheduling policy attribute of
thread creation
SYNOPSIS
#include <pthread.h>
int pthread_attr_setsched( pthread_attr_t *attr
int *scheduler );
PARAMETERS
attr Thread attributes object modified.
scheduler New value for the scheduling policy attribute.
Valid values are as follows:
SCHED_FIFO (First In, First Out)
The highest-priority thread runs until it
blocks. If there is more than one thread
with the same priority, and that priority
is the highest among other threads, the
first thread to begin running continues
until it blocks.
SCHED_RR (Round Robin)
The highest-priority thread runs until it
blocks; however, threads of equal priority,
if that priority is the highest among other
threads, are timesliced. Timeslicing is a
process in which threads alternate using
available processors.
SCHED_OTHER (Default)
All threads are timesliced. SCHED_OTHER
ensures that all threads, regardless of
priority, receive some scheduling so that
no thread is completely denied execution
time. (However, SCHED_OTHER threads can be
denied execution time by SCHED_FIFO or
SCHED_RR threads.)
SCHED_FG_NP (Foreground)
Same as SCHED_OTHER. Threads are time-
sliced and priorities can be modified
dynamically by the scheduler to ensure
fairness.
SCHED_BG_NP (Background)
Ensures that all threads, regardless of
priority, receive some scheduling. However,
SCHED_BG_NP can be denied execution by
SCHED_FIFO or SCHED_RR threads.
DESCRIPTION
The pthread_attr_setsched() routine sets the scheduling policy of a
thread that is created using the attributes object specified by the attr
parameter. The default value of the scheduling attribute is SCHED_OTHER.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by attr is invalid.
-1 [EINVAL] The value specified by scheduler is invalid.
-1 [EPERM] The caller does not have the appropriate
privileges to set the priority of the
specified thread.
RELATED INFORMATION
FUNCTIONS: pthread_attr_create
pthread_attr_getsched
pthread_attr_setinheritsched
pthread_create
2.11 – pthread_attr_setstacksize
NAME
pthread_attr_setstacksize - Changes the stacksize attribute of
thread creation
SYNOPSIS
#include <pthread.h>
int pthread_attr_setstacksize( pthread_attr_t *attr,
long stacksize );
PARAMETERS
attr Thread attributes object modified.
stacksize New value for the stacksize attribute. The
stacksize parameter specifies the minimum size
(in bytes) of the stack needed for a thread.
DESCRIPTION
The pthread_attr_setstacksize() routine sets the minimum size (in bytes)
of the stack needed for a thread created using the attributes object
specified by the attr parameter. Use this routine to adjust the size of
the writable area of the stack. The default value of the stacksize
attribute is machine specific.
A thread's stack is fixed at the time of thread creation. Only the main
or initial thread can dynamically extend its stack.
Most 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 the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by attr is invalid.
-1 [EINVAL] The value specified by stacksize is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_attr_create
pthread_attr_getstacksize
pthread_create
2.12 – pthread_cancel
NAME
pthread_cancel - Allows a thread to request that it or another
thread terminate execution
SYNOPSIS
#include <pthread.h>
int pthread_cancel(pthread_t thread);
PARAMETERS
thread Thread that receives a cancel request.
DESCRIPTION
The pthread_cancel() routine sends a cancel to the specified thread. A
cancel is a mechanism by which a calling thread informs either itself or
the called thread to terminate as quickly as possible. Issuing a cancel
does not guarantee that the canceled thread receives or handles the can-
cel. The canceled thread can delay processing the cancel after receiving
it. For instance, if a cancel arrives during an important operation, the
canceled thread can continue if what it is doing cannot be interrupted
at the point where the cancel is requested.
Because of communications delays, the calling thread can only rely on
the fact that a cancel eventually becomes pending in the designated
thread (provided that the thread does not terminate beforehand). Furth-
ermore, the calling thread has no guarantee that a pending cancel is to
be delivered because delivery is controlled by the designated thread.
Termination processing when a cancel is delivered to a thread is similar
to pthread_exit(). Outstanding cleanup routines are executed in the con-
text of the target thread, and a status of -1 is made available to any
threads joining with the target thread.
This routine is preferred in implementing Ada's abort statement and any
other language (or software-defined construct) for requesting thread
cancellation.
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 the function fails, errno may be set to one of the following values:
Return Error Description
____________________________________________________
0 Successful completion.
-1 [EINVAL] The specified thread is invalid.
-1 [ERSCH] The specified thread does not refer
to a currently existing thread.
RELATED INFORMATION
FUNCTIONS: pthread_exit
pthread_join
pthread_setasynccancel
pthread_setcancel
pthread_testcancel
2.13 – pthread_cleanup_pop
NAME
pthread_cleanup_pop - Removes the cleanup handler at the top of the
cleanup stack and optionally executes it
SYNOPSIS
#include <pthread.h>
void pthread_cleanup_pop(int execute);
PARAMETERS
execute Integer that specifies whether the cleanup
routine that is popped should be executed or
just discarded. If the value is nonzero, the
cleanup routine is executed.
DESCRIPTION
The pthread_cleanup_pop() routine removes the routine specified in
pthread_cleanup_push() from the top of the calling thread's cleanup
stack and executes it if the value specified in execute is nonzero.
This routine and pthread_cleanup_push() are implemented as macros and
must be displayed 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 correspond-
ing } (right brace).
RETURN VALUES
This routine must be used as a statement.
RELATED INFORMATION
FUNCTIONS: pthread_cleanup_push
2.14 – pthread_cleanup_push
NAME
pthread_cleanup_push - Establishes a cleanup handler
SYNOPSIS
#include <pthread.h>
void pthread_cleanup_push( void routine,
pthread_addr_t arg );
PARAMETERS
routine Routine executed as the cleanup handler.
arg Parameter executed with the cleanup routine.
DESCRIPTION
The pthread_cleanup_push() 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 parameter when any of the following
actions occur:
o The thread calls pthread_exit().
o The thread is canceled.
o The thread calls pthread_cleanup_pop() and specifies a nonzero
value for the execute parameter.
This routine and pthread_cleanup_pop() are implemented as macros and
must be displayed 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
This routine must be used as a statement.
RELATED INFORMATION
FUNCTIONS: pthread_cancel
pthread_cleanup_pop
pthread_exit
pthread_testcancel
2.15 – pthread_condattr_create
NAME
pthread_condattr_create - Creates a condition variable attributes
object
SYNOPSIS
#include <pthread.h>
int pthread_condattr_create(pthread_condattr_t *attr);
PARAMETERS
attr Condition variable attributes object that is
created.
DESCRIPTION
The pthread_condattr_create() routine creates a condition variable
attributes object that is used to specify the attributes of condition
variables when they are created. The condition variable attributes
object is initialized with the default value for all of the attributes
defined by a given implementation.
When a condition variable attributes object is used to create a condi-
tion variable, the values of the individual attributes determine the
characteristics of the new object. Attributes objects act like addi-
tional parameters to object creation. Changing individual attributes
does not affect objects that were previously created using the attri-
butes object.
RETURN VALUES
The created condition variable attributes object is returned to the attr
parameter.
If the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by attr is invalid.
-1 [ENOMEM] Insufficient memory exists to create
the condition variable attributes object.
RELATED INFORMATION
FUNCTIONS: pthread_condattr_delete
pthread_cond_init
2.16 – pthread_condattr_delete
NAME
pthread_condattr_delete - Deletes a condition variable attributes
object
SYNOPSIS
#include <pthread.h>
int pthread_condattr_delete(pthread_condattr_t *attr);
PARAMETERS
attr Condition variable attributes object deleted.
DESCRIPTION
The pthread_condattr_delete() routine deletes a condition variable
attributes object. Call this routine when a condition variable attri-
butes object created by pthread_condattr_create() is no longer refer-
enced.
This routine gives permission to reclaim storage for the condition vari-
able attributes object. Condition variables that are created using this
attributes object are not affected by the deletion of the condition
variable attributes object.
The results of calling this routine are unpredictable if the handle
specified by the attr parameter refers to an attributes object that does
not exist.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by attr is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_condattr_create
2.17 – pthread_cond_broadcast
NAME
pthread_cond_broadcast - Wakes all threads that are waiting on
a condition variable
SYNOPSIS
#include <pthread.h>
int pthread_cond_broadcast(pthread_cond_t *cond);
PARAMETERS
cond Condition variable broadcast.
DESCRIPTION
The pthread_cond_broadcast() routine wakes all threads waiting on a con-
dition variable. 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. If any one waiting thread might be able
to proceed, call pthread_cond_signal().
Call this routine when the associated mutex is either locked or
unlocked.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by cond is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_cond_destroy
pthread_cond_init
pthread_cond_signal
pthread_cond_timedwait
pthread_cond_wait
2.18 – pthread_cond_destroy
NAME
pthread_cond_destroy - Deletes a condition variable
SYNOPSIS
#include <pthread.h>
int pthread_cond_destroy(pthread_cond_t *cond);
PARAMETERS
cond Condition variable deleted.
DESCRIPTION
The pthread_cond_destroy() routine deletes a condition variable. Call
this routine when a condition variable is no longer referenced. The
effect of calling this routine is to give permission to reclaim storage
for the condition variable.
The results of this routine are unpredictable if the condition variable
specified in cond does not exist.
The results of this routine are also unpredictable if there are threads
waiting for the specified condition variable to be signaled or broadcast
when it is deleted.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by cond is invalid.
-1 [EBUSY] A thread is currently executing a
pthread_cond_timedwait() routine or
pthread_cond_wait() on the condition
variable specified in cond.
RELATED INFORMATION
FUNCTIONS: pthread_cond_broadcast
pthread_cond_init
pthread_cond_signal
pthread_cond_timedwait
pthread_cond_wait
2.19 – pthread_cond_init
NAME
pthread_cond_init - Creates a condition variable
SYNOPSIS
#include <pthread.h>
int pthread_cond_init( pthread_cond_t *cond,
pthread_condattr_t attr );
PARAMETERS
cond Condition variable that is created.
attr Condition variable attributes object that
defines the characteristics of the condition
variable created. If you specify
pthread_condattr_default, default attributes
are used.
DESCRIPTION
The pthread_cond_init() routine creates and initializes a condition
variable. A condition variable is a synchronization object used in con-
junction with a mutex. A mutex controls access to shared data; a condi-
tion variable allows threads to wait for that data to enter a defined
state. The state is defined by a Boolean expression called a predicate.
A condition variable is signaled or broadcast to indicate that a predi-
cate might have become true. The broadcast operation indicates that all
waiting threads need to resume and reevaluate the predicate. The signal
operation is used when any one waiting thread can continue.
If a thread that holds a mutex determines that the shared data is not in
the correct state for it to proceed (the associated predicate is not
true), it waits on a condition variable associated with the desired
state. Waiting on the condition variable automatically releases the
mutex so that other threads can modify or examine the shared data. When
a thread modifies the state of the shared data so that a predicate might
be true, it signals or broadcasts on the appropriate condition variable
so that threads waiting for that predicate can continue.
It is important that all threads waiting on a particular condition vari-
able at any time hold the same mutex. If they do not, the behavior of
the wait operation is unpredictable (an implementation can use the mutex
to control internal access to the condition variable object). However,
it is legal for a client to store condition variables and mutexes and
later reuse them in different combinations. The client must ensure that
no threads use the condition variable with the old mutex. At any time,
an arbitrary number of condition variables can be associated with a sin-
gle mutex, each representing a different predicate of the shared data
protected by that mutex.
Condition variables are not owned by a particular thread. Any associated
storage is not automatically deallocated when the creating thread ter-
minates.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
__________________________________________________
0 Successful completion.
-1 [EAGAIN] The system lacks the necessary resources
to initialize another condition variable.
-1 [EINVAL] Invalid attributes object.
-1 [ENOMEM] Insufficient memory exists to initialize
the condition variable.
RELATED INFORMATION
FUNCTIONS: pthread_cond_broadcast
pthread_cond_destroy
pthread_cond_signal
pthread_cond_timedwait
pthread_cond_wait
2.20 – pthread_cond_signal
NAME
pthread_cond_signal - Wakes one thread that is waiting on a
condition variable
SYNOPSIS
#include <pthread.h>
int pthread_cond_signal(pthread_cond_t *cond);
PARAMETERS
cond Condition variable signaled.
DESCRIPTION
The pthread_cond_signal() routine wakes one thread waiting on a condi-
tion variable. Calling this routine implies that data guarded by the
associated mutex has changed so that it is possible for a single waiting
thread to proceed. Call this routine when any thread waiting on the
specified condition variable might find its predicate true, but only one
thread needs to proceed.
The scheduling policy determines which thread is awakened. For policies
SCHED_FIFO and SCHED_RR a blocked thread is chosen in priority order.
Call this routine when the associated mutex is either locked or
unlocked.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by cond is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_cond_broadcast
pthread_cond_destroy
pthread_cond_init
pthread_cond_timedwait
pthread_cond_wait
2.21 – pthread_cond_timedwait
NAME
pthread_cond_timedwait - Causes a thread to wait for a condition
variable to be signaled or broadcast
SYNOPSIS
#include <pthread.h>
int pthread_cond_timedwait( pthread_cond_t *cond,
pthread_mutex_t *mutex,
struct timespec *abstime );
PARAMETERS
cond Condition variable waited on.
mutex Mutex associated with the condition variable
specified in cond.
abstime Absolute time at which the wait expires, if the
condition has not been signaled or broadcast.
(See the pthread_get_expiration_np() routine,
which you can use to obtain a value for this
parameter.)
DESCRIPTION
The pthread_cond_timedwait() routine causes a thread to wait until one
of the following occurs:
o The specified condition variable is signaled or broadcast.
o The current system clock time is greater than or equal to the time
specified by the abstime parameter.
This routine is identical to pthread_cond_wait() except that this rou-
tine can return before a condition variable is signaled or broadcast-
specifically, when a specified time expires.
If the current time equals or exceeds the expiration time, this routine
returns immediately, without causing the current thread to wait.
Call this routine after you lock the mutex specified in mutex. The
results of this routine are unpredictable if this routine is called
without first locking the mutex.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by cond, mutex, or
abstime is invalid.
-1 [EAGAIN] The time specified by abstime expired.
-1 [EDEADLK] A deadlock condition is detected.
RELATED INFORMATION
FUNCTIONS: pthread_cond_broadcast
pthread_cond_destroy
pthread_cond_init
pthread_cond_signal
pthread_cond_wait
pthread_get_expiration_np
2.22 – pthread_cond_wait
NAME
pthread_cond_wait - Causes a thread to wait for a condition
variable to be signaled or broadcast
SYNOPSIS
#include <pthread.h>
int pthread_cond_wait( pthread_cond_t *cond,
pthread_mutex_t *mutex );
PARAMETERS
cond Condition variable waited on.
mutex Mutex associated with the condition variable
specified in cond.
DESCRIPTION
The pthread_cond_wait() routine causes a thread to wait for a condition
variable to be signaled or broadcast. Each condition corresponds to one
or more predicates based on shared data. The calling thread waits for
the data to reach a particular state (for the predicate to become true).
Call this routine after you have locked the mutex specified in mutex.
The results of this routine are unpredictable if this routine is called
without first locking the mutex.
This routine automatically releases the mutex and causes the calling
thread to wait on the condition. If the wait is satisfied as a result of
some thread calling pthread_cond_signal() or pthread_cond_broadcast(),
the mutex is reacquired and the routine returns.
A thread that changes the state of storage protected by the mutex in
such a way that a predicate associated with a condition variable might
now be true must call either pthread_cond_signal() or
pthread_cond_broadcast() for that condition variable. If neither call is
made, any thread waiting on the condition variable continues to wait.
This routine might (with low probability) return when the condition
variable has not been signaled or broadcast. When a spurious wakeup
occurs, the mutex is reacquired before the routine returns. (To handle
this type of situation, enclose this routine in a loop that checks the
predicate.)
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
_________________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by cond or mutex is invalid.
-1 [EDEADLK] A deadlock condition is detected.
RELATED INFORMATION
FUNCTIONS: pthread_cond_broadcast
pthread_cond_destroy
pthread_cond_init
pthread_cond_signal
pthread_cond_timedwait
2.23 – pthread_create
NAME
pthread_create - Creates a thread object and thread
SYNOPSIS
#include <pthread.h>
int pthread_create( pthread_t *thread,
pthread_attr_t attr,
pthread_startroutine_t start_routine,
pthread_addr_t arg );
PARAMETERS
thread Handle to the thread object created.
attr Thread attributes object that defines the
characteristics of the thread being created.
If you specify pthread_attr_default, default
attributes are used.
start_routine Function executed as the new thread's start
routine.
arg Address value copied and passed to the
thread's start routine.
DESCRIPTION
The pthread_create() routine creates a thread object and a thread. A
thread is a single, sequential flow of control within a program. It is
the active execution of a designated routine, including any nested rou-
tine invocations. A thread object defines and controls the executing
thread.
CREATING A THREAD
Calling this routine sets into motion the following actions:
o An internal thread object is created to describe the thread.
o The associated executable thread is created with attributes
specified by the attr parameter (or with default attributes
if pthread_attr_default is specified).
o The thread parameter receives the new thread.
o The start_routine function is called when this routine
completes successfully.
THREAD EXECUTION
The thread is created in the ready state and therefore might
immediately begin executing the function specified by the
start_routine parameter. The newly created thread begins running
before pthread_create() completes if the new thread follows the
SCHED_RR or SCHED_FIFO scheduling policy or has a priority higher
than the creating thread, or both. Otherwise, the new thread
begins running at its turn, which with sufficient processors
might also be before pthread_create() returns.
The start_routine parameter is passed a copy of the arg
parameter. The value of the arg parameter is unspecified.
The thread object exists until the pthread_detach() routine is
called or the thread terminates, whichever occurs last.
The synchronization between the caller of pthread_create() and the
newly created thread is through the use of the pthread_join()
routine (or any other mutexes or condition variables they agree to
use).
TERMINATING A THREAD
A thread terminates when one of the following events occurs:
o The thread returns from its start routine.
o The thread exits (within a routine) as the result of calling
the pthread_exit() routine.
o The thread is canceled.
WHEN A THREAD TERMINATES
The following actions are performed when a thread terminates:
o If the thread terminates by returning from its start routine
or calling pthread_exit(), the return value is copied into the
thread object. If the start routine returns normally and the
start routine is a procedure that does not return a value,
then the result obtained by pthread_join() is unpredictable.
If the thread has been cancelled, a return value of -1 is
copied into the thread object. The return value can be retri-
-eved by other threads by calling the pthread_join() routine.
o A destructor for each thread-specific data point is removed
from the list of destructors for this thread and then is
called. This step destroys all the thread-specific data
associated with the current thread.
o Each cleanup handler that has been declared by
pthread_cleanup_push() and not yet removed by
pthread_cleanup_pop() is called. The most recently pushed
handler is called first.
o A flag is set in the thread object indicating that the thread
has terminated. This flag must be set in order for callers of
pthread_join() to return from the call.
o A broadcast is made so that all threads currently waiting in a
call to pthread_join() can return from the call.
o The thread object is marked to indicate that it is no longer
needed by the thread itself. A check is made to determine if
the thread object is no longer needed by other threads; that
is, if pthread_detach() has been called. If that routine is
called, then the thread object is deallocated.
RETURN VALUES
Upon successful completion, this routine stores the identifier of the
created thread at thread and returns 0. Otherwise, a value of -1 is
returned and no thread is created, the contents of thread are undefined,
and errno may be set to one of the following values:
Return Error Description
__________________________________________________
0 Successful completion.
-1 [EAGAIN] The system lacks the necessary resources
to create another thread.
-1 [ENOMEM] Insufficient memory exists to create the
thread object. This is not a temporary
condition.
RELATED INFORMATION
FUNCTIONS: pthread_attr_create
pthread_cancel
pthread_detach
pthread_exit
pthread_join
2.24 – pthread_delay_np
NAME
pthread_delay_np - Causes a thread to wait for a specified period
SYNOPSIS
#include <pthread.h>
int pthread_delay_np( struct timespec *interval );
PARAMETERS
interval Number of seconds and nanoseconds that the
calling thread waits before continuing
execution. The value specified must be
greater than or equal to 0 (zero).
DESCRIPTION
The pthread_delay_np() routine causes a thread to delay execution for a
specified period of elapsed wall clock time. The period of time the
thread waits is at least as long as the number of seconds and
nanoseconds specified in the interval parameter.
Specifying an interval of 0 seconds and 0 nanoseconds is allowed and can
result in the thread giving up the processor or delivering a pending
cancel.
The struct timespec structure contains two fields, as follows:
o The tv_sec field is an integer number of seconds.
o The tv_nsec field is an integer number of nanoseconds.
This routine is not portable.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
_______________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by interval is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_yield
2.25 – pthread_detach
NAME
pthread_detach - Marks a thread object for deletion
SYNOPSIS
#include <pthread.h>
int pthread_detach( pthread_t *thread );
PARAMETERS
thread Thread object marked for deletion.
DESCRIPTION
The pthread_detach() routine indicates that storage for the specified
thread is reclaimed when the thread terminates. This includes storage
for the thread parameter's return value. If thread has not terminated
when this routine is called, this routine does not cause it to ter-
minate.
Call this routine when a thread object is no longer referenced. Addi-
tionally, call this routine for every thread that is created to ensure
that storage for thread objects does not accumulate.
You cannot join with a thread after the thread has been detached.
The results of this routine are unpredictable if the value of thread
refers to a thread object that does not exist.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
_____________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by thread is invalid.
-1 [ESRCH] The value specified by thread does not
refer to an existing thread.
RELATED INFORMATION
FUNCTIONS: pthread_cancel
pthread_create
pthread_exit
pthread_join
2.26 – pthread_equal
NAME
pthread_equal - Compares one thread identifier to another thread
identifier.
SYNOPSIS
#include <pthread.h>
equal = pthread_equal( pthread_t *thread1,
pthread_t thread2 );
PARAMETERS
thread1 The first thread identifier to be compared.
thread2 The second thread identifier to be
compared.
DESCRIPTION
This routine compares one thread identifier to another thread identi-
-fier.(This routine does not check whether the objects that corres-
-pond to the identifiers currently exist.) If the identifiers have
values indicating that they designate the same object, 1 (true) is
returned. If the values do not designate the same object, 0 (false) is
returned.
This routine is implemented as a C macro.
RETURN VALUES
Possible return values are as follows:
Return Error Description
__________________________________________________
0 Values of thread1 and thread2 do not designate the
same object.
1 Values of thread1 and thread2 designate the same
object.
EXAMPLES
equal = pthread_equal (thread1, thread2)
RELATED INFORMATION
FUNCTIONS: pthread_create
2.27 – pthread_exit
NAME
pthread_exit - Terminates the calling thread
SYNOPSIS
#include <pthread.h>
void pthread_exit( pthread_addr_t status );
PARAMETERS
status Address value copied and returned to the
caller of pthread_join().
DESCRIPTION
The pthread_exit() routine terminates the calling thread and makes a
status value available to any thread that calls pthread_join() and
specifies the terminating thread.
An implicit call to pthread_exit() is issued when a thread returns from
the start routine that was used to create it. The function's return
value serves as the thread's exit status. If the return value is -1, an
error exit is forced for the thread instead of a normal exit. The pro-
cess exits when the last running thread calls pthread_exit(), with an
undefined exit status.
RESTRICTIONS
The pthread_exit() routine does not work in the main (initial) thread
because DCE Threads relies on information at the base of thread stacks;
this information does not exist in the main thread.
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: pthread_create
pthread_detach
pthread_join
2.28 – pthread_getprio
NAME
pthread_getprio - Obtains the current priority of a thread
SYNOPSIS
#include <pthread.h>
int pthread_getprio( pthread_t thread );
PARAMETERS
thread Thread whose priority is obtained.
DESCRIPTION
The pthread_getprio() routine obtains the current priority of a thread.
The current priority is different from the initial priority of the
thread if the pthread_setprio() routine is called.
The exact effect of different priority values depends upon the schedul-
ing policy assigned to the thread.
RETURN VALUES
The current priority value of the thread specified in thread is
returned. (See the pthread_setprio() reference page for valid values.)
If the function fails, errno may be set to one of the following values:
Return Error Description
________________________________________________________
Priority value Successful completion.
-1 [EINVAL] The value specified by thread is invalid.
-1 [ESRCH] The value specified by thread does not
refer to an existing thread.
RELATED INFORMATION
FUNCTIONS: pthread_attr_setprio
pthread_setprio
pthread_setscheduler
2.29 – pthread_getscheduler
NAME
pthread_getscheduler - Obtains the current scheduling policy
of a thread
SYNOPSIS
#include <pthread.h>
int pthread_getscheduler( pthread_t thread );
PARAMETERS
thread Thread whose scheduling policy is obtained.
DESCRIPTION
The pthread_getscheduler() routine obtains the current scheduling policy
of a thread. The current scheduling policy of a thread is different from
the initial scheduling policy if the pthread_setscheduler() routine is
called.
RETURN VALUES
The current scheduling policy value of the thread specified in thread is
returned. (See the pthread_setscheduler() reference page for valid
values.)
If the function fails, errno may be set to one of the following values:
Return Error Description
______________________________________________________________
Current scheduling policy Successful completion.
-1 [EINVAL] The value specified by thread
is invalid.
-1 [ESRCH] The value specified by thread does
not refer to an existing thread.
RELATED INFORMATION
FUNCTIONS: pthread_attr_setscheduler
pthread_setscheduler
2.30 – pthread_getspecific
NAME
pthread_getspecific - Obtains the thread-specific data associated
with the specified key
SYNOPSIS
#include <pthread.h>
int pthread_getspecific( pthread_key_t key,
pthread_addr_t *value );
PARAMETERS
key Context key value that identifies the data
value obtained. This key value must be obtained
from pthread_keycreate().
value Address of the current thread-specific data value
associated with the specified key.
DESCRIPTION
The pthread_getspecific() routine obtains the thread-specific data asso-
ciated with the specified key for the current thread.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
_____________________________________________
0 Successful completion.
-1 [EINVAL] The key value is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_keycreate
pthread_setspecific
2.31 – pthread_get_expiration_np
NAME
pthread_get_expiration_np - Obtains a value representing a desired
expiration time
SYNOPSIS
#include <pthread.h>
int pthread_get_expiration_np( struct timespec *delta,
struct timespec *abstime );
PARAMETERS
delta Number of seconds and nanoseconds to add to
the current system time. The result is the
time when a timed wait expires.
abstime Value representing the expiration time.
DESCRIPTION
The pthread_get_expiration_np() routine adds a specified interval to the
current absolute system time and returns a new absolute time. This new
absolute time is used as the expiration time in a call to
pthread_cond_timedwait().
This routine is not portable.
The struct timespec structure contains two fields, as follows:
o The tv_sec field is an integer number of seconds.
o The tv_nsec field is an integer number of nanoseconds.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
____________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by delta is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_cond_timedwait
2.32 – pthread_join
NAME
pthread_join - Causes the calling thread to wait for the
termination of a specified thread
SYNOPSIS
#include <pthread.h>
int pthread_join( pthread_t thread,
pthread_addr_t *status );
PARAMETERS
thread Thread whose termination is awaited by the
caller of this routine.
status Status value of the terminating thread when
that thread calls pthread_exit().
DESCRIPTION
The pthread_join() routine causes the calling thread to wait for the
termination of a specified thread. A call to this routine returns after
the specified thread has terminated.
Any number of threads can call this routine. All threads are awakened
when the specified thread terminates.
If the current thread calls this routine, a deadlock results.
The results of this routine are unpredictable if the value for thread
refers to a thread object that no longer exists.
RETURN VALUES
If the thread terminates normally, the exit status is the value that is
is optionally returned from the thread's start routine.
If the function fails, errno may be set to one of the following values:
Return Error Description
______________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by thread is invalid.
-1 [ESRCH] The value specified by thread does not
refer to a currently existing thread.
-1 [EDEADLK] A deadlock is detected.
RELATED INFORMATION
FUNCTIONS: pthread_create
pthread_detach
pthread_exit
2.33 – pthread_keycreate
NAME
pthread_keycreate - Generates a unique thread-specific data
key value
SYNOPSIS
#include <pthread.h>
int pthread_keycreate( pthread_key_t *key,
pthread_destructor_t destructor );
PARAMETERS
key Value of the new thread-specific data key.
destructor Procedure to be called to destroy a data value
associated with the created key when the thread
terminates.
DESCRIPTION
The pthread_keycreate() routine generates a unique thread-specific
data key value. This key value identifies a thread-specific data
value, which is an address of memory generated by the client containing
arbitrary data of any size.
Thread-specific data allows client software to associate information
with the current thread.
For example, thread-specific data can be used by a language runtime
library that needs to associate a language-specific thread-private data
structure with an individual thread. The thread-specific data routines
also provide a portable means of implementing the class of storage
called thread-private static, which is needed to support parallel
decomposition in the FORTRAN language.
This routine generates and returns a new key value. Each call to this
routine within a process returns a key value that is unique within an
application invocation. Calls to pthread_keycreate() must occur in ini-
tialization code guaranteed to execute only once in each process. The
pthread_once() routine provides a way of specifying such code.
When multiple facilities share access to thread-specific data, the
facilities must agree on the key value that is associated with the con-
text. The key value must be created only once and needs to be stored in
a location known to each facility. (It may be desirable to encapsulate
the creation of a key, and the setting and getting of context values for
that key, within a special facility created for that purpose.)
When a thread terminates, thread-specific data is automatically des-
troyed. For each thread-specific data currently associated with the
thread, the destructor routine associated with the key value of that
context is called. The order in which per-thread context destructors are
called at thread termination is undefined.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
_________________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by key is invalid.
-1 [EAGAIN] An attempt was made to allocate a key when
the key namespace is exhausted. This is not
a temporary condition.
-1 [ENOMEM] Insufficient memory exists to create the key.
RELATED INFORMATION
FUNCTIONS: pthread_getspecific
pthread_setspecific
2.34 – pthread_lock_global_np
NAME
pthread_lock_global_np - Locks the global mutex
SYNOPSIS
#include <pthread.h>
void pthread_lock_global_np();
DESCRIPTION
The pthread_lock_global_np() routine locks the global mutex. If the glo-
bal mutex is currently held by another thread when a thread calls this
routine, the thread waits for the global mutex to become available.
The thread that has locked the global mutex becomes its current owner
and remains the owner until the same thread has unlocked it. This rou-
tine returns with the global mutex in the locked state and with the
current thread as the global mutex's current owner.
Use the global mutex when calling a library package that is not designed
to run in a multithreaded environment. (Unless the documentation for a
library function specifically states that it is compatible with mul-
tithreading, assume that it is not compatible; in other words, assume it
is nonreentrant.)
The global mutex is one lock. Any code that calls any function that is
not known to be reentrant uses the same lock. This prevents dependencies
among threads calling library functions and those functions calling
other functions, and so on.
The global mutex is a recursive mutex. A thread that has locked the glo-
bal mutex can relock it without deadlocking. (The locking thread must
call pthread_unlock_global_np() as many times as it called this routine
to allow another thread to lock the global mutex.)
This routine is not portable.
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: pthread_mutexattr_setkind_np
pthread_mutex_lock
pthread_mutex_unlock
pthread_unlock_global_np
2.35 – pthread_mutexattr_create
NAME
pthread_mutexattr_create - Creates a mutex attributes object
SYNOPSIS
#include <pthread.h>
int pthread_mutexattr_create( pthread_mutexattr_t *attr );
PARAMETERS
attr Mutex attributes object created.
DESCRIPTION
The pthread_mutexattr_create() routine creates a mutex attributes object
used to specify the attributes of mutexes when they are created. The
mutex attributes object is initialized with the default value for all of
the attributes defined by a given implementation.
When a mutex attributes object is used to create a mutex, the values of
the individual attributes determine the characteristics of the new
object. Attributes objects act like additional parameters to object
creation. Changing individual attributes does not affect any objects
that were previously created using the attributes object.
RETURN VALUES
The created mutex attributes object is returned to the attr parameter.
If the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by attr is invalid.
-1 [ENOMEM] Insufficient memory exists to create
the mutex attributes object.
RELATED INFORMATION
FUNCTIONS: pthread_create
pthread_mutexattr_delete
pthread_mutexattr_getkind_np
pthread_mutexattr_setkind_np
pthread_mutex_init
2.36 – pthread_mutexattr_delete
NAME
pthread_mutexattr_delete - Deletes a mutex attributes object
SYNOPSIS
#include <pthread.h>
int pthread_mutexattr_delete( pthread_mutexattr_t *attr );
PARAMETERS
attr Mutex attributes object deleted.
DESCRIPTION
The pthread_mutexattr_delete() routine deletes a mutex attributes
object. Call this routine when a mutex attributes object is no longer
referenced by the pthread_mutexattr_create() routine.
This routine gives permission to reclaim storage for the mutex attri-
butes object. Mutexes that were created using this attributes object are
not affected by the deletion of the mutex attributes object.
The results of calling this routine are unpredictable if the attributes
object specified in the attr parameter does not exist.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by attr is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_mutexattr_create
2.37 – pthread_mutexattr_getkind_np
NAME
pthread_mutexattr_getkind_np - Obtains the mutex type attribute
used when a mutex is created
SYNOPSIS
#include <pthread.h>
int pthread_mutexattr_getkind_np( pthread_mutexattr_t *attr );
PARAMETERS
attr Mutex attributes object whose mutex type
is obtained.
DESCRIPTION
The pthread_mutexattr_getkind_np() routine obtains the mutex type
attribute that is used when a mutex is created. See the
pthread_mutexattr_setkind_np() reference page for information about
mutex type attributes.
This routine is not portable.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
______________________________________________________________
Mutex type attribute Successful completion.
-1 [EINVAL] The value specified by attr is
invalid.
RELATED INFORMATION
FUNCTIONS: pthread_mutexattr_create
pthread_mutexattr_setkind_np
pthread_mutex_init
2.38 – pthread_mutexattr_setkind_np
NAME
pthread_mutexattr_setkind_np - Specifies the mutex type attribute
SYNOPSIS
#include <pthread.h>
int pthread_mutexattr_setkind_np( pthread_mutexattr_t *attr,
int kind );
PARAMETERS
attr Mutex attributes object modified.
kind New value for the mutex type attribute. The
kind parameter specifies the type of mutex
that is created. Valid values are MUTEX_FAST_NP
(default), MUTEX_RECURSIVE_NP, and
MUTEX_NONRECURSIVE_NP.
DESCRIPTION
The pthread_mutexattr_setkind_np() routine sets the mutex type attribute
that is used when a mutex is created.
A fast mutex is locked and unlocked in the fastest manner possible. A
fast mutex can only be locked (obtained) once. All subsequent calls to
pthread_mutex_lock() cause the calling thread to block until the mutex
is freed by the thread that owns it. If the thread that owns the mutex
attempts to lock it again, the thread waits for itself to release the
mutex (causing a deadlock).
A recursive mutex can be locked more than once by the same thread
without causing that thread to deadlock. In other words, a single thread
can make consecutive calls to pthread_mutex_lock() without blocking.
The thread must then call pthread_mutex_unlock() the same number of
times as it called pthread_mutex_lock() before another thread can lock
the mutex.
A nonrecursive mutex is locked only once by a thread, like a fast mutex.
If the thread tries to lock the mutex again without first unlocking it,
the thread receives an error. Thus, nonrecursive mutexes are more
informative than fast mutexes because fast mutexes block in such a case,
leaving it up to you to determine why the thread no longer executes.
Also, if someone other than the owner tries to unlock a nonrecursive
mutex, an error is returned.
Never use a recursive mutex with condition variables because the impli-
cit unlock performed for a pthread_cond_wait() or
pthread_cond_timedwait() might not actually release the mutex. In that
case, no other thread can satisfy the condition of the predicate.
This routine is not portable.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
_____________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by attr or kind is invalid.
-1 [EPERM] The caller does not have the appropriate
privileges.
-1 [ERANGE] One or more parameters supplied have an invalid
value.
RELATED INFORMATION
FUNCTIONS: pthread_mutexattr_create
pthread_mutexattr_getkind_np
pthread_mutex_init
2.39 – pthread_mutex_destroy
NAME
pthread_mutex_destroy - Deletes a mutex
SYNOPSIS
#include <pthread.h>
int pthread_mutex_destroy( pthread_mutex_t *mutex );
PARAMETERS
mutex Mutex to be deleted.
DESCRIPTION
The pthread_mutex_destroy() routine deletes a mutex and must be called
when a mutex object is no longer referenced. The effect of calling this
routine is to reclaim storage for the mutex object.
It is illegal to delete a mutex that has a current owner (in other
words, is locked).
The results of this routine are unpredictable if the mutex object speci-
fied in the mutex parameter does not currently exist.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
________________________________________________________________
0 Successful completion.
-1 [EBUSY] An attempt was made to destroy a mutex
that is locked.
-1 [EINVAL] The value specified by mutex is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_mutex_init
pthread_mutex_lock
pthread_mutex_trylock
pthread_mutex_unlock
2.40 – pthread_mutex_init
NAME
pthread_mutex_init - Creates a mutex
SYNOPSIS
#include <pthread.h>
int pthread_mutex_init( pthread_mutex_t *mutex,
pthread_mutexattr_t attr );
PARAMETERS
mutex Mutex that is created.
attr Attributes object that defines the
characteristics of the created mutex.
If you specify pthread_mutexattr_default,
default attributes are used.
DESCRIPTION
The pthread_mutex_init() routine creates a mutex and initializes it to
the unlocked state. If the thread that called this routine terminates,
the created mutex is not automatically deallocated, because it is con-
sidered shared among multiple threads.
RETURN VALUES
If an error condition occurs, this routine returns -1, the mutex is not
initialized, the contents of mutex are undefined, and errno may be set
to one of the following values:
Return Error Description
__________________________________________________________
0 Successful completion.
-1 [EAGAIN] The system lacks the necessary resources to
initialize another mutex.
-1 [ENOMEM] Insufficient memory exists to initialize the
mutex.
RELATED INFORMATION
FUNCTIONS: pthread_mutexattr_create
pthread_mutexattr_getkind_np
pthread_mutexattr_setkind_np
pthread_mutex_lock
pthread_mutex_trylock
pthread_mutex_unlock
2.41 – pthread_mutex_lock
NAME
pthread_mutex_lock - Locks an unlocked mutex
SYNOPSIS
#include <pthread.h>
int pthread_mutex_lock( pthread_mutex_t *mutex );
PARAMETERS
mutex Mutex that is locked.
DESCRIPTION
The pthread_mutex_lock() routine locks a mutex. If the mutex is locked
when a thread calls this routine, the thread waits for the mutex to
become available.
The thread that has locked a mutex becomes its current owner and remains
the owner until the same thread has unlocked it. This routine returns
with the mutex in the locked state and with the current thread as the
mutex's current owner.
If you specified a fast mutex in a call to
pthread_mutexattr_setkind_np(), a deadlock can result if the current
owner of a mutex calls this routine in an attempt to lock the mutex a
second time. If you specified a recursive mutex in a call to
pthread_mutexattr_setkind_np(), the current owner of a mutex can relock
the same mutex without blocking. If you specify a nonrecursive mutex in
a call to pthread_mutexattr_setkind_np(), an error is returned and the
thread does not block if the current owner of a mutex calls this routine
in an attempt to lock the mutex a second time.
The preemption of a lower-priority thread that locks a mutex possibly
results in the indefinite blocking of higher-priority threads waiting
for the same mutex. The execution of the waiting higher-priority threads
is blocked for as long as there is a sufficient number of runable
threads of any priority between the lower-priority and higher-priority
values. Priority inversion occurs when any resource is shared between
threads with different priorities.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
_____________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by mutex is invalid.
-1 [EDEADLK] A deadlock condition is detected.
RELATED INFORMATION
FUNCTIONS: pthread_mutexattr_setkind_np
pthread_mutex_destroy
pthread_mutex_init
pthread_mutex_trylock
pthread_mutex_unlock
2.42 – pthread_mutex_trylock
NAME
pthread_mutex_trylock - Locks a mutex
SYNOPSIS
#include <pthread.h>
int pthread_mutex_trylock( pthread_mutex_t *mutex );
PARAMETERS
mutex Mutex that is locked.
DESCRIPTION
The pthread_mutex_trylock() routine locks a mutex. If the specified
mutex is locked when a thread calls this routine, the calling thread
does not wait for the mutex to become available.
When a thread calls this routine, an attempt is made to lock the mutex
immediately. If the mutex is successfully locked, 1 is returned and the
current thread is then the mutex's current owner.
If the mutex is locked by another thread when this routine is called, 0
(zero) is returned and the thread does not wait to acquire the lock. If
a fast mutex is owned by the current thread, 0 is returned. If a recur-
sive mutex is owned by the current thread, 1 is returned and the mutex
is relocked. (To unlock a recursive mutex, each call to
pthread_mutex_trylock() must be matched by a call to the
pthread_mutex_unlock() routine.)
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
____________________________________________________________
1 Successful completion.
0 The mutex is locked; therefore, it was
not acquired.
-1 [EINVAL] The value specified by mutex is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_mutexattr_setkind_np
pthread_mutex_destroy
pthread_mutex_init
pthread_mutex_lock
pthread_mutex_unlock
2.43 – pthread_mutex_unlock
NAME
pthread_mutex_unlock - Unlocks a mutex
SYNOPSIS
#include <pthread.h>
int pthread_mutex_unlock( pthread_mutex_t *mutex );
PARAMETERS
mutex Mutex that is unlocked.
DESCRIPTION
The pthread_mutex_unlock() routine unlocks a mutex. If no threads are
waiting for the mutex, the mutex unlocks with no current owner. If one
or more threads are waiting to lock the specified mutex, this routine
causes one thread to return from its call to pthread_mutex_lock(). The
scheduling policy is used to determine which thread acquires the mutex.
For the SCHED_FIFO and SCHED_RR policies, a blocked thread is chosen in
priority order.
The results of calling this routine are unpredictable if the mutex
specified in mutex is unlocked. The results of calling this routine are
also unpredictable if the mutex specified in mutex is currently owned by
a thread other than the calling thread.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
____________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by mutex is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_mutexattr_setkind_np
pthread_mutex_destroy
pthread_mutex_init
pthread_mutex_lock
pthread_mutex_trylock
pthread_unlock_global_np
2.44 – pthread_once
NAME
pthread_once - Calls an initialization routine executed by
one thread, a single time
SYNOPSIS
#include <pthread.h>
int pthread_once( pthread_once_t *once_block,
pthread_initroutine_t init_routine );
PARAMETERS
once_block Address of a record that defines the
one-time initialization code. Each
one-time initialization routine must
have its own unique pthread_once_t data
structure.
init_routine Address of a procedure that performs the
initialization. This routine is called
only once, regardless of the number of
times it and its associated once_block
are passed to pthread_once().
DESCRIPTION
The pthread_once() routine calls an initialization routine executed by
one thread, a single time. This routine allows you to create your own
initialization code that is guaranteed to be run only once, even if
called simultaneously by multiple threads or multiple times in the same
thread.
For example, a mutex or a thread-specfic data key must be created
exactly once. Calling pthread_once() prevents the code that creates a
mutex or thread-specific data from being called by multiple threads.
Without this routine, the execution must be serialized so that only one
thread performs the initialization. Other threads that reach the same
point in the code are delayed until the first thread is finished.
---------------------------- NOTE -------------------------------
If you specify an init_routine that directly or indirectly results
in a recursive call to pthread_once() and that specifies the same
init_routine argument, the recursive call can result in a deadlock.
------------------------------------------------------------------
This routine initializes the control record if it has not been initial-
ized and then determines if the client one-time initialization routine
has executed once. If it has not executed, this routine calls the ini-
tialization routine specified in init_routine. If the client one-time
initialization code has executed once, this routine returns.
The pthread_once_t data structure is a record that allows client ini-
tialization operations to guarantee mutual exclusion of access to the
initialization routine, and that each initialization routine is executed
exactly once.
The client code must declare a variable of type pthread_once_t to use
the client initialization operations. This variable must be initialized
using the pthread_once_init macro, as follows:
static pthread_once_t myOnceBlock = pthread_once_init;
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
__________________________________________
0 Successful completion.
-1 [EINVAL] Invalid parameter.
2.45 – pthread_self
NAME
pthread_self - Obtains the identifier of the current thread
SYNOPSIS
#include <pthread.h>
pthread_t pthread_self();
DESCRIPTION
The pthread_self() routine allows a thread to obtain its own identifier.
For example, this identifier allows a thread to set its own priority.
This value becomes meaningless when the thread object is deleted; that
is, when the thread terminates its execution and pthread_detach() is
called.
RETURN VALUES
Returns the identifier of the calling thread to pthread_t.
RELATED INFORMATION
FUNCTIONS: pthread_create
pthread_setprio
pthread_setscheduler
2.46 – pthread_setasynccancel
NAME
pthread_setasynccancel - Enables or disables the current
thread's asynchronous cancelability
SYNOPSIS
#include <pthread.h>
int pthread_setasynccancel( int state );
PARAMETERS
state State of asynchronous cancelability set for
the calling thread. On return, receives the
prior state of asynchronous cancelability.
Valid values are as follows:
CANCEL_ON Asynchronous cancelability is
enabled.
CANCEL_OFF Asynchronous cancelability is
disabled.
DESCRIPTION
The pthread_setasynccancel() routine enables or disables the current
thread's asynchronous cancelability and returns the previous cancelabil-
ity state to the state parameter.
When general cancelability is set to CANCEL_OFF, a cancel cannot be
delivered to the thread, even if a cancelable routine is called or asyn-
chronous cancelability is enabled. When general cancelability is set to
CANCEL_ON, cancelability depends on the state of the thread's asynchro-
nous cancelability.
When general cancelability is set to CANCEL_ON and asynchronous cancela-
bility is set to CANCEL_OFF, the thread can only receive a cancel at
specific cancellation points (for example, condition waits, thread
joins, and calls to the pthread_testcancel() routine). If both general
cancelability and asynchronous cancelability are set to CANCEL_ON, the
thread can be canceled at any point in its execution.
When a thread is created, the default asynchronous cancelability state
is CANCEL_OFF.
If you call this routine to enable asynchronous cancels, call it in a
region of code where asynchronous delivery of cancels is disabled by a
previous call to this routine. Do not call threads routines in regions
of code where asynchronous delivery of cancels is enabled. The previous
state of asynchronous delivery can be restored later by another call to
this routine.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________________
CANCEL_ON Asynchronous cancelability was on.
CANCEL_OFF Asynchronous cancelability was off.
-1 [EINVAL] The specified state is not CANCEL_ON
or CANCEL_OFF.
RELATED INFORMATION
FUNCTIONS: pthread_cancel
pthread_setcancel
pthread_testcancel
2.47 – pthread_setcancel
NAME
pthread_setcancel - Enables or disables the current thread's
general cancelability
SYNOPSIS
#include <pthread.h>
int pthread_setcancel( int state );
PARAMETERS
state State of general cancelability set for the
calling thread. On return, receives the
prior state of general cancelability. Valid
values are as follows:
CANCEL_ON General cancelability is enabled.
CANCEL_OFF General cancelability is disabled.
DESCRIPTION
The pthread_setcancel() routine enables or disables the current thread's
general cancelability and returns the previous cancelability state to
the state parameter.
When general cancelability is set to CANCEL_OFF, a cancel cannot be
delivered to the thread, even if a cancelable routine is called or asyn-
chronous cancelability is enabled.
When a thread is created, the default general cancelability state is
CANCEL_ON.
POSSIBLE DANGERS OF DISABLING CANCELABILITY
The most important use of cancels is to ensure that indefinite wait
operations are terminated. For example, a thread waiting on some network
connection, which may take days to respond (or may never respond), is
normally made cancelable.
However, when cancelability is disabled, no routine is cancelable. Waits
must be completed normally before a cancel can be delivered. As a
result, the program stops working and the user is unable to cancel the
operation.
When disabling cancelability, be sure that no long waits can occur or
that it is necessary for other reasons to defer cancels around that par-
ticular region of code.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________________
CANCEL_ON Asynchronous cancelability was on.
CANCEL_OFF Asynchronous cancelability was off.
-1 [EINVAL] The specified state is not CANCEL_ON
or CANCEL_OFF.
RELATED INFORMATION
FUNCTIONS: pthread_cancel
pthread_setasynccancel
pthread_testcancel
2.48 – pthread_setprio
NAME
pthread_setprio - Changes the current priority of a thread
SYNOPSIS
#include <pthread.h>
int pthread_setprio( pthread_t thread,
int priority );
PARAMETERS
thread Thread whose priority is changed.
priority New priority value of the thread specified
in thread. The priority value depends on
scheduling policy. Valid values fall within
one of the following ranges:
o PRI_OTHER_MIN <= priority <= PRI_OTHER_MAX
o PRI_FIFO_MIN <= priority <= PRI_FIFO_MAX
o PRI_RR_MIN <= priority <= PRI_RR_MAX
o PRI_FG_MIN_NP <= priority <= PRI_FG_MAX_NP
o PRI_BG_MIN_NP <= priority <= PRI_BG_MAX_NP
If you create a new thread without specifying a threads attributes
object that contains a changed priority attribute, the default priority
of the newly created thread is the midpoint between PRI_OTHER_MIN and
PRI_OTHER_MAX (the midpoint between the minimum and the maximum for the
SCHED_OTHER policy).
When you call this routine to specify a minimum or maximum priority, use
the appropriate symbol; for example, PRI_FIFO_MIN or PRI_FIFO_MAX. To
specify a value between the minimum and maximum, use an appropriate
arithmetic expression. For example, to specify a priority midway between
the minimum and maximum for the Round Robin scheduling policy, specify
the following concept using your programming language's syntax:
pri_rr_mid = (PRI_RR_MIN + PRI_RR_MAX)/2
If your expression results in a value outside the range of minimum to
maximum, an error results when you use it.
DESCRIPTION
The pthread_setprio() routine changes the current priority of a thread.
A thread can change its own priority using the identifier returned by
pthread_self().
Changing the priority of a thread can cause it to start executing or be
preempted by another thread. The effect of setting different priority
values depends on the scheduling priority assigned to the thread. The
initial scheduling priority is set by calling the pthread_attr_setprio()
routine.
Note that pthread_attr_setprio() sets the priority attribute that is
used to establish the priority of a new thread when it is created. How-
ever, pthread_setprio() changes the priority of an existing thread.
RETURN VALUES
If successful, this routine returns the previous priority.
If the function fails, errno may be set to one of the following values:
Return Error Description
___________________________________________________________
Previous priority Successful completion.
-1 [EINVAL] The value specified by thread is
invalid.
-1 [ENOTSUP] An attempt is made to set the policy
to an unsupported value.
-1 [ESRCH] The value specified by thread does
not refer to an existing thread.
-1 [EPERM] The caller does not have the
appropriate privileges to set the
priority of the specified thread.
RELATED INFORMATION
FUNCTIONS: pthread_attr_setprio
pthread_attr_setsched
pthread_create
pthread_self
pthread_setscheduler
2.49 – pthread_setscheduler
NAME
pthread_setscheduler - Changes the current scheduling policy
and priority of a thread
SYNOPSIS
#include <pthread.h>
int pthread_setscheduler( pthread_t thread,
int scheduler,
int priority );
PARAMETERS
thread Thread whose scheduling policy is to be
changed.
scheduler New scheduling policy value for the thread
specified in thread. Valid values are as
follows:
SCHED_FIFO (First In, First Out)
The highest-priority thread runs
until it blocks. If there is more
than one thread with the same
priority, and that priority is the
highest among other threads, the
first thread to begin running
continues until it blocks.
SCHED_RR (Round Robin)
The highest-priority thread runs
until it blocks; however, threads
of equal priority, if that priority
is the highest among other threads,
are timesliced. Timeslicing is a
process in which threads alternate
using available processors.
SCHED_OTHER (Default)
All threads are timesliced.
SCHED_OTHER ensures that all
threads, regardless of priority,
receive some scheduling, and thus
no thread is completely denied
execution time. (However,
SCHED_OTHER threads can be denied
execution time by SCHED_FIFO or
SCHED_RR threads.)
SCHED_FG_NP (Foreground)
Same as SCHED_OTHER. Threads are
timesliced and priorities can be
modified dynamically by the
scheduler to ensure fairness.
SCHED_BG_NP (Background)
Like SCHED_OTHER, ensures that all
threads, regardless of priority,
receive some scheduling. However,
SCHED_BG_NP can be denied execution
by any of the other scheduling
policies.
priority New priority value of the thread specified in
thread. The priority attribute depends on
scheduling policy. Valid values fall within
one of the following ranges:
o PRI_OTHER_MIN <= priority <= PRI_OTHER_MAX
o PRI_FIFO_MIN <= priority <= PRI_FIFO_MAX
o PRI_RR_MIN <= priority <= PRI_RR_MAX
o PRI_FG_MIN_NP <= priority <= PRI_FG_MAX_NP
o PRI_BG_MIN_NP <= priority <= PRI_BG_MAX_NP
If you create a new thread without specifying a threads attributes
object that contains a changed priority attribute, the default priority
of the newly created thread is the midpoint between PRI_OTHER_MIN and
PRI_OTHER_MAX (the midpoint between the minimum and the maximum for the
SCHED_OTHER policy).
When you call this routine to specify a minimum or maximum priority, use
the appropriate symbol; for example, PRI_FIFO_MIN or PRI_FIFO_MAX. To
specify a value between the minimum and maximum, use an appropriate
arithmetic expression. For example, to specify a priority midway between
the minimum and maximum for the Round Robin scheduling policy, specify
the following concept using your programming language's syntax:
pri_rr_mid = (PRI_RR_MIN + PRI_RR_MAX)/2
If your expression results in a value outside the range of minimum to
maximum, an error results when you use it.
DESCRIPTION
The pthread_setscheduler() routine changes the current scheduling policy
and priority of a thread. Call this routine to change both the priority
and scheduling policy of a thread at the same time. To change only the
priority, call the pthread_setprio() routine.
A thread changes its own scheduling policy and priority by using the
identifier returned by pthread_self(). Changing the scheduling policy
or priority, or both, of a thread can cause it to start executing or to
be preempted by another thread.
This routine differs from pthread_attr_setprio() and
pthread_attr_setsched() because those routines set the priority and
scheduling policy attributes that are used to establish the priority and
scheduling policy of a new thread when it is created. This routine, how-
ever, changes the priority and scheduling policy of an existing thread.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
______________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by thread is invalid.
-1 [ENOTSUP] An attempt is made to set the policy to
an unsupported value.
-1 [ESRCH] The value specified by thread does not
refer to an existing thread.
-1 [EPERM] The caller does not have the appropriate
privileges to set the priority of the
specified thread.
RELATED INFORMATION
FUNCTIONS: pthread_attr_setprio
pthread_attr_setsched
pthread_create
pthread_self
pthread_setprio
2.50 – pthread_setspecific
NAME
pthread_setspecific - Sets the thread-specific data associated
with the specified key for the current thread
SYNOPSIS
#include <pthread.h>
int pthread_setspecific( pthread_key_t key,
pthread_addr_t value );
PARAMETERS
key Context key value that uniquely identifies the
context value specified in value. This key value
must have been obtained from pthread_keycreate().
value Address containing data to be associated with the
specified key for the current thread; this is the
thread-specific data.
DESCRIPTION
The pthread_setspecific() routine sets the thread-specific data associ-
ated with the specified key for the current thread. If a value has
already been defined for the key in this thread, the new value is sub-
stituted for it.
Different threads can bind different values to the same key. These
values are typically pointers to blocks of dynamically allocated memory
that are reserved for use by the calling thread.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
_____________________________________________
0 Successful completion.
-1 [EINVAL] The key value is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_getspecific
pthread_keycreate
2.51 – pthread_signal_to_cancel_np
NAME
pthread_signal_to_cancel_np - Cancels the specified thread
SYNOPSIS
#include <pthread.h>
int pthread_signal_to_cancel_np( sigset_t *sigset,
pthread_t *thread );
PARAMETERS
sigset Signal mask containing a list of signals that,
when received by the process, cancels the
specified thread.
thread Thread canceled if a valid signal is received
by the process.
DESCRIPTION
The pthread_signal_to_cancel_np() routine requests that the specified
thread be canceled if one of the signals specified in the signal mask is
received by the process. The set of legal signals is the same as that
for the sigwait() service. The sigset parameter is not validated. If it
is invalid, this routine will return successfully but neither the speci-
fied thread nor the previously specified thread will be canceled if a
signal occurs.
Note that the address of the specified thread is saved in a per-process
global variable. Therefore, any subsequent call to this routine by your
application or any library function will supercede the thread specified
in the previous call, and that thread will not be canceled if one of the
signals specified for it is delivered to the process. In other words,
take care when you call this routine; if another thread calls it after
you do, the expected result of this routine will not occur.
RETURN VALUES
If the function fails, errno may be set to one of the following values:
Return Error Description
_____________________________________________________________
0 Successful completion.
-1 [EINVAL] The value specified by thread is invalid.
RELATED INFORMATION
FUNCTIONS: pthread_cancel
2.52 – pthread_testcancel
NAME
pthread_testcancel - Requests delivery of a pending cancel to the
current thread
SYNOPSIS
#include <pthread.h>
void pthread_testcancel();
DESCRIPTION
The pthread_testcancel() routine requests delivery of a pending cancel
to the current thread. The cancel is delivered only if a cancel is
pending for the current thread and general cancel delivery is not
currently disabled. (A thread disables delivery of cancels to itself by
calling the pthread_setcancel() routine.)
This routine, when called within very long loops, ensures that a pending
cancel is noticed within a reasonable amount of time.
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: pthread_cancel
pthread_setasynccancel
pthread_setcancel
2.53 – pthread_unlock_global_np
NAME
pthread_unlock_global_np - Unlocks a global mutex
SYNOPSIS
#include <pthread.h>
void pthread_unlock_global_np();
DESCRIPTION
The pthread_unlock_global_np() routine unlocks the global mutex when
each call to pthread_lock_global_np() is matched by a call to this rou-
tine. For example, if you called pthread_lock_global_np() three times,
pthread_unlock_global_np() unlocks the global mutex when you call it
the third time. If no threads are waiting for the global mutex, it
becomes unlocked with no current owner. If one or more threads are
waiting to lock the global mutex, one thread returns from its call to
pthread_lock_global_np(). The scheduling policy is used to determine
which thread acquires the global mutex. For the policies SCHED_FIFO and
SCHED_RR, a blocked thread is chosen in priority order.
The results of calling this routine are unpredictable if the global
mutex is already unlocked. The results of calling this routine are also
unpredictable if the global mutex is owned by a thread other than the
calling thread.
This routine is not portable.
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: pthread_lock_global_np
pthread_mutexattr_setkind_np
pthread_mutex_lock
pthread_mutex_unlock
2.54 – pthread_yield
NAME
pthread_yield - Notifies the scheduler that the current thread
is willing to release its processor
SYNOPSIS
#include <pthread.h>
void pthread_yield();
DESCRIPTION
The pthread_yield() routine notifies the scheduler that the current
thread is willing to release its processor to other threads of the same
priority. (A thread releases its processor to a thread of a higher
priority without calling this routine.)
If the current thread's scheduling policy (as specified in a call to the
pthread_attr_setsched() or pthread_setscheduler() routine) is SCHED_FIFO
or SCHED_RR, this routine yields the processor to other threads of the
same or a higher priority. If no threads of the same priority are ready
to execute, the thread continues.
This routine allows knowledge of the details of an application to be
used to increase fairness. It increases fairness of access to the pro-
cessor by removing the current thread from the processor. It also
increases fairness of access to shared resources by removing the
current thread from the processor as soon as it is finished with the
resource.
Call this routine when a thread is executing code that denies access to
other threads on a uniprocessor if the scheduling policy is SCHED_FIFO.
Use pthread_yield() carefully because misuse causes unnecessary context
switching, which increases overhead without increasing fairness. For
example, it is counterproductive for a thread to yield while it has a
needed resource locked.
RETURN VALUES
No value is returned.
RELATED INFORMATION
FUNCTIONS: pthread_attr_setsched
pthread_setscheduler
2.55 – sigwait
NAME
sigwait - Causes a thread to wait for an asynchronous signal
SYNOPSIS
#include <pthread.h>
int sigwait( sigset_t *set );
PARAMETERS
set Set of asynchronous pending signals from which
this routine chooses one signal on which the
calling thread will wait.
DESCRIPTION
This routine causes a thread to wait for an asynchronous signal by
choosing a pending signal from set, atomically clearing it from the
system's set of pending signals and returning that signal number. If no
signal in set is pending at the time of the call, the thread is blocked
until one or more signals becomes pending. The signals defined by set
may be unblocked during the call to this routine and will be blocked
when the thread returns from the call unless some other thread is
currently waiting for one of those signals.
If more than one thread is using this routine to wait for the same
signal, only one of these threads will return from this routine with the
signal number.
RETURN VALUES
Possible return values are as follows:
Return Error Description
__________________________________________________
Signal number Successful completion.
-1 [EINVAL] The value specified by set is
invalid.
RELATED INFORMATION
FUNCTIONS: pthread_cancel
pthread_setasynccancel