1.7 tis Routines Summary

Thread-independent services (tis) routines comprise a Digital proprietary interface of DECthreads. 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 in the threaded environment.

When DECthreads is not active within the process, tis executes 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 DECthreads is active, the tis functions provide the necessary thread-safe synchronization.

In a nonthreaded environment, condition variables should not be used to block operations (for example, with tis_cond_wait). In a threaded environment, the guidelines for using the pthread routines also apply to the use of the corresponding tis routine.

The tis routines can be classified into the following functional categories:

• General Routines

• Mutex Routines

• Condition Variable Routines

• Key Context Routines

• Cancellation Routines

• Readers/Writers Locks

Table 1-2 summarizies these groups of tis routines.

Table 1-2 DECthreads Routines Summary

       General tis Routines

Routine                                 Description

tis_once              Calls a one-time initialization routine that
                      can be executed.

tis_raise             Sends a signal to the thread that called tis_
                      raise.

tis_self              Obtains the identifier of the current thread.

        Mutex Routines

Routine                                 Description

tis_lock_global       Locks a global tis mutex.

tis_mutex_destroy     Destroys a tis mutex.

tis_mutex_init        Initializes a tis mutex.

tis_mutex_lock        Locks an unlocked mutex.

tis_mutex_trylock     Tries to lock a mutex.

tis_mutex_unlock      Unlocks a tis mutex.

tis_unlock_global     Unlocks a global mutex.

       Condition Variable Routines

Routine                                 Description

tis_cond_broadcast    Wakes all threads waiting on a condition
                      variable.

tis_cond_destroy      Destroys a condition variable.

tis_cond_init         Initializes a condition variable.

tis_cond_signal       Wakes at least one thread that is waiting on a
                      condition variable.

tis_cond_wait         Causes a thread to wait for a condition
                      variable to be signaled or broadcasted.

       Key Context Routines

Routine                                 Description

tis_getspecific       Obtains the data associated with the specified
                      key.

tis_key_create        Generates a unique data key.

tis_key_delete        Deletes a data key.

tis_setspecific       Sets the data value associated with the
                      specified key.

       Thread Cancellation Routines

Routine                                 Description

tis_setcancelstate    Sets the current thread's cancelability state.

tis_testcancel        Creates a cancellation point in the current
                      thread.

                        Readers/Writers Locks
tis_read_lock         Acquires a read lock.

tis_read_trylock      Acquires a read lock; returns immediately if
                      already locked.

tis_read_unlock       Unlocks a read lock.

tis_rwlock_destroy    Destroys a readers/writers lock.

tis_rwlock_init       Initializes a readers/writers lock.

tis_write_lock        Acquires a write lock.

tis_write_trylock     Acquires a write lock; returns immediately if
                      already locked.

tis_write_unlock      Unlocks a write lock.