pthread_rwlock_destroy(), pthread_rwlock_init()

destroy and initialize a read-write lock object 

Advanced Realtime Threads


SYNOPSIS

#include <pthread.h>

int pthread_rwlock_destroy(pthread_rwlock_t *rwlock);

int pthread_rwlock_init(pthread_rwlock_t *restrict rwlock, const pthread_rwlockattr_t *restrict attr);


DESCRIPTION

The pthread_rwlock_destroy() function destroys the read-write lock object pointed to by the rwlock argument. This function also releases any resources that the specified lock uses.

The pthread_rwlock_init() function allocates the resources required to use the read-write lock pointed to by the rwlock argument.

A read-write lock can be statically initialized by assigning PTHREAD_RWLOCK_INITIALIZER in its definition, as follows:

pthread_rwlock_t rwlock = PTHREAD_RWLOCK_INITIALIZER;

A read-write lock must be initialized (either by calling pthread_rwlock_init(), or statically) before it may be used in any other read-write lock functions. When a read-write lock is initialized statically, the resources usually allocated by pthread_rwlock_init() are initialized by any of the other read-write lock functions called (except pthread_rwlock_destroy()).

The pthread_rwlock_init() also initializes the lock to an unlocked state and assigns the attributes pointed to by the attr argument. When attr is NULL, pthread_rwlock_init() assigns the default read-write lock attributes to the specified lock. Once a lock has been initialized, you can use it any number of times without reinitializing it. Static initialization behaves as though pthread_rwlock_init() were called with a NULL read-write lock attribute.

If the pthread_rwlock_init() function fails, rwlock shall not be initialized and the contents of rwlock are undefined. When initialized statically, the various read-write lock functions will fail on initialization failure.

Only the object referenced by rwlock may be used for performing synchronization. The result of referring to copies of that object in calls to is undefined. You can only use rwlock itself to perform synchronization. Referring to copies of rwlock in calls to the pthread_rwlock_destroy(), pthread_rwlock_rdlock(), pthread_rwlock_timedrdlock(), pthread_rwlock_timedwrlock(), pthread_rwlock_tryrdlock(), pthread_rwlock_trywrlock(), pthread_rwlock_unlock(), or pthread_rwlock_wrlock() functions is not recommended. While the current implementation of these functions supports the use of copies, there is no guarantee that future implementations will have this support.


PARAMETERS

attr 

Points to an object specifying the attributes to assign to the read-write lock being initialized.

rwlock 

Points to a read-write lock to be initialized or destroyed.


RETURN VALUES

On success, the pthread_rwlock_destroy() and pthread_rwlock_init() functions return zero. On failure, the lock is neither initialized or destroyed, and these functions return one of the following error numbers:

EAGAIN 

Insufficient resources (other than memory) exist to initialize another read-write lock.

EBUSY 

You tried to destroy the object pointed to by rwlock while it was locked or held by another thread.

EINVAL 

The rwlock or attr arguments specify an invalid value. For example, this may occur when you try to destroy an uninitialized read-write lock with pthread_rwlock_destroy(), try to initialize an already initialized read-write lock with pthread_rwlock_init(), or try to use any read-lock lock without first initializing it.

ENOMEM 

Insufficient memory exists to initialize the read-write lock.

EPERM 

The caller lacks the required privilege to perform the operation.


CONFORMANCE

UNIX 03.


MULTITHREAD SAFETY LEVEL

MT-Safe.


PORTING ISSUES

None.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
pthread_rwlock_rdlock(), pthread_rwlock_timedrdlock(), pthread_rwlock_timedwrlock(), pthread_rwlock_tryrdlock(), pthread_rwlock_trywrlock(), pthread_rwlock_unlock(), pthread_rwlock_wrlock()


PTC MKS Toolkit 10.3 Documentation Build 39.