Document revision date: 30 March 2001

## Guide to the POSIX Threads Library

Previous | Contents | Index

## 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()`

Previous | Next | Contents | Index

| privacy and legal statement |
6101PRO_028.HTML