HP OpenVMS Systems Documentation

Content starts here

Guide to the POSIX Threads Library


Previous Contents Index


sched_get_priority_min

Returns the minimum priority for the specified scheduling policy.

Syntax

sched_get_priority_min(
policy );

Argument Data Type Access
policy integer read
C Binding #include <sched.h>

int
sched_get_priority_min (
int policy);


Arguments

policy

One of the scheduling policies, as defined in sched.h .

Description

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.

No special privileges are required to use this 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:
Return Description
0 Successful completion.
[EINVAL] The value of the policy argument does not represent a defined scheduling policy.

sched_yield

Yields execution to another thread.

Syntax

sched_yield( );

C Binding #include <sched.h>
#include <unistd.h>

int
sched_yield (void);


Arguments

None

Description

In conformance with the IEEE POSIX.1-1996 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.

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 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.
[ENOSYS] The routine sched_yield() is not supported by this implementation.

Associated Routines

pthread_attr_setschedparam()
pthread_getschedparam()
pthread_setschedparam()

sigwait

Suspends a calling thread until a signal arrives.

This routine is for Tru64 UNIX systems only.


Syntax

sigwait(
set ,
signal );

Argument Data Type Access
set sigset_t read
signal integer write
C Binding #include <signal.h>

int
sigwait (
sigset_t *set,
int *signal);


Arguments

set

Set of signals to wait for.

signal

Signal number obtained for the selected signal.

Description

This routine blocks 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.

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 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 of the set argument contains an invalid or unsupported signal number.
[EINTR] The wait was interrupted by an unblocked, caught signal.


Part 3
Compaq Proprietary Interfaces: tis Routines Reference

Part 3 provides detailed descriptions of the Compaq proprietary thread-independent services (or tis) interface routines.

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 similar to the pthread functions for synchronization. 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

Never use tis_cond_wait() in a nonthreaded environment. It cannot wait, as there would be no thread able to awaken the waiter. The tis "stub" will abort your program.

When threads are present, the guidelines for using pthread routines apply to using the corresponding tis routines.


tis_cond_broadcast

Wakes all threads that are waiting on a condition variable.

Syntax

tis_cond_broadcast(
cond );

Argument Data Type Access
cond opaque pthread_cond_t modify
C Binding #include <tis.h>

int
tis_cond_broadcast (
pthread_cond_t *cond);


Arguments

cond

Address of the condition variable (passed by reference) on which to broadcast.

Description

When threads are not present, this routine has no effect.

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 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 not a valid condition variable.

Associated Routines

tis_cond_destroy()
tis_cond_init()
tis_cond_signal()
tis_cond_wait()

tis_cond_destroy

Destroys the specified condition variable.

Syntax

tis_cond_destroy(
cond );

Argument Data Type Access
cond opaque pthread_cond_t write
C Binding #include <tis.h>

int
tis_cond_destroy (
pthread_cond_t *cond);


Arguments

cond

Address of the condition variable (passed by reference) to be destroyed.

Description

This routine destroys the condition variable specified by cond. After this routine is called, the Threads Library may reclaim internal storage used by the condition variable object. Call this routine when a condition variable will no longer be referenced.

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 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.
[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.)
[EINVAL] The value specified by cond is not a valid condition variable.

Associated Routines

tis_cond_broadcast()
tis_cond_init()
tis_cond_signal()
tis_cond_wait()

tis_cond_init

Initializes a condition variable.

Syntax

tis_cond_init(
cond );

Argument Data Type Access
cond opaque pthread_cond_t write
C Binding #include <tis.h>

int
tis_cond_init (
pthread_cond_t *cond);


Arguments

cond

Address of the condition variable (passed by reference) to be initialized.

Description

This routine initializes a condition variable (cond) with the Threads Library default condition variable attributes.

A condition variable is a synchronization object used 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 default condition variable attributes. Static initialization can be used only for a condition variable with storage class "extern" or "static" --- "automatic" (stack local) objects must be initialized by calling tis_cond_init() . 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() .

Return Values If there is an error condition, the following occurs:
  • The routine returns an integer value indicating the type of error.
  • The condition variable is not initialized.
  • The contents of condition variable cond are undefined.

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 cond is not a valid condition variable.
[ENOMEM] Insufficient memory to initialize the condition variable.

Associated Routines

tis_cond_broadcast()
tis_cond_destroy()
tis_cond_signal()
tis_cond_wait()

tis_cond_signal

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

Syntax

tis_cond_signal(
cond );

Argument Data Type Access
cond opaque pthread_cond_t modify
C Binding #include <tis.h>

int
tis_cond_signal (
pthread_cond_t *cond);


Arguments

cond

Address of the condition variable (passed by reference) on which to signal.

Description

When threads are present, this routine unblocks at least one thread that is waiting on the specified condition variable cond. When threads are not present, this routine has no effect.

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 not a valid condition variable.

Associated Routines

tis_cond_broadcast()
tis_cond_destroy()
tis_cond_init()
tis_cond_wait()

tis_cond_timedwait

Causes a thread to wait for the specified condition variable to be signaled or broadcast, such that it will awake after a specified period of time.

Syntax

tis_cond_timedwait(
cond ,
mutex ,
abstime );

Argument Data Type Access
cond opaque pthread_cond_t modify
mutex opaque pthread_mutex_t modify
abstime structure timespec read
C Binding #include <tis.h>

int
tis_cond_timedwait (
pthread_cond_t *cond,
pthread_mutex_t *mutex,
const struct timespec *abstime);


Arguments

cond

Condition variable that the calling thread waits 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 tis_get_expiration() routine, which is used to obtain a value for this argument.

The abstime argument is specified in Universal Coordinated Time (UTC). In the UTC-based model, time is represented as seconds since the Epoch. The Epoch is defined as the time 0 hours, 0 minutes, 0 seconds, January 1st, 1970 UTC.


Description

If threads are not present, this function is equivalent to sleep() .

This routine causes a thread to wait until one of the following occurs:

  • The specified condition variable is signaled or broadcast.
  • The current system clock time is greater than or equal to the time specified by the abstime argument.

This routine is identical to tis_cond_wait() , except that this routine can return before a condition variable is signaled or broadcast, specifically, when the specified time expires. For more information, see the tis_cond_wait() description.

This routine atomically releases the mutex and causes the calling thread to wait on the condition. When the thread regains control after calling tis_cond_timedwait() , the mutex is locked and the thread is the owner. This is true regardless of why the wait ended. If general cancelability is enabled, the thread reacquires the mutex (blocking for it if necessary) before the cleanup handlers are run (or before the exception is raised).

If the current time equals or exceeds the expiration time, this routine returns immediately, releasing and reacquiring the mutex. It might cause the calling thread to yield (see the sched_yield() description). Your code should check the return status whenever this routine returns and take the appropriate action. Otherwise, waiting on the condition variable can become a nonblocking loop.

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. The only routines that are supported for use with asynchronous cancelability enabled are those that disable asynchronous cancelability.

Return Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows:
Return Description
0 Successful completion.
[EINVAL] The value specified by cond, mutex, or abstime is invalid, or

Different mutexes are supplied for concurrent
tis_cond_timedwait() operations or
tis_cond_wait() operations on the same condition variable, or

The mutex was not owned by the calling thread at the time of the call.

[ETIMEDOUT] The time specified by abstime expired.
[ENOMEM] The Threads Library cannot acquire memory needed to block using a statically initialized condition variable.

Associated Routines

tis_cond_broadcast()
tis_cond_destroy()
tis_cond_init()
tis_cond_signal()
tis_cond_wait()
tis_get_expiration()


Previous Next Contents Index