Document revision date: 30 March 2001

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

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.

Associated Routines

pthread_rwlockattr_init()
pthread_rwlock_init()
pthread_rwlock_rdlock()
pthread_rwlock_unlock()
pthread_rwlock_wrlock()

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

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.

Associated Routines

pthread_rwlockattr_init()
pthread_rwlock_init()
pthread_rwlock_rdlock()
pthread_rwlock_unlock()
pthread_rwlock_wrlock()

Unlocks a read-write lock object.

Syntax

pthread_rwlock_unlock(
rwlock );

Argument	Data Type	Access
rwlock	opaque pthread_rwlock_t	write

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.

Associated Routines

pthread_rwlockattr_init()
pthread_rwlock_init()
pthread_rwlock_rdlock()
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

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.

Associated Routines

pthread_rwlockattr_init()
pthread_rwlock_init()
pthread_rwlock_rdlock()
pthread_rwlock_trywrlock()
pthread_rwlock_unlock()

Obtains the identifier of the calling thread.

Syntax

pthread_self( );

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.

Associated Routines

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

Sets the calling thread's cancelability state.

Syntax

pthread_setcancelstate(
state ,
oldstate );

Argument	Data Type	Access
state	integer	read
oldstate	integer	write

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.

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

Sets the calling thread's cancelability type.

Syntax

pthread_setcanceltype(
type ,
oldtype );

Argument	Data Type	Access
type	integer	read
oldtype	integer	write

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.

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

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

Syntax

pthread_setconcurrency(
level );

Argument	Data Type	Access
level	int	read

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.

Associated Routines

pthread_getconcurrency()

	privacy and legal statement
6101PRO_024.HTML