Document revision date: 30 March 2001

Causes a thread to wait for the specified condition variable to be signaled or broadcast.

Syntax

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);

Arguments

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.

Description

When threads are present, this routine causes a thread to wait for the specified condition variable cond to be signaled or broadcast.

Calling this routine in a single-threaded environment is a coding error. Because no other thread exists 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.

Associated Routines

tis_cond_broadcast()
tis_cond_destroy()
tis_cond_init()
tis_cond_signal()

Obtains the data associated with the specified thread-specific data key.

Syntax

tis_getspecific(
key );

Argument	Data Type	Access
key	opaque pthread_key_t	read

void *
tis_getspecific (
pthread_key_t key);

Arguments

key

Identifies a value returned by a call to tis_key_create() . This routine returns the data value associated with the thread-specific data key.

Description

This routine returns the value currently bound to the specified thread-specific data key.

This routine can be called from a data destructor function.

When threads are present, the data and keys are thread specific; they enable a library to maintain context on a per-thread basis.

Associated Routines

tis_key_create()
tis_key_delete()
tis_setspecific()

Obtains a value representing a desired expiration time.

Syntax

tis_get_expiration(
delta ,
abstime );

Argument	Data Type	Access
delta	struct timespec	read
abstime	struct timespec	write

int
tis_get_expiration (
const struct timespec *delta,
struct timespec *abstime);

Arguments

delta

Number of seconds and nanoseconds to add to the current system time. (The result is the time in the future.) This result will be placed in abstime.

abstime

Value representing the absolute expiration time. The absolute expiration time is obtained by adding delta to the current system time. The resulting abstime is in Universal Coordinated Time (UTC).

Description

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

This 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 tis_cond_timedwait() .

The timespec structure contains the following two fields:

• tv_sec is an integral number of seconds.
• tv_nsec is an integral number of nanoseconds.

Associated Routines

tis_cond_timedwait()

AST completion routine to VMS I/O system services.
This routine is for OpenVMS systems only.

Syntax

tis_io_complete( );

int
tis_io_complete (void);

Description

When you are performing thread-synchronous "wait-form" system service calls on OpenVMS such as $QIOW , $ENQW , $GETJPIW , and so on, you should use this routine and tis_sync() with the asynchronous form of the service (in other words, without the "W"), and specify the address of tis_io_complete() as the completion AST routine (the AST argument if any is ignored). That must also specify an IOSB (or equivalent, such as an LKSB) and if possible a unique event flag (see lib$get_ef ). Once the library code is ready to wait for the I/O, it simply calls tis_sync() (just as if it were calling $SYNC ).

Associated Routines

tis_sync()

Generates a unique thread-specific data key.

Syntax

tis_key_create(
key ,
destructor );

Argument	Data Type	Access
key	opaque pthread_key_t	write
destructor	procedure	read

int
tis_key_create (
pthread_key_t *key,
void (*destructor)(void *));

Arguments

key

Address of a variable that receives the key value. This value is used in calls to tis_getspecific() and tis_setspecific() to obtain and set the value associated with this key.

destructor

Address of a routine that is called to destroy the context value when a thread terminates with a non-NULL value for the key. Note that this argument is used only when threads are present.

Description

This routine generates a unique thread-specific data key. The key argument points to an opaque object used to locate data.

This routine generates and returns a new key value. The key reserves a cell. Each call to this routine creates a new cell that is unique within an application invocation. Keys must be generated from initialization code that is guaranteed to be called only once within each process. (See the tis_once() description for more information.)

Your program can associate an optional destructor function with each key. At thread exit, if a key has a non-NULL destructor function pointer, and the thread has a non-NULL value associated with that key, the function pointed to is called with the current associated value as its sole argument. The order in which data destructors are called at thread termination is undefined.

When threads are present, keys and any corresponding data are thread specific; they enable the context to be maintained on a per-thread basis. For more information about the use of tis_key_create() in a threaded environment, refer to the pthread_key_create() description.

The Threads Library imposes a maximum number of thread-specific data keys, equal to the symbolic constant PTHREAD_KEYS_MAX .

Associated Routines

tis_getspecific()
tis_key_delete()
tis_setspecific()
tis_once()

Deletes the specified thread-specific data key.

Syntax

tis_key_delete(
key );

Argument	Data Type	Access
key	opaque pthread_key_t	write

int
tis_key_delete (
pthread_key_t key);

Arguments

key

Thread-specific data key to be deleted.

Description

This routine deletes a thread-specific data key key previously returned by a call to the tis_key_create() routine. The data values associated with key need not be NULL at the time this routine is called. The application must free any application storage or perform any cleanup actions for data structures related to the deleted key or associated data. This cleanup can be done before or after this routine is called. If the cleanup is done after this routine is called, the application must have a private mechanism to access any and all thread-specific values, contexts, and so on.

Attempting to use the thread-specific data key key after calling this routine results in unpredictable behavior.

No destructor functions are invoked by this routine. Any destructor functions that may have been associated with key will no longer be called upon thread exit.

This routine can be called from destructor functions.

Associated Routines

tis_getspecific()
tis_key_create()
tis_setspecific()

Locks the Threads Library global mutex.

Syntax

tis_lock_global( );

int
tis_lock_global (void);

Arguments

None

Description

This routine locks the global mutex. The global mutex is recursive. For example, if you called tis_lock_global() three times, tis_unlock_global() unlocks the global mutex when you call it the third time.

For more information about actions taken when threads are present, refer to the pthread_lock_global_np() description.

Associated Routines

tis_unlock_global()

Destroys the specified mutex object.

Syntax

tis_mutex_destroy(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	write

int
tis_mutex_destroy (
pthread_mutex_t *mutex);

Arguments

mutex

Address of the mutex object (passed by reference) to be destroyed.

Description

This routine destroys a mutex object by uninitializing it, and should be called when a mutex object is no longer referenced. After this routine is called, the Threads Library can reclaim internal storage used by the mutex object.

It is safe to destroy an initialized mutex object that is unlocked. However, it is illegal to destroy a locked mutex object.

The results of this routine are unpredictable if the mutex object specified in the mutex argument either does not currently exist or is not initialized.

Associated Routines

tis_mutex_init()
tis_mutex_lock()
tis_mutex_trylock()
tis_mutex_unlock()

Initializes the specified mutex object.

Syntax

tis_mutex_init(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	write

int
tis_mutex_init (
pthread_mutex_t *mutex );

Arguments

mutex

Pointer to a mutex object (passed by reference) to be initialized.

Description

This routine initializes a mutex object with the Threads Library default mutex attributes. A mutex is a synchronization object that allows multiple threads to serialize their access to shared data.

The mutex object is initialized and set to the unlocked state.

Your program can use the PTHREAD_MUTEX_INITIALIZER macro to statically initialize a mutex object without calling this routine. 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_mutex_init() . Use this macro as follows:
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER ;

Associated Routines

tis_mutex_destroy()
tis_mutex_lock()
tis_mutex_trylock()
tis_mutex_unlock()

Locks an unlocked mutex.

Syntax

tis_mutex_lock(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	read

int
tis_mutex_lock (
pthread_mutex_t *mutex);

Arguments

mutex

Address of the mutex (passed by reference) to be locked.

Description

This routine locks the specified mutex mutex. A deadlock can result if the owner of a mutex calls this routine in an attempt to lock the same mutex a second time. (The Threads Library may not detect or report the deadlock.)

In a threaded environment, 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.

Associated Routines

tis_mutex_destroy()
tis_mutex_init()
tis_mutex_trylock()
tis_mutex_unlock()

	privacy and legal statement
6101PRO_027.HTML