NAME

tis, tis_intro − Introduction to Thread-Independent Services (tis)

DESCRIPTION

Thread-independent services (tis) routines compose a Compaq-proprietary interface to the DECthreads multitasking library.  The tis interface provides services that assist with the development of thread-safe libraries. 

Thread synchronization can involve significant run-time cost, which is undesirable in a nonthreaded environment.  In the nonthreaded environment, the tis interface enables you to build thread-safe libraries that are efficient, yet provide the necessary synchronization when called from a threaded environment. 

When threads are not active within the process, tis routines execute only the minimum steps necessary: code running in a nonthreaded environment is not burdened by the run-time synchronization that is necessary when the same code is run in a threaded environment.  When threads are active, tis routines provide the necessary thread-safe synchronization. 

The tis objects created using this interface are fully interchangeable with DECthreads Pthreads (POSIX 1003.1c) objects.  So, a mutex can be created by using static initialization (or using tis_mutex_init(3)) and can be locked, the DECthreads core library (libpthread.so) subsequently activated, and the mutex unlocked.  Keys created by tis_key_create(3) are valid when a threaded run-time environment is loaded. 

Note that errno is NOT used by the tis routines.  To indicate errors, the tis routines return integer values indicating the type of error. 

In a nonthreaded environment, condition variables should not be used to guard operations (for example, with tis_cond_wait(3)).  In a threaded environment, the guidelines for using the DECthreads Pthread routines also pertain to the use of the corresponding tis routine. 

The tis routines can be classified into the following associated groups:

       •General routines

       •Thread cancellation routines

       •Thread-specific data key routines

       •Mutex routines

       •Condition variable routines

       •Read-write lock routines

General Routines

tis_get_expirationObtains a value representing a desired expiration time. 

tis_onceCalls a one-time initialization routine that can be executed. 

tis_selfObtains the identifier of the calling thread. 

Thread Cancellation Routines

tis_setcancelstateChanges the calling thread’s cancelability state. 

tis_testcancelCreates a cancellation point in the calling thread. 

Thread-Specific Data Key Routines

tis_getspecificObtains the data associated with the specified thread-specific data key. 

tis_key_createGenerates a unique thread-specific data key. 

tis_key_deleteDeletes a thread-specific data key. 

tis_setspecificSets the value associated with the specified thread-specific key. 

Mutex Routines

tis_lock_globalLocks the DECthreads global mutex. 

tis_mutex_destroyDestroys the specified tis mutex object. 

tis_mutex_initInitializes a tis mutex object. 

tis_mutex_lockLocks the specified tis mutex if not already locked. 

tis_mutex_trylockTries to lock the specified tis mutex. 

tis_mutex_unlockUnlocks the specified tis mutex. 

tis_unlock_globalUnlocks the DECthreads global mutex. 

Condition Variable Routines

tis_cond_broadcastWakes all threads waiting on the specified condition variable. 

tis_cond_destroyDestroys the specified condition variable object. 

tis_cond_initInitializes a condition variable object. 

tis_cond_signalWakes at least one thread that is waiting on the specified condition variable. 

tis_cond_timedwaitCauses the calling thread to wait for the specified condition variable to be signaled or broadcast, such that it will awake after a specified period of time. 

tis_cond_waitCauses the calling thread to wait for the specified condition variable to be signaled or broadcast. 

Read-Write Lock Routines

tis_read_lockAcquires the specified read-write lock for read access. 

tis_read_trylockAttempts to acquire the specified read-write lock for read access; returns immediately if already locked. 

tis_read_unlockUnlocks the specified read-write lock already acquired for read access. 

tis_rwlock_destroyDestroys the specified read-write lock object. 

tis_rwlock_initInitializes a read-write lock object. 

tis_write_lockAcquires the specified read-write lock for write access. 

tis_write_trylockAttempts to acquire the specified read-write lock for write access; returns immediately if already locked. 

tis_write_unlockUnlocks the specified read-write lock already acquired for write access.