Updated: 11 December 1998 |
Guide to DECthreads
Previous | Contents | Index |
Attempts to acquire a read-write lock object for read access without waiting.
pthread_rwlock_tryrdlock(
rwlock );
Argument Data Type Access rwlock opaque pthread_rwlock_t write
rwlock
Address of the read-write lock object to acquire for read access.
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 a thread already holds the lock for read access, the lock is granted and this routine returns. 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 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 corrresponding 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 | Description |
---|---|
0 | Successful completion; the read-write lock object was acquired for read access. |
[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. |
[EINVAL] | The value specified by rwlock does not refer to an initialized read-write lock object. |
[EDEADLCK] | The current thread already owns the read-write lock for writing. |
[EAGAIN] | The lock for read access could not be acquired because the maximum number of read lock acquisitions for rwlock has been exceeded. |
Attempts to acquire a read-write lock object for write access without waiting.
pthread_rwlock_trywrlock(
rwlock );
Argument Data Type Access rwlock opaque pthread_rwlock_t write
rwlock
Address of the read-write lock object to acquire for write access.
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 | 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. |
[EINVAL] | The value specified by rwlock does not refer to an initialized read-write lock object. |
[EDEADLCK] | The current thread already owns the read-write lock for write or read access. |
Unlocks a read-write lock object.
pthread_rwlock_unlock(
rwlock );
Argument Data Type Access rwlock opaque pthread_rwlock_t write
rwlock
Address of the read-write lock object to be unlocked.
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 not 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, DECthreads 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, DECthreads 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 | 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. |
Acquires, after waiting if necessary, a read-write lock for write access.
pthread_rwlock_wrlock(
rwlock );
Argument Data Type Access rwlock opaque pthread_rwlock_t write
rwlock
Address of the read-write lock object to acquire for write access.
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 DIGITAL UNIX signal or an OpenVMS AST) while waiting for a read-write lock for write access, upon return from the signal handler 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 | Description |
---|---|
0 | Successful completion; the read-write lock object was acquired for write access. |
[EINVAL] | The value specified by rwlock does not refer to an initialized read-write lock object. |
[EDEADLCK] | The calling thread already owns the read-write lock for write or read access. |
Obtains the identifier of the calling thread.
pthread_self( );
None
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.
Sets the calling thread's cancelability state.
pthread_setcancelstate(
state ,
oldstate );
Argument Data Type Access state integer read oldstate integer write
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.
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 | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The specified state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE. |
Sets the calling thread's cancelability type.
pthread_setcanceltype(
type ,
oldtype );
Argument Data Type Access type integer read oldtype integer write
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.
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 state is PTHREAD_CANCEL_ENABLE and the thread's cancelability type is set to 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 state is PTHREAD_CANCEL_ENABLE and its 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 DECthreads 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 | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The specified type is not PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_AYNCHRONOUS. |
Changes the value of the concurrency level global variable for this process.
pthread_setconcurrency(
level );
Argument Data Type Access level int read
level
New value for the concurrency level for this process.
This routine stores the value specified in the level argument in the "concurrency level" global setting for the calling thread's process. Because DECthreads automatically manages the concurrency of all threads in a multithreaded process, DECthreads ignores this concurrency level value.The concurrency level value has no effect on the behavior of a multithreaded program that uses DECthreads. 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 DECthreads 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 | Description |
---|---|
0 | Successful completion. |
[EINVAL] | The value specified by new_level is negative. |
[EAGAIN] | The value specified by new_level would cause a system resource to be exceeded. |
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
6101PRO_024.HTML
|