Document revision date: 19 July 1999

Initializes a read-write lock object.

Syntax

tis_rwlock_init(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

C Binding

Arguments

lock

Address of a read-write lock object.

Description

This routine initializes a read-write lock object. The routine initializes the tis_rwlock_t structure that holds the object's lock states.

To destroy a read-write lock object, call the tis_rwlock_destroy() routine.

Return Values

Associated Routines

• tis_read_lock()
• tis_read_trylock()
• tis_read_unlock()
• tis_rwlock_destroy()
• tis_write_lock()
• tis_write_trylock()
• tis_write_unlock()

Returns the identifier of the calling thread.

Syntax

tis_self(
void);

C Binding

Arguments

None

Description

This routine allows a thread to obtain its own thread identifier.

This value becomes meaningless when the thread is destroyed.

Note that the initial thread in a process can "change identity" when thread system initialization completes---that is, when the DECthreads multithreading run-time environment is loaded.

Return Values

Associated Routines

• pthread_create()

Changes the calling thread's cancelability state.

Syntax

tis_setcancelstate(
state ,
oldstate );

Argument	Data Type	Access
state	integer	read
oldstate	integer	write

C Binding

Arguments

state

State of general cancelability to set for the calling thread. Valid state values are as follows:

• PTHREAD_CANCEL_ENABLE
• PTHREAD_CANCEL_DISABLE

oldstate

Receives the value of the calling thread's previous cancelability state.

Description

This routine sets the calling thread's cancelability state to the value specified in the state argument and returns the calling thread's previous cancelability state in the location referenced by the oldstate argument.

When the a thread's 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 is enabled.

When a thread is created, its default cancelability state is PTHREAD_CANCEL_ENABLE. When this routine is called prior to loading threads, the cancelability state propagates to the initial thread in the executing program.

Possible Problems When Disabling Cancelability

The most important use of a cancelation request is to ensure that indefinite wait operations are terminated. For example, a thread waiting on some network connection, which might take days to respond (or might never respond), should be made cancelable.

When a thread's cancelability state is disabled, no routine called within that thread is cancelable. As a result, the user is unable to cancel the operation. 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

Associated Routines

• tis_testcancel()

Changes the value associated with the specified thread-specific data key.

Syntax

tis_setspecific(
key ,
value );

Argument	Data Type	Access
key	opaque pthread_key_t	read
value	void *	read

C Binding

Arguments

key

Thread-specific data key that identifies the data to receive value. Must be obtained from a call to tis_key_create().

value

New value to associate with the specified key. Once set, this value can be retrieved using the same key in a call to tis_getspecific().

Description

This routine sets the value associated with the specified thread-specific data key. If a value is defined for the key (that is, the current value is not NULL), the new value is substituted for it. The key is obtained by a previous call to tis_key_create().

Do not call this routine from a data destructor function.

Return Values

Associated Routines

• tis_getspecific()
• tis_key_create()
• tis_key_delete()

Creates a cancelation point in the calling thread.

Syntax

tis_testcancel( );

C Binding

Arguments

None

Description

This routine requests delivery of a pending cancelation request to the calling thread. Thus, this routine creates a cancelation point in the calling thread. The cancelation request is delivered only if a request is pending for the calling thread and the calling thread's cancelability state is enabled. (A thread disables delivery of cancelation requests to itself by calling tis_setcancelstate().)

This routine, when called within very long loops, ensures that a pending cancelation request is noticed within a reasonable amount of time.

Return Values

Associated Routines

• tis_setcancelstate()

Unlocks the DECthreads global mutex.

Syntax

tis_unlock_global( );

C Binding

Arguments

None

Description

This routine unlocks the DECthreads global mutex. Because the global mutex is recursive, the unlock occurs when each call to tis_lock_global() has been matched by a call to this routine. For example, if your program called tis_lock_global() three times, tis_unlock_global() unlocks the global mutex when you call it the third time.

For more information about actions taken when threads are present, refer to the pthread_unlock_global_np() description.

Return Values

Associated Routines

• tis_lock_global()

Acquires a read-write lock for write access.

Syntax

tis_write_lock(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

C Binding

Arguments

lock

Address of the read-write lock to be acquired for write access.

Description

This routine acquires a read-write lock for write access. This routine waits for any other active locks (for either read or write access) to be unlocked before this acquisition request is granted.

This routine returns when the specified read-write lock is acquired for write access.

Return Values

Associated Routines

• tis_read_lock()
• tis_read_trylock()
• tis_read_unlock()
• tis_rwlock_destroy()
• tis_rwlock_init()
• tis_write_trylock()
• tis_write_unlock()

Attempts to acquire a read-write lock for write access.

Syntax

tis_write_trylock(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

C Binding

Arguments

lock

Address of the read-write lock to be acquired for write access.

Description

This routine attempts to acquire a read-write lock for write access. The routine attempts to immediately acquire the lock. If the lock is acquired, zero (0) is returned. If the lock is held by another thread (for either read or write access), [EBUSY] is returned and the calling thread does not wait for the write-access lock to be acquired.

Note that it is a coding error to attempt to acquire the lock for write access if the lock is already held by the calling thread. (However, this routine returns [EBUSY] anyway, because no ownership error-checking takes place.)

Return Values

Associated Routines

• tis_read_lock()
• tis_read_trylock()
• tis_read_unlock()
• tis_rwlock_destroy()
• tis_rwlock_init()
• tis_write_lock()
• tis_write_unlock()

Unlocks a read-write lock that was acquired for write access.

Syntax

tis_write_unlock(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

C Binding

Arguments

lock

Address of the read-write lock to be unlocked.

Description

This routine unlocks a read-write lock that was acquired for write access.

Upon completion of this routine, any thread waiting to acquire the lock for read access will have those acquisitions granted. If no threads are waiting to acquire the lock for read access, then a thread waiting to acquire it for write access will have that acquisition granted.

Return Values

Associated Routines

• tis_read_lock()
• tis_read_trylock()
• tis_read_unlock()
• tis_rwlock_init()
• tis_rwlock_destroy()
• tis_write_lock()
• tis_write_trylock()

This appendix discusses DECthreads issues specific to DIGITAL UNIX systems.

A.1 Overview

The DIGITAL UNIX operating system supports multiple concurrent "execution contexts" within a process. DECthreads uses these kernel execution contexts to implement user threads. One important benefit of this is that user threads can run simultaneously on separate processors in a multiprocessor system. Review Section 3.1 for tips for ensuring that your application will work correctly with kernel threads and multiprocessing.

A.2 Building DECthreads Applications

The following sections discuss points to consider when building using DECthreads.

A.2.1 Including DECthreads Header Files

Include one of the DECthreads header files shown in Table A-1 in your program to use the appropriate DECthreads library.

Table A-1 DECthreads Header Files

Header File	Interface
pthread.h	POSIX.1c routines
tis.h	Thread-independent services routines

Do not include more than one of these header files in your module.

A.2.2 Building Multithreaded Applications from DECthreads Libraries

Multithreaded applications are built using shared libraries. For a description of shared libraries, see the DIGITAL UNIX Programmer's Guide.

Table A-2 contains the libraries supported for multithreaded programming.

Table A-2 DIGITAL UNIX Shared Libraries for Multithreaded Programs

libmach.so	Shared version of threads support library. Direct use of mach interfaces is not supported.
libpthread.so	Shared version of the base pthreads package. Requires libmach.so, libexc.so, and libc.so
libexc.so	Shared version of DIGITAL UNIX exception support package.
libpthreads.so	Shared version of DECthreads "legacy" package, implementing the Compaq-proprietary CMA (or cma) and POSIX 1003.4a/Draft 4 (or d4) interfaces.
libc.so	Shared version of the C language run-time library ( libc.so).

Build a multithreaded application using shared versions of libexc, libmach, libpthread, and libc using this command:

% cc -o myprog myprog.c -pthread

If you use a compiler front-end or other (not C) language environment that does not support the -pthread compilation switch, you must use the -D_REENTRANT compilation switch.

A.2.3 Linking Multithreaded Shared Libraries

The ld command does not support the -pthread or -threads switch. Instead, you must list the individual libraries in the proper order.

For libraries that use only the pthread interface, use the following:

ld <...> -lpthread -lexc

If using the cma or d4 interfaces, use the following:

ld <...> -lpthreads -lpthread -lexc

Applications that use the Compaq-proprietary thread-independent services (or tis) interface should include the tis.h header file and link against the shared C run-time library (libc.so).

A.3 Two-Level Scheduling on DIGITAL UNIX Systems

Under DIGITAL UNIX Version 4.0 and later, DECthreads implements a new scheduling model, referred to as two-level scheduling. DECthreads schedules "user threads" onto kernel execution contexts (often known as "kernel threads" or "virtual processors"), just as DIGITAL UNIX schedules processes onto the processors of a multiprocessing machine.

A user thread is executed on a kernel thread until it blocks or exhausts its timeslice quantum. Then, DECthreads schedules a new user thread to run. While DECthreads is scheduling user threads onto kernel threads, the DIGITAL UNIX kernel is independently scheduling those kernel threads to run on physical processors. The term two-level scheduling refers to this relationship.

This division allows most thread scheduling to take place completely in user mode, without the intervention of the kernel. Since a thread context switch does not involve any privileged information, it can be done much more efficiently in user mode.

The key to making the two-level scheduling model work is efficient two-way communication between DECthreads and the DIGITAL UNIX kernel. When a thread blocks in the kernel, the DECthreads scheduler is notified so that it can schedule another thread to take advantage of the idle kernel thread. This mechanism, sometimes referred to as an upcall, is inspired by original research on scheduler activations at the University of Washington. (See Scheduler Activations: Effective Kernel Support for the User-Level Management of Parallelism by Anderson, Bershad, Lazowska, and Levy; ACM Operating Systems Review Volume 25, Number 5, Proceedings of the Thirteenth ACM Symposium on Operating Systems Principles, October 13-16, 1991).

	privacy and legal statement
6101PRO_028.HTML