Guide to the POSIX Threads Library
tis_cond_wait
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
|
C Binding #include <tis.h>
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.
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 or the value specified
by
mutex is not a valid mutex, or
Different mutexes are supplied for concurrent
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.
|
Associated Routines
tis_cond_broadcast()
tis_cond_destroy()
tis_cond_init()
tis_cond_signal()
tis_getspecific
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
|
C Binding #include <tis.h>
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.
Return Values No errors are returned. This routine returns the data
value associated with the specified thread-specific data key
key. If no data value is associated with key, or if
key is not defined, then a NULL value is returned.
Associated Routines
tis_key_create()
tis_key_delete()
tis_setspecific()
tis_get_expiration
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
|
C Binding #include <tis.h>
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.
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
delta is invalid.
|
Associated Routines
tis_cond_timedwait()
tis_io_complete
AST completion routine to VMS I/O system services.
This routine is for OpenVMS systems only.
Syntax
tis_io_complete( );
C Binding #include <tis.h>
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
).
Return Values None. Associated Routines
tis_sync()
tis_key_create
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
|
C Binding #include <tis.h>
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
.
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.
|
[EAGAIN]
|
The system lacked the necessary resources to create another
thread-specific data key, or the limit on the total number of keys per
process (
PTHREAD_KEYS_MAX
) has been exceeded.
|
[EINVAL]
|
The value specified by
key is invalid.
|
[ENOMEM]
|
Insufficient memory to create the key.
|
Associated Routines
tis_getspecific()
tis_key_delete()
tis_setspecific()
tis_once()
tis_key_delete
Deletes the specified thread-specific data key.
Syntax
tis_key_delete( key );
Argument |
Data Type |
Access |
key
|
opaque pthread_key_t
|
write
|
C Binding #include <tis.h>
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.
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 for
key is invalid.
|
Associated Routines
tis_getspecific()
tis_key_create()
tis_setspecific()
tis_lock_global
Locks the Threads Library global mutex.
Syntax
tis_lock_global( );
C Binding #include <tis.h>
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.
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.
|
Associated Routines
tis_unlock_global()
tis_mutex_destroy
Destroys the specified mutex object.
Syntax
tis_mutex_destroy( mutex );
Argument |
Data Type |
Access |
mutex
|
opaque pthread_mutex_t
|
write
|
C Binding #include <tis.h>
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.
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]
|
An attempt was made to destroy the object referenced by
mutex while it is locked or referenced.
|
[EINVAL]
|
The value specified by
mutex is not a valid mutex.
|
[EPERM]
|
The caller does not have privileges to perform the operation.
|
Associated Routines
tis_mutex_init()
tis_mutex_lock()
tis_mutex_trylock()
tis_mutex_unlock()
tis_mutex_init
Initializes the specified mutex object.
Syntax
tis_mutex_init( mutex );
Argument |
Data Type |
Access |
mutex
|
opaque pthread_mutex_t
|
write
|
C Binding #include <tis.h>
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
;
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.
|
[EAGAIN]
|
The system lacks the necessary resources to initialize a mutex.
|
[EBUSY]
|
The implementation has detected an attempt to reinitialize
mutex (a previously initialized, but not yet destroyed, mutex).
|
[EINVAL]
|
The value specified by
mutex is not a valid mutex.
|
[ENOMEM]
|
Insufficient memory to initialize the mutex.
|
[EPERM]
|
The caller does not have privileges to perform this operation.
|
Associated Routines
tis_mutex_destroy()
tis_mutex_lock()
tis_mutex_trylock()
tis_mutex_unlock()
tis_mutex_lock
Locks an unlocked mutex.
Syntax
tis_mutex_lock( mutex );
Argument |
Data Type |
Access |
mutex
|
opaque pthread_mutex_t
|
read
|
C Binding #include <tis.h>
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.
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.
|
[EDEADLK]
|
A deadlock condition is detected.
|
[EINVAL]
|
The value specified by
mutex is not a valid mutex.
|
Associated Routines
tis_mutex_destroy()
tis_mutex_init()
tis_mutex_trylock()
tis_mutex_unlock()
|