Tru64 UNIX
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:

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