Guide to the POSIX Threads Library
tis_mutex_trylock
Attempts to lock the specified mutex.
Syntax
tis_mutex_trylock( mutex );
Argument |
Data Type |
Access |
mutex
|
opaque pthread_mutex_t
|
read
|
C Binding #include <tis.h>
int
tis_mutex_trylock (
pthread_mutex_t *mutex);
Arguments
mutex
Address of the mutex (passed by reference) to be locked.
Description
This routine attempts to lock the specified mutex mutex. When
this routine is called, an attempt is made immediately to lock the
mutex. If the mutex is successfully locked, zero (0) is returned.
If the specified mutex is already locked when this routine is called,
the caller does not wait for the mutex to become available. [EBUSY] is
returned, and the thread does not wait to acquire the lock.
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 mutex is already locked; therefore, it was not acquired.
|
[EINVAL]
|
The value specified by
mutex is not a valid mutex.
|
Associated Routines
tis_mutex_destroy()
tis_mutex_init()
tis_mutex_lock()
tis_mutex_unlock()
tis_mutex_unlock
Unlocks the specified mutex.
Syntax
tis_mutex_unlock( mutex );
Argument |
Data Type |
Access |
mutex
|
opaque pthread_mutex_t
|
read
|
C Binding #include <tis.h>
int
tis_mutex_unlock (
pthread_mutex_t *mutex);
Arguments
mutex
Address of the mutex (passed by reference) to be unlocked.
Description
This routine unlocks the specified mutex mutex.
For more information about actions taken when threads are present,
refer to the
pthread_mutex_unlock()
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
mutex is not a valid mutex.
|
[EPERM]
|
The caller does not own the mutex.
|
Associated Routines
tis_mutex_destroy()
tis_mutex_init()
tis_mutex_lock()
tis_mutex_trylock()
tis_once
Calls a one-time initialization routine that can be executed by only
one thread, once.
Syntax
tis_once( once _control, init _routine );
Argument |
Data Type |
Access |
once_control
|
opaque pthread_once_t
|
modify
|
init_routine
|
procedure
|
read
|
C Binding #include <tis.h>
int
tis_once (
pthread_once_t *once_control,
void (*init_routine) (void));
Arguments
once_control
Address of a record (control block) that defines the one-time
initialization code. Any one-time initialization routine in static
storage specified by once_control 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
tis_once()
.
Description
The first call to this routine by a process with a given
once_control calls the init_routine with no
arguments. Thereafter, subsequent calls to
tis_once()
with the same once_control do not call the
init_routine. On return from
tis_once()
, it is guaranteed that the initialization routine has completed.
For example, a mutex or a thread-specific data key must be created
exactly once. In a threaded environment, calling
tis_once()
ensures that the initialization is serialized across multiple threads.
Note
If you specify an init_routine that directly or indirectly
results in a recursive call to
tis_once()
and that specifies the same init_block argument, the recursive
call results in a deadlock.
|
The
PTHREAD_ONCE_INIT
macro, defined in the
pthread.h
header file, must be used to initialize a once_control record.
Thus, your program must declare a 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
tis_once()
. For example, you can code an "init" routine that begins
with the following basic logic:
init()
{
static pthread_mutex_t mutex = PTHREAD_MUTEX_INIT;
static int flag = FALSE;
tis_mutex_lock(&mutex);
if(!flag)
{
flag = TRUE;
/* initialize code */
}
tis_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.
|
tis_read_lock
Acquires a read-write lock for read access.
Syntax
tis_read_lock( lock );
Argument |
Data Type |
Access |
lock
|
opaque tis_rwlock_t
|
write
|
C Binding #include <tis.h>
int
tis_read_lock (
tis_rwlock_t *lock);
Arguments
lock
Address of the read-write lock.
Description
This routine acquires a read-write lock for read access. This routine
waits for any existing lock holder for write access to relinquish its
lock before granting the lock for read access. This routine returns
when the lock is acquired. If the lock is already held simply for read
access, the lock is granted.
For each call to
tis_read_lock()
that successfully acquires the lock for read access, a corresponding
call to
tis_read_unlock()
must be issued.
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
lock is not a valid read-write lock.
|
Associated Routines
tis_read_trylock()
tis_read_unlock()
tis_rwlock_destroy()
tis_rwlock_init()
tis_write_lock()
tis_write_trylock()
tis_write_unlock()
tis_read_trylock
Attempts to acquire a read-write lock for read access. Does not wait if
the lock cannot be immediately granted.
Syntax
tis_read_trylock( lock );
Argument |
Data Type |
Access |
lock
|
opaque tis_rwlock_t
|
write
|
C Binding #include <tis.h>
int
tis_read_trylock (
tis_rwlock_t *lock);
Arguments
lock
Address of the read-write lock to be acquired.
Description
This routine attempts to acquire a read-write lock for read access. If
the lock cannot be granted, the routine returns without waiting.
When a thread calls this routine, an attempt is made to immediately
acquire the lock for read access. If the lock is acquired, zero (0) is
returned. If a holder of the lock for write access exists, [EBUSY] is
returned.
If the lock cannot be acquired for read access immediately, the calling
program does not wait for the lock to be released.
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; the lock was acquired.
|
[EBUSY]
|
The lock is being held for write access. The lock for read access was
not acquired.
|
[EINVAL]
|
The value specified by
lock is not a valid read-write lock.
|
Associated Routines
tis_read_lock()
tis_read_unlock()
tis_rwlock_destroy()
tis_rwlock_init()
tis_write_lock()
tis_write_trylock()
tis_write_unlock()
tis_read_unlock
Unlocks a read-write lock that was acquired for read access.
Syntax
tis_read_unlock( lock );
Argument |
Data Type |
Access |
lock
|
opaque tis_rwlock_t
|
write
|
C Binding #include <tis.h>
int
tis_read_unlock (
tis_rwlock_t *lock);
Arguments
lock
Address of the read-write lock to be unlocked.
Description
This routine unlocks a read-write lock that was acquired for read
access. If there are no other holders of the lock for read access and
another thread is waiting to acquire the lock for write access, that
lock acquisition is granted.
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
lock is not a valid read-write lock.
|
Associated Routines
tis_read_lock()
tis_read_trylock()
tis_rwlock_destroy()
tis_rwlock_init()
tis_write_lock()
tis_write_trylock()
tis_write_unlock()
tis_rwlock_destroy
Destroys the specified read-write lock object.
Syntax
tis_rwlock_destroy( lock );
Argument |
Data Type |
Access |
lock
|
opaque tis_rwlock_t
|
write
|
C Binding #include <tis.h>
int
tis_rwlock_destroy (
tis_rwlock_t *lock);
Arguments
lock
Address of the read-write lock object to be destroyed.
Description
This routine destroys the specified read-write lock object. Prior to
calling this routine, ensure that there are no locks granted to the
specified read-write lock and that there are no threads waiting for
pending lock acquisitions on the specified read-write lock.
This routine should be called only after all reader threads (and
perhaps one writer thread) have finished using the specified read-write
lock.
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 lock is in use.
|
[EINVAL]
|
The value specified by
lock is not a valid read-write lock.
|
Associated Routines
tis_read_lock()
tis_read_trylock()
tis_read_unlock()
tis_rwlock_init()
tis_write_lock()
tis_write_trylock()
tis_write_unlock()
tis_rwlock_init
Initializes a read-write lock object.
Syntax
tis_rwlock_init( lock );
Argument |
Data Type |
Access |
lock
|
opaque tis_rwlock_t
|
write
|
C Binding #include <tis.h>
int
tis_rwlock_init (
tis_rwlock_t *lock);
Arguments
lock
Address of a read-write lock object.
Description
This routine initializes a read-write lock object. The routine
initializes the
tis_rwlock_t
structure that holds the object's lock states.
To destroy a read-write lock object, call the
tis_rwlock_destroy()
routine.
Note
The tis read-write lock has no relationship to the
Single UNIX Specification, Version 2 (SUSV2, or UNIX98) read-write lock
routines (such as
pthread_rwlock_init()
). The
tis_rwlock_t
type, in particular, cannot be used with the pthread
read-write lock functions, nor can a
pthread_rwlock_t
type be used with the tis read-write lock functions.
|
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
lock is not a valid read-write lock.
|
[ENOMEM]
|
Insufficient memory to initialize
lock.
|
Associated Routines
tis_read_lock()
tis_read_trylock()
tis_read_unlock()
tis_rwlock_destroy()
tis_write_lock()
tis_write_trylock()
tis_write_unlock()
tis_self
Returns the identifier of the calling thread.
Syntax
tis_self( void);
C Binding #include <tis.h>
pthread_t
tis_self (void);
Arguments
None
Description
This routine allows a thread to obtain its own thread identifier.
This value becomes meaningless when the thread is destroyed.
Note that the initial thread in a process can "change
identity" when thread system initialization completes---that is,
when the multithreading run-time environment is loaded.
Return Values Returns the thread identifier of the calling thread.
Associated Routines
pthread_create()
tis_setcancelstate
Changes the calling thread's cancelability state.
Syntax
tis_setcancelstate( state , oldstate );
Argument |
Data Type |
Access |
state
|
integer
|
read
|
oldstate
|
integer
|
write
|
C Binding #include <tis.h>
int
tis_setcancelstate (
int state,
int *oldstate );
Arguments
state
State of general cancelability to set for the calling thread. Valid
state values are as follows:
PTHREAD_CANCEL_ENABLE
PTHREAD_CANCEL_DISABLE
oldstate
Receives the value of the calling thread's previous cancelability state.
Description
This routine sets the calling thread's cancelability state to the value
specified in the state argument and returns the calling
thread's previous cancelability state in the location referenced by the
oldstate argument.
When a thread's 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 is
enabled.
When a thread is created, its default cancelability state is
PTHREAD_CANCEL_ENABLE
. When this routine is called prior to loading threads, the
cancelability state propagates to the initial thread in the executing
program.
Possible Problems When Disabling Cancelability
The most important use of a cancelation request is to ensure that
indefinite wait operations are terminated. For example, a thread
waiting on some network connection, which might take days to respond
(or might never respond), should be made cancelable.
When a thread's cancelability state is disabled, no routine
called within that thread is cancelable. As a result, the user is
unable to cancel the operation. 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.
Return Values On successful completion, this routine returns the
calling thread's previous cancelability state in the oldstate
argument.
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
.
|
Associated Routines
tis_testcancel()
|