int
pthread_setspecific (
pthread_key_t key,
const void *value);
key
Thread-specific key that identifies the thread-specific data to receive value. This key value must be obtained from pthread_key_create().value
New thread-specific data value to associate with the specified key for the calling thread.
This routine sets the thread-specific data value associated with the specified key for the current thread. If a value is defined for the key in this thread (the current value is not NULL), the new value is substituted for it. The key is obtained by a previous call to pthread_key_create().Return Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: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.
Do not call this routine from a thread-specific data destructor function.
Note that although the type for value (void*) implies that it represents an address, the type is being used as a "universal scalar type." DECthreads simply stores value for later retrieval.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The specified key is invalid. |
| [ENOMEM] | Insufficient memory exists to associate the value with the key. |
Examine or change the calling thread's signal mask.This routine is for DIGITAL UNIX systems only.
C Binding #include <pthread.h>pthread_sigmask(
how ,
set ,
oset );
Argument Data Type Access how integer read set sigset_t read oset sigset_t write
int
pthread_sigmask (
int how,
const sigset_t *set,
sigset_t *oset);
how
Indicates the manner in which the set of masked signals is changed. The optional values are as follows:
SIG_BLOCK The resulting set is the union of the current set and the signal set pointed to by the set argument. SIG_UNBLOCK The resulting set is the intersection of the current set and the complement of the signal set pointed to by the set argument. SIG_SETMASK The resulting set is the signal set pointed to by the set argument. set
Specifies the signal set by pointing to a set of signals used to change the blocked set. If this set value is NULL, the how argument is ignored and the process signal mask is unchanged.oset
Receives the value of the current signal mask (unless this value is NULL).
This routine examines or changes the calling thread's signal mask. Typically, you use the SIG_BLOCK option for the how value to block signals during a critical section of code, and then use this routine's SIG_SETMASK option to restore the mask to the previous value returned by the previous call to the pthread_sigmask() routine.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:If there are any unblocked signals pending after a call to this routine, at least one of those signals is before this routine returns.
This routine does not allow the SIGKILL or SIGSTOP signals to be blocked. If a program attempts to block one of these signals, pthread_sigmask() gives no indication of the error.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified for how is invalid. |
Requests delivery of a pending cancelation request to the calling thread.
C Binding #include <pthread.h>pthread_testcancel( );
void
pthread_testcancel (void);
None
This routine requests delivery of a pending cancelation request to the calling thread. Thus, calling this routine creates a cancelation point within the calling thread.Return Values NoneThe cancelation request is delivered only if a request is pending for the calling thread and the calling thread's cancelability state is enabled. (A thread disables delivery of cancelation requests to itself by calling pthread_setcancelstate().)
When called within very long loops, this routine ensures that a pending cancelation request is noticed by the calling thread within a reasonable amount of time.
Unlocks the DECthreads global mutex.
C Binding #include <pthread.h>pthread_unlock_global_np( );
int
pthread_unlock_global_np (void);
None
This routine unlocks the DECthreads global mutex. Because the global mutex is recursive, the unlock occurs when each call to pthread_lock_global_np() has been matched by a call to this routine. 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 DECthreads global mutex, it becomes unlocked with no current owner. If one or more threads are waiting to lock the global mutex, this routine causes one thread to unblock and try to acquire the global mutex. The scheduling policy is used to determine which thread is awakened. For the policies SCHED_FIFO and SCHED_RR, a blocked thread is chosen in priority order, using first-in/first-out (FIFO) within priorities.
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. |
| [EPERM] | The mutex is unlocked or owned by another thread. |
Returns the maximum priority for the specified scheduling policy.
C Binding #include <sched.h>sched_get_priority_max( policy );
int
sched_get_priority_max (
int policy);
policy
One of the scheduling policies, as defined in sched.h.
This routine returns the maximum priority for the scheduling policy specified in the policy argument. The argument value must be one of the scheduling policies (SCHED_FIFO, SCHED_RR, or SCHED_OTHER), as defined in the sched.h header file.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:No special privileges are required to use this routine.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value of the policy argument does not represent a defined scheduling policy. |
Returns the minimum priority for the specified scheduling policy.
C Binding include <sched.h>sched_get_priority_min( policy );
int
sched_get_priority_min (
int policy);
policy
One of the scheduling policies, as defined in sched.h.
This routine returns the minimum priority for the scheduling policy specified in the policy argument. The argument value must be one of the scheduling policies (SCHED_FIFO, SCHED_RR, or SCHED_OTHER), as defined in the sched.h header file.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:No special privileges are required to use this routine.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value of the policy argument does not represent a defined scheduling policy. |
Yields execution to another thread.
C Binding include <sched.h>sched_yield( );
int sched_yield (
void);
None
In conformance with the IEEE POSIX.1b-1995 standard, the sched_yield() function causes the calling thread to yield execution to another thread. It is useful when a thread running under the SCHED_FIFO scheduling policy must allow another thread at the same priority to run. The thread that is interrupted by sched_yield() goes to the end of the queue for its priority.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:If no other thread is runnable at the priority of the calling thread, the calling thread continues to run.
Threads with higher priority are allowed to preempt the calling thread, so the sched_yield() function has no effect on the scheduling of higher- or lower-priority threads.
The sched_yield() routine takes no arguments. No special privileges are needed to use the sched_yield() function.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| -1 | Unsuccessful completion--- errno is set to indicate that an error occurred. |
| [ENOSYS] | The routine sched_yield() is not supported by this implementation. |
Suspends a calling thread until a signal arrives.
C Binding include <signal.h>sigwait(
set ,
signal );
int
sigwait (
sigset_t *set,
int *signal);
set
Set of signals to wait for.signal
Signal number obtained for the selected signal.
This routine suspends the calling thread until at least one of the signals in the set argument is in the caller's set of pending signals. When this happens, one of those signals is automatically selected and removed from the set of pending signals. The signal number identifying that signal is then returned.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 stores the signal number obtained in the address specified in the signal argument.
The effect of calling this routine is unspecified if any signals in the set argument are not blocked at the time of the call.
The set signal set object is created using the set manipulation routines sigemptyset(), sigfillset(), sigaddset(), and sigdelset().
If, while this routine is waiting, a signal occurs that is eligible for delivery (that is, not blocked by the signal mask), that signal is handled asynchronously and the wait is interrupted.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value of the set argument contains an invalid or unsupported signal number. |
| [EINTR] | The wait was interrupted by an unblocked, caught signal. |
These routines are designed to provide efficient tools for thread safety in libraries whose routines do not themselves use threads. The tis interface provides functions identical to several pthread functions. In a program that creates or uses threads, the tis functions provide full thread synchronization and coherence of memory access. But, in a program that does not use threads, the same tis calls provide low-overhead "stub" implementations of pthread features.
The objects created using tis interface routines are the same as pthread interface objects.
The variable errno is not used by the tis routines. Like the pthread routines, the tis routines return integer values indicating the type of error.
Note
In a nonthreaded environment, never code tis routines to use condition variables to block operations. For example, the single-threaded implementation of tis_cond_wait() cannot block. If it did, no other thread would be running to "awaken" the program.
When threads are present, the guidelines for using pthread routines apply to using the corresponding tis routines.
Wakes all threads that are waiting on a condition variable.
C Binding #include <tis.h>tis_cond_broadcast(
cond );
Argument Data Type Access cond opaque pthread_cond_t modify
int
tis_cond_broadcast (
pthread_cond_t *cond);
cond
Address of the condition variable (passed by reference) on which to broadcast.
When threads are not present, this routine performs no actions.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:When threads are present, this routine unblocks all threads waiting on the specified condition variable cond.
For further information about actions when threads are present, refer to the pthread_cond_broadcast() description.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by cond is invalid. |
Destroys the specified condition variable.
C Binding #include <tis.h>tis_cond_destroy(
cond );
Argument Data Type Access cond opaque pthread_cond_t write
int
tis_cond_destroy (
pthread_cond_t *cond);
cond
Address of the condition variable (passed by reference) to be destroyed.
This routine destroys the condition variable specified by cond. After this routine is called, DECthreads may reclaim internal storage used by the condition variable object. Call this routine when a condition variable will no longer be referenced.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 results of this routine are unpredictable, if the condition variable specified in cond does not exist or is not initialized.
For more information about actions when threads are present, refer to the pthread_cond_destroy() description.
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by cond is invalid. |
| [EBUSY] |
The object being referenced by
cond is being referenced by another thread that is currently
executing a
tis_cond_wait() on the condition variable specified in cond. (This error can only occur when threads are present.) |
Initializes a condition variable.
C Binding #include <tis.h>tis_cond_init(
cond );
Argument Data Type Access cond opaque pthread_cond_t write
int
tis_cond_init (
pthread_cond_t *cond);
cond
Address of the condition variable (passed by reference) to be initialized.
This routine initializes a condition variable (cond) with the DECthreads default condition variable attributes.Return Values If there is an error condition, the following occurs:A condition variable is a synchronization object used in conjunction with a mutex. A mutex controls access to shared data. When threads are present, a condition variable allows threads to wait for data to enter a defined state.
For more information about actions taken when threads are present, refer to the pthread_cond_init() description.
Your program can use the macro PTHREAD_COND_INITIALIZER to initialize statically allocated condition variables to the DECthreads default condition variable attributes. Use this macro as follows:
pthread_cond_t condition = PTHREAD_COND_INITIALIZER;When statically initialized, a condition variable should not also be initialized using tis_cond_init(). Also, a statically initialized condition variable need not be destroyed using tis_cond_destroy().
The possible return values are as follows:
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EAGAIN] |
The system lacks the necessary resources to initialize another
condition variable, or:
The system-imposed limit on the total number of condition variables under execution by a single user is exceeded. |
| [EBUSY] | The implementation has detected an attempt to reinitialize the object referenced by cond, a previously initialized, but not yet destroyed condition variable. |
| [EINVAL] | The value specified by attr is invalid. |
| [ENOMEM] | Insufficient memory exists to initialize the condition variable. |
Wakes at least one thread that is waiting on the specified condition variable.
C Binding #include <tis.h>tis_cond_signal(
cond );
Argument Data Type Access cond opaque pthread_cond_t modify
int
tis_cond_signal (
pthread_cond_t *cond);
cond
Address of the condition variable (passed by reference) on which to signal.
When threads are present, this routine unblocks at least one thread that is waiting on the specified condition variable cond.For more information about actions taken when threads are present, refer to the pthread_cond_signal() description.
Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
| Return | Description |
|---|---|
| 0 | Successful completion. |
| [EINVAL] | The value specified by cond is invalid. |
Causes a thread to wait for the specified condition variable to be signaled or broadcasted.
C Binding #include <tis.h>tis_cond_wait(
cond ,
mutex );
Argument Data Type Access cond opaque pthread_cond_t modify mutex opaque pthread_mutex_t modify
int
tis_cond_wait (
pthread_cond_t *cond,
pthread_mutex_t *mutex);
cond
Address of the condition variable (passed by reference) on which to wait.mutex
Address of the mutex (passed by reference) that is associated with the condition variable specified in cond.
When threads are present, this routine causes a thread to wait for the specified condition variable cond to be signaled or broadcasted.Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: Previous | Next | ContentsCalling this routine in a single-threaded environment is a coding error. Because no thread can execute in parallel to issue a call to tis_cond_signal() or tis_cond_broadcast(), using this routine in a single-threaded environment forces the program to exit.
For further information about actions taken when threads are present, refer to the pthread_cond_wait() description.