Guide to DECthreads

Associated Routines

• tis_cond_broadcast()
• tis_cond_destroy()
• tis_cond_init()
• tis_cond_signal()

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

Syntax

tis_getspecific(
key );

Argument	Data Type	Access
key	opaque pthread_key_t	read

void *
tis_getspecific (
pthread_key_t key);

ARGUMENTS

key

Identifies a value returned by a call to tis_key_create(). This routine returns the data value associated with the thread-specific data key.

DESCRIPTION

This routine returns the value currently bound to the specified thread-specific data key.

This routine can be called from a data destructor function.

When threads are present, the data and keys are thread specific; they enable a library to maintain context on a per-thread basis.

Associated Routines

• tis_key_create()
• tis_key_delete()
• tis_setspecific()

Generates a unique thread-specific data key.

Syntax

tis_key_create(
key ,
destructor );

Argument	Data Type	Access
key	opaque pthread_key_t	write
destructor	procedure	read

int
tis_key_create (
pthread_key_t *key,
void (*destructor)(void *));

ARGUMENTS

key

Address of a variable that receives the key value. This value is used in calls to tis_getspecific() and tis_setspecific() to get and set the value associated with this key.

destructor

Address of a routine that is called to destroy the context value when a thread terminates with a non-NULL value for the key. Note that this argument is used only when threads are present.

DESCRIPTION

This routine generates a unique thread-specific data key. The key argument points to an opaque object used to locate data.

This routine generates and returns a new key value. The key reserves a cell. Each call to this routine creates a new cell that is unique within an application invocation. Keys must be generated from initialization code that is guaranteed to be called only once within each process. (See the tis_once() description for more information.)

Your program can associate an optional destructor function with each key. At thread exit, if a key has a non-NULL destructor function pointer, and the thread has a non-NULL value associated with that key, the function pointed to is called with the current associated value as its sole argument. The order in which data destructors are called at thread termination is undefined.

When threads are present, keys and any corresponding data are thread specific; they enable the context to be maintained on a per-thread basis. For more information about the use of tis_key_create() in a threaded environment, refer to the pthread_key_create() description.

DECthreads imposes a maximum number of thread-specific data keys, equal to the symbolic constant PTHREAD_KEYS_MAX.

Associated Routines

• tis_getspecific()
• tis_key_delete()
• tis_setspecific()
• tis_once()

Deletes the specified thread-specific data key.

Syntax

tis_key_delete(
key );

Argument	Data Type	Access
key	opaque pthread_key_t	write

int
tis_key_delete (
pthread_key_t key);

ARGUMENTS

key

Thread-specific data key to be deleted.

DESCRIPTION

This routine deletes a thread-specific data key key previously returned by a call to the tis_key_create() routine. The data values associated with key need not be NULL at the time this routine is called. The application must free any application storage or perform any cleanup actions for data structures related to the deleted key or associated data. This cleanup can be done before or after this routine is called.

Attempting to use the thread-specific data key key after calling this routine results in unpredictable behavior.

No destructor functions are invoked by this routine. Any destructor functions that may have been associated with key will no longer be called upon thread exit.

This routine can be called from destructor functions.

Associated Routines

• tis_getspecific()
• tis_key_create()
• tis_setspecific()

Locks the DECthreads global mutex.

Syntax

tis_lock_global( );

int
tis_lock_global (void);

ARGUMENTS

None

DESCRIPTION

This routine locks the DECthreads global mutex. The global mutex is recursive. For example, if you 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_lock_global_np() description.

Associated Routines

• tis_unlock_global()

Destroys the specified mutex object.

Syntax

tis_mutex_destroy(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	write

int
tis_mutex_destroy (
pthread_mutex_t *mutex);

ARGUMENTS

mutex

Address of the mutex object (passed by reference) to be destroyed.

DESCRIPTION

This routine destroys a mutex object by uninitializing it, and should be called when a mutex object is no longer referenced. After this routine is called, DECthreads can reclaim internal storage used by the mutex object.

It is safe to destroy an initialized mutex object that is unlocked. However, it is illegal to destroy a locked mutex object.

The results of this routine are unpredictable if the mutex object specified in the mutex argument does not currently exist or is not initialized.

Associated Routines

• tis_mutex_init()
• tis_mutex_lock()
• tis_mutex_trylock()
• tis_mutex_unlock()

Initializes the specified mutex object.

Syntax

tis_mutex_init(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	write

int
tis_mutex_init (
pthread_mutex_t *mutex );

ARGUMENTS

mutex

Pointer to a mutex object (passed by reference) to be initialized.

DESCRIPTION

This routine initializes a mutex object with the DECthreads default mutex attributes. A mutex is a synchronization object that allows multiple threads to serialize their access to shared data.

The mutex object is initialized and set to the unlocked state. Mutexes can be allocated in heap or static memory, but not on a stack.

Your program can use the PTHREAD_MUTEX_INITIALIZER macro to statically initialize a mutex object without calling this routine. Statically initialized mutexes need not be destroyed using tis_mutex_destroy(). Use this macro as follows:
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;

Associated Routines

• tis_mutex_destroy()
• tis_mutex_lock()
• tis_mutex_trylock()
• tis_mutex_unlock()

Locks an unlocked mutex.

Syntax

tis_mutex_lock(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	read

int
tis_mutex_lock (
pthread_mutex_t *mutex);

ARGUMENTS

mutex

Address of the mutex (passed by reference) to be locked.

DESCRIPTION

This routine locks the specified mutex mutex. A deadlock can result if the owner of a mutex calls this routine in an attempt to lock the same mutex a second time. (DECthreads does not detect or report the deadlock.)

In a threaded environment, the thread that has locked a mutex becomes its current owner and remains the owner until the same thread has unlocked it. This routine returns with the mutex in the locked state and with the current thread as the mutex's current owner.

Associated Routines

• tis_mutex_destroy()
• tis_mutex_init()
• tis_mutex_trylock()
• tis_mutex_unlock()

Attempts to lock the specified mutex.

Syntax

tis_mutex_trylock(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	read

int
tis_mutex_trylock (
pthread_mutex_t *mutex);

ARGUMENTS

mutex

Address of the mutex (passed by reference) to be locked.

DESCRIPTION

This routine attempts to lock the specified mutex mutex. When this routine is called, an attempt is made immediately to lock the mutex. If the mutex is successfully locked, zero (0) is returned.

If the specified mutex is already locked when this routine is called, the caller does not wait for the mutex to become available. [EBUSY] is returned, and the thread does not wait to acquire the lock.

Associated Routines

• tis_mutex_destroy()
• tis_mutex_init()
• tis_mutex_lock()
• tis_mutex_unlock()

Unlocks the specified mutex.

Syntax

tis_mutex_unlock(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	read

int
tis_mutex_unlock (
pthread_mutex_t *mutex);

ARGUMENTS

mutex

Address of the mutex (passed by reference) to be unlocked.

DESCRIPTION

This routine unlocks the specified mutex mutex.

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

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:

Return	Description
0	Successful completion.
[EINVAL]	The value specified by mutex is invalid.
[EPERM]	The caller does not own the mutex.

Associated Routines

• tis_mutex_destroy()
• tis_mutex_init()
• tis_mutex_lock()
• tis_mutex_trylock()

Calls a one-time initialization routine that can be executed by only one thread, once.

Syntax

tis_once(
once _control,
init _routine );

Argument	Data Type	Access
once_control	opaque pthread_once_t	modify
init_routine	procedure	read

int
tis_once (
pthread_once_t *once_control,
void (*init_routine) (void));

ARGUMENTS

once_control

Address of a record (control block) that defines the one-time initialization code. Each one-time initialization routine in static storage must have its own unique pthread_once_t record.

init_routine

Address of a procedure that performs the initialization. This routine is called only once, regardless of the number of times it and its associated once_control are passed to tis_once().

DESCRIPTION

The first call to this routine by a process with a given once_control calls the init_routine with no arguments. Thereafter, subsequent calls to tis_once() with the same once_control do not call the init_routine. On return from tis_once(), it is guaranteed that the initialization routine has completed.

For example, a mutex or a thread-specific data key must be created exactly once. In a threaded environment, calling tis_once() ensures that the initialization is serialized across multiple threads.

The once_control argument must be statically initialized using the PTHREAD_ONCE_INIT macro or by zeroing out the entire structure.

---

Note

If you specify an init_routine that directly or indirectly results in a recursive call to tis_once() and that specifies the same init_block argument, the recursive call results in a deadlock.

---

The PTHREAD_ONCE_INIT macro, defined in the pthread.h header file, must be used to initialize a once_control record. Thus, your program must declare a once_control record as follows:

pthread_once_t  once_control = PTHREAD_ONCE_INIT; 

Note that it is often easier to simply lock a statically initialized mutex, check a control flag, and perform necessary initialization (in-line) rather than using tis_once(). For example, you can code an "init" routine that begins with the following basic logic:

  init() 
  { 
   static pthread_mutex_t    mutex = PTHREAD_MUTEX_INIT; 
   static int                flag = FALSE; 
   
   tis_mutex_lock(&mutex); 
   if(!flag) 
     { 
      flag = TRUE; 
      /* initialize code */ 
     } 
   tis_mutex_unlock(&mutex); 
  } 
   

Acquires a read-write lock for read access.

Syntax

tis_read_lock(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

int
tis_read_lock (
tis_rwlock_t *lock);

ARGUMENTS

lock

Address of the read-write lock.

DESCRIPTION

This routine acquires a read-write lock for read access. This routine waits for any existing lock holder for write access to relinquish its lock before granting the lock for read access. This routine returns when the lock is acquired. If the lock is already held for read access, the lock is granted.

For each call to tis_read_lock() that successfully acquires the lock for read access, a corresponding call to tis_read_unlock() must be issued.

Note that the type tis_rwlock_p is a pointer to type tis_rwlock_t.

Associated Routines

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

Attempts to acquire a read-write lock for read access. Does not wait if the lock cannot be immediately granted.

Syntax

tis_read_trylock(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

int
tis_read_trylock (
tis_rwlock_t *lock);

ARGUMENTS

lock

Address of the read-write lock to be acquired.

DESCRIPTION

This routine attempts to acquire a read-write lock for read access. If the lock cannot be granted, the routine returns without waiting.

When a thread calls this routine, an attempt is made to immediately acquire the lock for read access. If the lock is acquired, zero (0) is returned. If a holder of the lock for write access exists, [EBUSY] is returned.

If the lock cannot be acquired for read access immediately, the calling program does not wait for the lock to be released.

Associated Routines

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

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

Syntax

tis_read_unlock(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write

int
tis_read_unlock (
tis_rwlock_t *lock);

ARGUMENTS

lock

Address of the read-write lock to be unlocked.

DESCRIPTION

This routine unlocks a read-write lock that was acquired for read access. If there are no other holders of the lock for read access and another thread is waiting to acquire the lock for write access, that lock acquisition is granted.

Associated Routines

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

Destroys the specified read-write lock object.

Syntax

tis_rwlock_destroy(
lock );

Argument	Data Type	Access
lock	opaque tis_rwlock_t	write