Updated: 11 December 1998

Guide to DECthreads

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

This routine is for DIGITAL UNIX systems only.

Syntax

pthread_rwlockattr_getpshared(
attr ,
pshared );

Argument	Data Type	Access
attr	opaque pthread_rwlockattr_t	read
pshared	int	write

C Binding

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.

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.

Return Values

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

C Binding

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.

Return Values

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 DIGITAL UNIX systems only.

Syntax

pthread_rwlockattr_setpshared(
attr ,
pshared );

Argument	Data Type	Access
attr	opaque pthread_rwlockattr_t	write
pshared	int	read

C Binding

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.

Return Values

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

C Binding

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, DECthreads 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.

Results are undefined after an attempt to destroy an uninitialized read-write lock object. Results are undefined if this routine is called when any thread holds rwlock.

Return Values

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

C Binding

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 based on DECthreads. 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.

Return Values

Associated Routines

• pthread_rwlock_setname_np()

Initializes a read-write lock object with attributes specified by a read-write lock attributes object.

Syntax

pthread_rwlock_init(
rwlock ,
attr );

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

C Binding

Arguments

rwlock

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

attr

Address of the read-write lock attributes object to use to initialize the object rwlock.

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, 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_trwlock= PTHREAD_RWLOCK_INITIALIZER

Return Values

Associated Routines

• pthread_rwlock_destroy()

Acquires, after waiting if necessary, a read-write lock object for read access.

Syntax

pthread_rwlock_rdlock(
rwlock );

Argument	Data Type	Access
rwlock	opaque pthread_rwlock_t	write

C Binding

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 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.

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 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 DIGITAL UNIX signal or an OpenVMS AST) while waiting for a read-write lock for read access, upon return from the signal handler the thread resumes waiting for the lock as if it had not been interrupted.

Return Values

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

C Binding

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

(Must be zero) For use by DECthreads.

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 based on DECthreads. The maximum number of characters in the object name is 31.

Return Values

Associated Routines

• pthread_rwlock_getname_np()
• pthread_rwlock_init()

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6101PRO_023.HTML