HP OpenVMS Systems Documentation

Obtains the value of the process-shared attribute of a read-write lock attributes object.

This routine is for Tru64 UNIX systems only.

Syntax

pthread_rwlockattr_getpshared(
attr ,
pshared );

Argument	Data Type	Access
attr	opaque pthread_rwlockattr_t	read
pshared	int	write

int
pthread_rwlockattr_getpshared (
const pthread_rwlockattr_t *attr,
int *pshared);

Arguments

attr

Address of the read-write lock attributes object whose process-shared attribute is to be obtained.

pshared

Receives the value of the process-shared attribute of the read-write lock attributes object specified by attr.

Description

This routine obtains the value of the process-shared attribute from the read-write lock attributes object specified by the attr argument and stores it in the location specified by the pshared argument. This attributes object must already be initialized at the time this routine is called.

Associated Routines

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

Initializes a read-write lock attributes object.

Syntax

pthread_rwlockattr_init(
attr );

Argument	Data Type	Access
attr	opaque pthread_rwlockattr_t	write

int
pthread_rwlockattr_init (
pthread_rwlockattr_t *attr);

Arguments

attr

Address of the read-write lock attributes object to be initialized.

Description

This routine initializes the read-write lock attributes object referenced by attr and sets its attributes with default values.

The results of calling this routine are undefined if attr references an already initialized read-write lock attributes object.

After an initialized read-write lock attributes object has been used to initialize one or more read-write lock objects, any operation on that attributes object (including destruction) has no effect on those read-write lock objects.

Associated Routines

pthread_rwlockattr_destroy()
pthread_rwlock_init()

Sets the value of the process-shared attribute of a read-write lock attributes object.

This routine is for Tru64 UNIX systems only.

Syntax

pthread_rwlockattr_setpshared(
attr ,
pshared );

Argument	Data Type	Access
attr	opaque pthread_rwlockattr_t	write
pshared	int	read

int
pthread_rwlockattr_setpshared (
pthread_rwlockattr_t *attr,
int pshared);

Arguments

attr

Address of the read-write lock attributes object whose process-shared attribute is to be modified.

pshared

New value for the process-shared attribute of the read-write lock attributes object specified by attr.

Description

This routine uses the value specified in the pshared argument to set the process-shared attribute of the read-write lock attributes object specified by the attr argument. This attributes object must already be initialized at the time this routine is called.

If the process-shared attribute is set to PTHREAD_PROCESS_PRIVATE , the read-write lock object can only be operated upon by threads created within the same process as the thread that initialized the read-write lock object. If threads of differing processes attempt to operate on such a read-write lock object, the behavior is undefined.

The default value of the process-shared attribute of a read-write lock attributes object is PTHREAD_PROCESS_PRIVATE .

If the process-shared attribute of a read-write lock attributes object is set to PTHREAD_PROCESS_SHARED , the read-write lock object can be operated upon by any thread that has access to the memory where that object is allocated, even if that object is allocated in memory that is shared by multiple processes.

Associated Routines

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

Destroys a read-write lock object.

Syntax

pthread_rwlock_destroy(
rwlock );

Argument	Data Type	Access
rwlock	opaque pthread_rwlock_t	write

int
pthread_rwlock_destroy (
pthread_rwlock_t *rwlock);

Arguments

rwlock

Address of the read-write lock object to be destroyed.

Description

This routine destroys the specified read-write lock object by uninitializing it, and should be called when the object is no longer referenced in your program. After this routine is called, the Threads Library may reclaim internal storage used by the specified read-write lock object. The effect of subsequent use of the lock is undefined until the lock is reinitialized by another call to pthread_rwlock_init() .

It is illegal to destroy a locked read-write lock.

The results of this routine are unpredictable if the specified read-write lock object does not currently exist or is not initialized. This routine destroys the read-write lock object specified by the rwlock argument and releases any resources that the object used.

A destroyed read-write lock object can be reinitialized using the
pthread_rwlock_init() routine. The results of otherwise referencing a destroyed read-write lock object are undefined.

Associated Routines

pthread_rwlock_init()

Obtains the object name from a read-write lock object.

Syntax

pthread_rwlock_getname_np(
rwlock ,
name ,
len );

Argument	Data Type	Access
rwlock	opaque pthread_rwlock_t	read
name	char	write
len	size_t	read

int
pthread_rwlock_getname_np (
pthread_rwlock_t *rwlock,
char *name,
size_t len);

Arguments

rwlock

Address of the read-write lock object whose object name is to be obtained.

name

Location to store the obtained object name.

len

Length in bytes of buffer at the location specified by name.

Description

This routine copies the object name from the read-write lock object specified by rwlock to the buffer at the location name. Before calling this routine, your program must allocate the buffer indicated by name.

The object name is a C language string and provides an identifier that is meaningful to a person debugging a multithreaded application. The maximum number of characters in the object name is 31.

If the specified read-write lock object has not been previously set with an object name, this routine copies a C language null string into the buffer at location name.

Associated Routines

pthread_rwlock_setname_np()

Initializes a read-write lock object.

Syntax

pthread_rwlock_init(
rwlock ,
attr );

Argument	Data Type	Access
rwlock	opaque pthread_rwlock_t	write
attr	opaque pthread_rwlockattr_t	read

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

Arguments

rwlock

Read-write lock object to be initialized.

attr

Read-write lock attributes object that defines the characteristics of the read-write lock to be initialized.

Description

This routine initializes a read-write lock object with the attributes specified by the read-write lock attributes object specified in attr. A read-write lock is a synchronization object that serializes access to shared information that needs to be read frequently and written only occasionally. A thread can acquire a read-write lock for shared read access or for exclusive write access.

Upon successful completion of this routine, the read-write lock is initialized and set to the unlocked state. If attr is set to NULL, the default read-write lock attributes are used; the effect is the same as passing the address of a default read-write lock attributes object. Once initialized, the lock can be used any number of times without being reinitialized.

Results of calling this routine are undefined if attr specifies an already initialized read-write lock or if rwlock is used without first being initialized.

If this routine returns unsuccessfully, rwlock is not initialized and the contents of rwlock are undefined.

A read-write lock is a resource of the process, not part of any particular thread. A read-write lock is neither destroyed not unlocked automatically when any thread exits. Because read-write locks are shared, they may be allocated in heap or static memory, but not on a stack.

In cases where default read-write lock attributes are appropriate, you may use the PTHREAD_RWLOCK_INITIALIZER macro to statically initialize the lock object without calling this routine. The effect is equivalent to dynamic initialization by a call to pthread_rwlock_init() with attr specified as NULL, except that no error checks are performed. Statically initialized read-write locks need not be destroyed using pthread_rwlock_destroy() .

Use the PTHREAD_RWLOCK_INITIALIZER macro as follows:

pthread_rwlock_t rwlock = PTHREAD_RWLOCK_INITIALIZER;

Associated Routines

pthread_rwlock_destroy()

Acquires a read-write lock object for read access.

Syntax

pthread_rwlock_rdlock(
rwlock );

Argument	Data Type	Access
rwlock	opaque pthread_rwlock_t	write

int
pthread_rwlock_rdlock (
pthread_rwlock_t *rwlock);

Arguments

rwlock

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

Description

This routine acquires a read-write lock for read access. 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.

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 some thread already holds the lock for write access, the calling thread will not acquire the read lock. If the read lock is not acquired, the calling thread blocks until it can acquire the lock for read access. Results are undefined if the calling thread has already acquired a lock for write access on rwlock when 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 read access, upon return from the interrupt routine the thread resumes waiting for the lock as if it had not been interrupted.

Associated Routines

pthread_rwlock_init()
pthread_rwlockattr_init()
pthread_rwlock_tryrdlock()
pthread_rwlock_wrlock()
pthread_rwlock_unlock()

Changes the object name in a read-write lock object.

Syntax

pthread_rwlock_setname_np(
rwlock ,
name ,
mbz );

Argument	Data Type	Access
rwlock	opaque pthread_rwlock_t	write
name	char	read
mbz	void	read

int
pthread_rwlock_setname_np (
pthread_rwlock_t *rwlock,
const char *name,
void *mbz);

Arguments

rwlock

Address of the read-write lock object whose object name is to be changed.

name

Object name value to copy into the read-write lock object.

mbz

Reserved for future use. The value must be zero (0).

Description

This routine changes the object name in the read-write lock object specified by rwlock to the value specified by name. To set a new read-write lock object's object name, call this routine immediately after initializing the read-write lock object.

The object name is a C language string and provides an identifier that is meaningful to a person debugging a multithreaded application. The maximum number of characters in the object name is 31.

Associated Routines

pthread_rwlock_getname_np()
pthread_rwlock_init()