![]() |
Software > OpenVMS Systems > Documentation > 72final > 6493 ![]() HP OpenVMS Systems Documentation |
![]() |
Guide to DECthreads
tis_rwlock_init
Initializes a read-write lock object. Syntax
C Binding#include <tis.h>int tis_rwlock_init ( tis_rwlock_t *lock); Arguments
DescriptionThis routine initializes a read-write lock object. The routine initializes the tis_rwlock_t structure that holds the object's lock states. Return ValuesIf an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Associated Routines
tis_self
Returns the identifier of the calling thread. Syntax
C Binding#include <tis.h>pthread_t tis_self (void); ArgumentsNone DescriptionThis routine allows a thread to obtain its own thread identifier. Return ValuesReturns the thread identifier of the calling thread.Associated Routines
tis_setcancelstate
Changes the calling thread's cancelability state. Syntax
C Binding#include <tis.h>int tis_setcancelstate ( int state, int *oldstate ); Arguments
DescriptionThis 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. Return ValuesOn successful completion, this routine returns the calling thread's previous cancelability state in the oldstate argument.If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Associated Routines
tis_setspecific
Changes the value associated with the specified thread-specific data key. Syntax
C Binding#include <tis.h>int tis_setspecific ( pthread_key_t key, const void *value); Arguments
DescriptionThis 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().
Return ValuesIf an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows:
Associated Routines
tis_testcancel
Creates a cancelation point in the calling thread. Syntax
C Binding#include <tis.h>void tis_testcancel (void); ArgumentsNone DescriptionThis 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().) Return ValuesNoneAssociated Routines
tis_unlock_global
Unlocks the DECthreads global mutex. Syntax
C Binding#include <tis.h>int tis_unlock_global (void); ArgumentsNone DescriptionThis 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. Return ValuesIf an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Associated Routines
tis_write_lock
Acquires a read-write lock for write access. Syntax
C Binding#include <tis.h>int tis_rwlock ( tis_rwlock_t *lock); Arguments
DescriptionThis 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. Return ValuesIf an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Associated Routines
tis_write_trylock
Attempts to acquire a read-write lock for write access. Syntax
C Binding#include <tis.h>int tis_write_trylock ( tis_rwlock_t *lock); Arguments
DescriptionThis 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. Return ValuesIf an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:
Associated Routines
tis_write_unlock
Unlocks a read-write lock that was acquired for write access. Syntax
C Binding#include <tis.h>int tis_write_unlock ( tis_rwlock_t *lock); Arguments
DescriptionThis routine unlocks a read-write lock that was acquired for write access. Return ValuesIf an error condition occurs, this routine returns an integer value indicating the type error. Possible return values are as follows:
Associated Routines
Part 4
Part 4 contains appendixes that provide supporting information
about DECthreads, such as operating system-specific information,
debugging information, and additional reference information.
|
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.
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.
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.
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 |
If you build software (whether applications or libraries) that links against the static version of a DECthreads library, you must not require developers who use your software to link against any library that dynamically loads any DECthreads shared library, such as libpthread.so. |
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).
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).
Previous | Next | Contents | Index |