The object name is a C language string and provides an identifier that is meaningful to a person debugging a DECthreads-based multithreaded application. The maximum number of characters in the object name is 31. Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by mutex is invalid, or the length in characters of name exceeds 31. |
[ENOMEM] | Insufficient memory exists to create a copy of the object name string. |
Attempts to lock the specified mutex. If the mutex is already locked, the calling thread does not wait for the mutex to become available.
C Binding #include <pthread.h>pthread_mutex_trylock(
mutex );
Argument Data Type Access mutex opaque pthread_mutex_t read
int
pthread_mutex_trylock (
pthread_mutex_t *mutex);
mutex
Mutex to be locked.
This routine attempts to lock the mutex specified in the mutex argument. When a thread calls this routine, an attempt is made to immediately lock the mutex. If the mutex is successfully locked, this routine returns zero (0) and the calling thread becomes the mutex's current owner. If the specified mutex is locked when a thread calls this routine, the calling thread does not wait for the mutex to become available.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:The behavior of this routine is as follows:
- For a normal, default, or errorcheck mutex: if the mutex is locked by any thread (including the calling thread) when this routine is called, this routine returns [EBUSY] and the calling thread does not wait to acquire the lock.
- For a normal or errorcheck mutex: if the mutex is not owned, this routine returns zero (0) and the mutex becomes locked.
- For a recursive mutex: if the mutex is owned by the current thread, this routine returns zero (0) and the mutex lock count is incremented. (To unlock a recursive mutex, each call to pthread_mutex_trylock() must be matched by a call to pthread_mutex_unlock().)
Use the pthread_mutexattr_settype() routine to set the mutex type attribute (normal, default, recursive, or errorcheck). For information about mutex types and their usage, see Chapter 2.
Return | Description |
---|---|
0 | Successful completion. |
[EBUSY] | The mutex is already locked; therefore, it was not acquired. |
[EINVAL] |
The value specified by
mutex is invalid, or
The mutex was created with the protocol attribute set to PTHREAD_PRIO_PROTECT and the calling thread's priority set higher than the mutex's current priority ceiling. |
Unlocks the specified mutex.
C Binding #include <pthread.h>pthread_mutex_unlock(
mutex );
Argument Data Type Access mutex opaque pthread_mutex_t read
int
pthread_mutex_unlock (
pthread_mutex_t *mutex);
mutex
Mutex to be unlocked.
This routine unlocks the mutex specified by the mutex argument.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:This routine behaves as follows, based on the type of the specified mutex:
- For a normal, default, or errorcheck mutex: if the mutex is owned by the calling thread, it is unlocked with no current owner. Further, for a normal or default mutex: if the mutex is not locked or is locked by another thread, this routine can also return [EPERM], but this is not guaranteed. For an errorcheck mutex: if the mutex is not locked or is locked by another thread, this routine returns [EPERM].
- For a recursive mutex: if the mutex is owned by the calling thread, the lock count is decremented. The mutex remains locked and owned until the lock count reaches zero (0). When the lock count reaches zero, the mutex becomes unlocked with no current owner.
If one or more threads are waiting to lock the specified mutex, and the mutex becomes unlocked, this routine causes one thread to unblock and to try to acquire the mutex. The scheduling policy is used to determine which thread to unblock. For the SCHED_FIFO and SCHED_RR policies, a blocked thread is chosen in priority order, using first-in/first-out within priorities. Note that the mutex might not be acquired by the awakened thread, if any other running thread attempts to lock the mutex first.
On DIGITAL UNIX, if a signal is delivered to a thread waiting for a mutex, upon return from the signal handler, the thread resumes waiting for the mutex as if it was not interrupted.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified for mutex is invalid. |
[EPERM] | The calling thread does not own the mutex. |
Calls an initialization routine that is executed by a single thread, once.
C Binding #include <pthread.h>pthread_once(
once _control,
init _routine );
Argument Data Type Access once_control opaque pthread_once_t modify init_routine procedure read
int
pthread_once (
pthread_once_t *once_control,
void (*init_routine) (void));
once_control
Address of a record that defines the one-time initialization code. Each one-time initialization routine must have its own unique pthread_once_t record.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_control are passed to pthread_once().
The first call to this routine by any thread in a process with a given once_control will call the specified init_routine with no arguments. Subsequent calls to pthread_once() with the same once_control will not call the init_routine. On return from pthread_once(), it is guaranteed that the initialization routine has completed.For example, a mutex or a per-thread context key must be created exactly once. Calling pthread_once() ensures that the initialization is serialized across multiple threads. Other threads that reach the same point in the code would be 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.
To initialize the once_control record, your program can zero out the entire structure, or you can use the PTHREAD_ONCE_INIT macro, which is defined in the pthread.h header file, to statically initialize that structure. If using PTHREAD_ONCE_INIT, declare the once_control record as follows:
pthread_once_t once_control = PTHREAD_ONCE_INIT;Note that it is often easier to simply lock a statically initialized mutex, check a control flag, and perform necessary initialization (in-line) rather than using pthread_once(). For example, you can code an initialization routine that begins with the following basic logic:
init() { static pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER; static int flag = FALSE; pthread_mutex_lock(&mutex); if(!flag) { flag = TRUE; /* initialize code */ } pthread_mutex_unlock(&mutex); }
Return Values If an error occurs, this routine returns an integer indicating the type of error. Possible return values are as follows:
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | Invalid argument. |
Obtains the identifier of the calling thread.
C Binding #include <pthread.h>pthread_self( );
pthread_t
pthread_self (void);
None
This routine returns the address of the calling thread's own thread identifier. For example, you can use this thread object to obtain the calling thread's own sequence number. To do so, pass the return value from this routine in a call to the pthread_getsequence_np() routine, as follows:Return Values Returns the address of the calling thread's own thread object.. . . unsigned long this_thread_nbr; . . . this_thread_nbr = pthread_getsequence_np( pthread_self( ) ); . . .The return value from the pthread_self() routine becomes meaningless after the calling thread is destroyed.
Sets the calling thread's cancelability state.
C Binding #include <pthread.h>pthread_setcancelstate(
state ,
oldstate );
Argument Data Type Access state integer read oldstate integer write
int
pthread_setcancelstate (
int state,
int *oldstate );
state
State of general cancelability to set for the calling thread. The following are valid cancel state values:
- PTHREAD_CANCEL_ENABLE
- PTHREAD_CANCEL_DISABLE
oldstate
Previous cancelability state for the calling thread.
This routine sets the calling thread's cancelability state and returns the calling thread's previous cancelability state in oldstate.Return Values On successful completion, this routine returns the calling thread's previous cancelability state in the location specified by the oldstate argument.When cancelability state is set to PTHREAD_CANCEL_DISABLE, a cancelation request cannot be delivered to the thread, even if a cancelable routine is called or asynchronous cancelability type is enabled.
When a thread is created, its default cancelability state is PTHREAD_CANCEL_ENABLE.
Possible Problems When Disabling Cancelability
The most important use of thread cancelation is to ensure that indefinite wait operations are terminated. For example, a thread that waits on some network connection, which can possibly take days to respond (or might never respond), should be made cancelable.
When a thread's cancelability is disabled, no routine in that thread is cancelable. As a result, the user is unable to cancel the operation performed by that thread. When disabling cancelability, be sure that no long waits can occur or that it is necessary for other reasons to defer cancelation requests around that particular region of code.
If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The specified state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE. |
Sets the calling thread's cancelability type.
C Binding #include <pthread.h>pthread_setcanceltype(
type ,
oldtype );
Argument Data Type Access type integer read oldtype integer write
int
pthread_setcanceltype (
int type,
int *oldtype);
type
The cancelability type to set for the calling thread. The following are valid values:
- PTHREAD_CANCEL_DEFERRED
- PTHREAD_CANCEL_ASYNCHRONOUS
oldtype
Returns the previous cancelability type.
This routine sets the cancelability type and returns the previous type in location oldtype.Return Values On successful completion, this routine returns the previous cancelability type in oldtype.When a thread's cancelability state is set to PTHREAD_CANCEL_DISABLE, (see pthread_setcancelstate()), a cancelation request cannot be delivered to that thread, even if a cancelable routine is called or asynchronous cancelability type is enabled.
When the cancelability state is set to PTHREAD_CANCEL_ENABLE, cancelability depends on the thread's cancelability type, as follows:
- If the thread's cancelability state is PTHREAD_CANCEL_ENABLE and the thread's cancelability type is set to PTHREAD_CANCEL_DEFERRED, the thread can only receive a cancelation request at a cancelation point (including condition waits, thread joins, and calls to pthread_testcancel()).
- If the thread's cancelability state is PTHREAD_CANCEL_ENABLE and its cancelability type is PTHREAD_CANCEL_ASYNCHRONOUS, the thread can be canceled at any point in its execution.
When a thread is created, the default cancelability type is
PTHREAD_CANCEL_DEFERRED.
Warning
If the asynchronous cancelability type is set, do not call any routine unless it is explicitly documented as "safe for asynchronous cancelation." Note that none of the general run-time libraries and none of the DECthreads libraries are safe for asynchronous cancelation except for pthread_setcanceltype() and pthread_setcancelstate().Use asynchronous cancelability only when you have a compute-bound section of code that carries no state and makes no routine calls.
If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The specified type is not PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_AYNCHRONOUS. |
Changes the value of the concurrency level global variable for this process.
C Binding #include <pthread.h>pthread_setconcurrency(
level );
Argument Data Type Access level int read
int
pthread_setconcurrency (
int level);
level
New value for the concurrency level for this process.
This routine stores the value specified in the level argument in the "concurrency level" global setting for the calling thread's process. Because DECthreads automatically manages the concurrency of all threads in a multithreaded process, DECthreads ignores this concurrency level value.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:The concurrency level value has no effect on the behavior of a multithreaded program that uses DECthreads. This routine is provided for Single UNIX Specification, Version 2 source code compatibility and has no other effect when called.
After calling this routine, subsequent calls to the pthread_getconcurrency() routine return the same value, until another call to pthread_setconcurrency() changes that value.
The initial concurrency level is zero (0), indicating that DECthreads manages the concurrency level. To indicate in a portable manner that the implementation is to resume control of concurrency level, call this routine with a level argument of zero (0).
The concurrency level value can be obtained using the pthread_getconcurrency() routine.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by new_level is negative. |
[EAGAIN] | The value specified by new_level would cause a system resource to be exceeded. |
Changes the object name in the thread object for an existing thread.
C Binding #include <pthread.h>pthread_setname_np(
thread ,
name ,
mbz );
Argument Data Type Access thread opaque pthread_thread_t write name char read mbz void read
int
pthread_setname_np (
pthread_thread_t thread,
const char *name,
void *mbz);
thread
Thread object whose object name is to be changed.name
Object name value to copy into the thread object.mbz
(Must be zero) Argument for use by DECthreads.
This routine changes the object name in the thread object for the thread specified by the thread argument to the value specified by the name argument. To set an existing thread's object name, call this routine after creating the thread. However, with this approach your program must account for the possibility that the target thread has already exited or has been canceled before this routine is called.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:The object name is a C language string and provides an identifier that is meaningful to a person debugging a DECthreads-based multithreaded application. The maximum number of characters in the object name is 31.
This routine contrasts with pthread_attr_setname_np(), which changes the object name attribute in a thread attributes object that is used to create a new thread.
Return | Description |
---|---|
0 | Successful completion. |
[ESRCH] | The thread specified by thread does not exist. |
[EINVAL] | The length in characters of name exceeds 31. |
[ENOMEM] | Insufficient memory exists to create a copy of the object name string. |
Changes a thread's scheduling policy and scheduling parameters.
C Binding #include <pthread.h>pthread_setschedparam(
thread ,
policy ,
param );
Argument Data Type Access thread opaque pthread_t read policy integer read param struct sched_param read
int
pthread_setschedparam (
pthread_t thread,
int policy,
const struct sched_param *param);
thread
Thread whose scheduling policy and parameters are to be changed.policy
New scheduling policy value for the thread specified in thread. The following are valid values:
- SCHED_BG_NP
- SCHED_FG_NP
- SCHED_FIFO
- SCHED_OTHER
- SCHED_RR
See Section 2.3.2.2 for a description of thread scheduling policies.
param
New values of the scheduling parameters associated with the scheduling policy for the thread specified in thread. Valid values for the sched_priority field of a sched_param structure depend on the chosen scheduling policy. Use the POSIX routines sched_get_priority_min() or sched_get_priority_max() to determine the low and high limits of each policy.Additionally, DECthreads provides nonportable priority range constants, as follows:
Low High PRI_FIFO_MIN PRI_FIFO_MAX PRI_RR_MIN PRI_RR_MAX PRI_OTHER_MIN PRI_OTHER_MAX PRI_FG_MIN_NP PRI_FG_MAX_NP PRI_BG_MIN_NP PRI_BG_MAX_NP The default priority varies by DECthreads platform. On DIGITAL UNIX, the default is 19 (that is, the POSIX priority of a normal timeshare process). On other platforms the default priority is the midpoint between PRI_FG_MIN_NP and PRI_FG_MAX_NP. (Section 2.3.6 describes how to specify priorities between the minimum and maximum values.)
This routine changes both the current scheduling policy and associated scheduling parameters of the thread specified by thread to the policy and associated parameters provided in policy and param, respectively.Return Values If an error condition occurs, no scheduling policy or parameters are changed for the target thread, and this routine returns an integer value indicating the type of error. Possible return values are as follows:All currently implemented DECthreads scheduling policies have one scheduling parameter called sched_priority. For the policy you choose, you must specify an appropriate value in the sched_priority field of the sched_param structure.
Changing the scheduling policy or priority, or both, of a thread can cause it to start executing or to be preempted by another thread. A thread changes its own scheduling policy and priority by using the handle returned by the pthread_self() routine.
This routine differs from pthread_attr_setschedpolicy() and
pthread_attr_setschedparam(), in that those routines set the scheduling policy and parameter attributes that are used to establish the scheduling priority and scheduling policy of a new thread when it is created. However, this routine changes the scheduling policy and parameters of an existing thread.
Return | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by policy or param is invalid. |
[ENOTSUP] | An attempt was made to set the scheduling policy or a parameter to an unsupported value. |
[EPERM] | The caller does not have the appropriate privileges to set the scheduling policy or parameters of the specified thread. |
[ESRCH] | The value specified by thread does not refer to an existing thread. |
Sets the thread-specific data value associated with the specified key for the calling thread.
C Binding #include <pthread.h>pthread_setspecific(
key ,
value );
Argument Data Type Access key opaque pthread_key_t read value void * read