Document revision date: 30 March 2001

## Guide to the POSIX Threads Library

Previous | Contents | Index

## pthread_rwlock_tryrdlock

> Attempts to acquire a read-write lock object for read access without waiting.

### Syntax

> pthread_rwlock_tryrdlock(
> rwlock );

> Argument | Data Type | Access
> --- | --- | ---
> rwlock | opaque pthread_rwlock_t | write

C Binding #include <pthread.h>

int
pthread_rwlock_tryrdlock (
pthread_rwlock_t *rwlock);

### Arguments

> #### rwlock

> Address of the read-write lock object to acquire for read access.

### Description

> This routine attempts to acquire a read-write lock for read access, but does not wait for the lock if it not immediately available.

> If no thread already holds the lock for write access and there are no writers waiting to acquire the lock, the lock for read access is granted to the calling thread and this routine returns. If a thread already holds the lock for read access, the lock is granted and this routine returns.

> If some thread already holds the lock for write access, the calling thread will not acquire the read lock. Results are undefined if the calling thread has already acquired a lock for write access on rwlock when this routine is called.

> A thread can hold multiple, concurrent locks for read access on the same read-write lock. In a given thread, for each call to this routine that successfully acquires the same read-write lock for read access, a corresponding call to `pthread_rwlock_unlock()` must be issued.

> If the read-write lock object referenced by rwlock is not initialized, the results of calling this routine are undefined.

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 read-write lock object was acquired for read access.
[EAGAIN] | The lock for read access could not be acquired because the maximum number of read lock acquisitions for rwlock has been exceeded.
[EBUSY] | The read-write lock could not be acquired for read access because another thread already acquired it for write access or is blocked and waiting for it for write access.
[EDEADLCK] | The current thread already owns the read-write lock for writing.
[EINVAL] | The value specified by rwlock does not refer to an initialized read-write lock object.

#### Associated Routines

> `pthread_rwlockattr_init()`
> `pthread_rwlock_init()`
> `pthread_rwlock_rdlock()`
> `pthread_rwlock_unlock()`
> `pthread_rwlock_wrlock()`

## pthread_rwlock_trywrlock

> Attempts to acquire a read-write lock object for write access without waiting.

### Syntax

> pthread_rwlock_trywrlock(
> rwlock );

> Argument | Data Type | Access
> --- | --- | ---
> rwlock | opaque pthread_rwlock_t | write

C Binding #include <pthread.h>

int
pthread_rwlock_trywrlock (
pthread_rwlock_t *rwlock);

### Arguments

> #### rwlock

> Address of the read-write lock object to acquire for write access.

### Description

> This routine attempts to acquire the read-write lock referenced by rwlock for write access. If any thread already holds that lock for write access or read access, this routine fails and returns [EBUSY] and the calling thread does not wait for the lock to become available.

> Results are undefined if the calling thread holds the read-write lock (whether for read or write access) at the time this routine is called.

> If the read-write lock object referenced by rwlock is not initialized, the results of calling this routine are undefined.

> Realtime applications can encounter priority inversion when using read-write locks. The problem occurs when a high-priority thread acquires a read-write lock that is about to be unlocked (that is, posted) by a low-priority thread, but the low-priority thread is preempted by a medium-priority thread. This scenario leads to priority inversion in that a high-priority thread is blocked by lower-priority threads for an unlimited period of time. During system design, realtime programmers must take into account the possibility of priority inversion and can deal with it in a number of ways, such as by having critical sections that are guarded by read-write locks execute at a high priority, so that a thread cannot be preempted while executing in its critical section.

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 read-write lock object was acquired for write access.
[EBUSY] | The read-write lock could not be acquired for write access because it was already locked for write access or for read access.
[EDEADLCK] | The current thread already owns the read-write lock for write or read access.
[EINVAL] | The value specified by rwlock does not refer to an initialized read-write lock object.

#### Associated Routines

> `pthread_rwlockattr_init()`
> `pthread_rwlock_init()`
> `pthread_rwlock_rdlock()`
> `pthread_rwlock_unlock()`
> `pthread_rwlock_wrlock()`

## pthread_rwlock_unlock

> Unlocks a read-write lock object.

### Syntax

> pthread_rwlock_unlock(
> rwlock );

> Argument | Data Type | Access
> --- | --- | ---
> rwlock | opaque pthread_rwlock_t | write

C Binding #include <pthread.h>

int
pthread_rwlock_unlock (
pthread_rwlock_t *rwlock);

### Arguments

> #### rwlock

> Address of the read-write lock object to be unlocked.

### Description

> This routine releases a lock acquisition held on the read-write lock object referenced by rwlock. Results are undefined if rwlock is not held by the calling thread.

> If this routine is called to release a lock for read access on rwlock and the calling thread also currently holds other locks for read access on rwlock, the read-write lock object remains in the read locked state. If this routine releases the calling thread's last lock for read access on rwlock, the calling thread is no longer one of the owners of the lock object.

> If this routine is called to release a lock for write access on rwlock, the lock object is put in the unlocked state with no owners.

> If a call to this routine results in the read-write lock object becoming unlocked and there are multiple threads waiting to acquire that lock for write access, the Threads Library uses the scheduling policy of those waiting threads to determine which thread next acquires the lock object for write access. If there are multiple threads waiting to acquire the read-write lock object for read access, the Threads Library uses the scheduling policy of those waiting threads to determine the order in which those threads acquire the lock for read access. If there are multiple threads waiting to acquire the read-write lock object for both read and write access, it is unspecified whether a thread waiting for read access or for write access next acquires the lock object.

> If the read-write lock object referenced by rwlock is not initialized, the results of calling this routine are undefined.

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 values specified by rwlock does not refer to an initialized read-write lock object.
[EPERM] | The calling thread does not hold the read-write lock object.

#### Associated Routines

> `pthread_rwlockattr_init()`
> `pthread_rwlock_init()`
> `pthread_rwlock_rdlock()`
> `pthread_rwlock_wrlock()`

## pthread_rwlock_wrlock

> Acquires a read-write lock for write access.

### Syntax

> pthread_rwlock_wrlock(
> rwlock );

> Argument | Data Type | Access
> --- | --- | ---
> rwlock | opaque pthread_rwlock_t | write

C Binding #include <pthread.h>

int
pthread_rwlock_wrlock (
pthread_rwlock_t *rwlock);

### Arguments

> #### rwlock

> Address of the read-write lock object to acquire for write access.

### Description

> This routine attempts to acquire a read-write lock for write access. If any thread already has acquired the lock for write access or read access, the lock is not granted and the calling thread blocks until it can acquire the lock. A thread can hold only one lock for write access on a read-write lock.

> Results are undefined if the calling thread holds the read-write lock (whether for read or write access) at the time this routine is called.

> If the read-write lock object referenced by rwlock is not initialized, the results of calling this routine are undefined.

> If a thread is interrupted (via a Tru64 UNIX signal or an OpenVMS AST) while waiting for a read-write lock for write access, upon return from the interrupt routine the thread resumes waiting for the lock as if it had not been interrupted.

> Realtime applications can encounter priority inversion when using read-write locks. The problem occurs when a high-priority thread acquires a read-write lock that is about to be unlocked (that is, posted) by a low-priority thread, but the low-priority thread is preempted by a medium-priority thread. This scenario leads to priority inversion in that a high-priority thread is blocked by lower-priority threads for an unlimited period of time. During system design, realtime programmers must take into account the possibility of priority inversion and can deal with it in a number of ways, such as by having critical sections that are guarded by read-write locks execute at a high priority, so that a thread cannot be preempted while executing in its critical section.

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 read-write lock object was acquired for write access.
[EDEADLCK] | The calling thread already owns the read-write lock for write or read access.
[EINVAL] | The value specified by rwlock does not refer to an initialized read-write lock object.

#### Associated Routines

> `pthread_rwlockattr_init()`
> `pthread_rwlock_init()`
> `pthread_rwlock_rdlock()`
> `pthread_rwlock_trywrlock()`
> `pthread_rwlock_unlock()`

## pthread_self

> Obtains the identifier of the calling thread.

### Syntax

> pthread_self( );

C Binding #include <pthread.h>

pthread_t
pthread_self (void);

### Arguments

> ####

> None

### Description

> This routine returns the address of the calling thread's own thread identifier. For example, you can use this thread object to obtain the calling thread's own sequence number. To do so, pass the return value from this routine in a call to the `pthread_getsequence_np()` routine, as follows:

>        .
>        .
>        .
>        unsigned long     this_thread_nbr;
>        .
>        .
>        .
>        this_thread_nbr = pthread_getsequence_np( pthread_self( ) );
>        .
>        .
>        .

> The return value from the `pthread_self()` routine becomes meaningless after the calling thread is destroyed.

Return Values Returns the address of the calling thread's own thread object.

#### Associated Routines

> `pthread_cancel()`
> `pthread_create()`
> `pthread_detach()`
> `pthread_exit()`
> `pthread_getsequence_np()`
> `pthread_join()`
> `pthread_kill()`
> `pthread_sigmask()`

## pthread_setcancelstate

> Sets the calling thread's cancelability state.

### Syntax

> pthread_setcancelstate(
> state ,
> oldstate );

> Argument | Data Type | Access
> --- | --- | ---
> state | integer | read
> oldstate | integer | write

C Binding #include <pthread.h>

int
pthread_setcancelstate (
int state,
int *oldstate );

### Arguments

> #### state

> State of general cancelability to set for the calling thread. The following are valid cancel state values:

> > `PTHREAD_CANCEL_ENABLE`
> > `PTHREAD_CANCEL_DISABLE`

> #### oldstate

> Previous cancelability state for the calling thread.

### Description

> This routine sets the calling thread's cancelability state and returns the calling thread's previous cancelability state in oldstate.

> When 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 type is enabled.

> When a thread is created, its default cancelability state is `PTHREAD_CANCEL_ENABLE` .

> Possible Problems When Disabling Cancelability

> The most important use of thread cancelation is to ensure that indefinite wait operations are terminated. For example, a thread that waits on some network connection, which can possibly take days to respond (or might never respond), should be made cancelable.

> When a thread's cancelability is disabled, no routine in that thread is cancelable. As a result, the user is unable to cancel the operation performed by that thread. 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 location specified by 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

> `pthread_cancel()`
> `pthread_setcanceltype()`
> `pthread_testcancel()`

## pthread_setcanceltype

> Sets the calling thread's cancelability type.

### Syntax

> pthread_setcanceltype(
> type ,
> oldtype );

> Argument | Data Type | Access
> --- | --- | ---
> type | integer | read
> oldtype | integer | write

C Binding #include <pthread.h>

int
pthread_setcanceltype (
int type,
int *oldtype);

### Arguments

> #### type

> The cancelability type to set for the calling thread. The following are valid values:

> > `PTHREAD_CANCEL_DEFERRED`
> > `PTHREAD_CANCEL_ASYNCHRONOUS`

> #### oldtype

> Returns the previous cancelability type.

### Description

> This routine sets the cancelability type and returns the previous type in location oldtype.

> When a thread's cancelability state is set to `PTHREAD_CANCEL_DISABLE` , (see `pthread_setcancelstate()` ), a cancelation request cannot be delivered to that thread, even if a cancelable routine is called or asynchronous cancelability type is enabled.

> When the cancelability state is set to `PTHREAD_CANCEL_ENABLE` , cancelability depends on the thread's cancelability type, as follows:

> - If the thread's cancelability type is `PTHREAD_CANCEL_DEFERRED` , the thread can only receive a cancelation request at a cancelation point (including condition waits, thread joins, and calls to `pthread_testcancel()` ).
> - If the thread's cancelability type is `PTHREAD_CANCEL_ASYNCHRONOUS` , the thread can be canceled at any point in its execution.

> When a thread is created, the default cancelability type is
> `PTHREAD_CANCEL_DEFERRED` .

> Caution If the asynchronous cancelability type is set, do not call any routine unless it is explicitly documented as "safe for asynchronous cancelation." Note that none of the general run-time libraries and none of the POSIX Threads libraries are safe for asynchronous cancelation except for `pthread_setcanceltype()` and `pthread_setcancelstate()` . Use asynchronous cancelability only when you have a compute-bound section of code that carries no state and makes no routine calls.

Return Values On successful completion, this routine returns the previous cancelability type in oldtype.

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 type is not `PTHREAD_CANCEL_DEFERRED` or `PTHREAD_CANCEL_AYNCHRONOUS` .

#### Associated Routines

> `pthread_cancel()`
> `pthread_setcancelstate()`
> `pthread_testcancel()`

## pthread_setconcurrency

> Changes the value of the concurrency level global variable for this process.

### Syntax

> pthread_setconcurrency(
> level );

> Argument | Data Type | Access
> --- | --- | ---
> level | int | read

C Binding #include <pthread.h>

int
pthread_setconcurrency (
int level);

### Arguments

> #### level

> New value for the concurrency level for this process.

### Description

> This routine stores the value specified in the level argument in the "concurrency level" global setting for the calling thread's process. Because the Threads Library automatically manages the concurrency of all threads in a multithreaded process, it ignores this concurrency level value.

> "Concurrency level" is a parameter used to coerce "simple" 2-level schedulers into allowing application concurrency. The Threads Library supplies the maximum concurrency at all times, automatically. It has no need for coercion, and calls `pthread_setconcurrency()` merely to determine the value returned by the next call to `pthread_getconcurrency()` .

> The concurrency level value has no effect on the behavior of a multithreaded program that uses the Threads Library. This routine is provided for Single UNIX Specification, Version 2 source code compatibility and has no other effect when called.

> After calling this routine, subsequent calls to the `pthread_getconcurrency()` routine return the same value, until another call to `pthread_setconcurrency()` changes that value.

> The initial concurrency level is zero (0), indicating that the Threads Library manages the concurrency level. To indicate in a portable manner that the implementation is to resume control of concurrency level, call this routine with a level argument of zero (0).

> The concurrency level value can be obtained using the `pthread_getconcurrency()` 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.
[EAGAIN] | The value specified by new_level would cause a system resource to be exceeded.
[EINVAL] | The value specified by new_level is negative.

#### Associated Routines

> `pthread_getconcurrency()`

Previous | Next | Contents | Index

| privacy and legal statement |
6101PRO_024.HTML