Guide to DECthreads

These routines are designed to provide efficient tools for thread safety in libraries whose routines do not themselves use threads. The tis interface provides functions identical to several pthread functions. In a program that creates or uses threads, the tis functions provide full thread synchronization and coherence of memory access. But, in a program that does not use threads, the same tis calls provide low-overhead "stub" implementations of pthread features.

The objects created using tis interface routines are the same as pthread interface objects.

The variable errno is not used by the tis routines. Like the pthread routines, the tis routines return integer values indicating the type of error.

Note

In a nonthreaded environment, never code tis routines to use condition variables to block operations. For example, the single-threaded implementation of tis_cond_wait() cannot block. If it did, no other thread would be running to "awaken" the program.

When threads are present, the guidelines for using pthread routines apply to using the corresponding tis routines.

Wakes all threads that are waiting on a condition variable.

Syntax

tis_cond_broadcast(
cond );

Argument	Data Type	Access
cond	opaque pthread_cond_t	modify

int
tis_cond_broadcast (
pthread_cond_t *cond);

ARGUMENTS

cond

Address of the condition variable (passed by reference) on which to broadcast.

DESCRIPTION

When threads are not present, tis_cond_broadcast() performs no actions.

When threads are present, tis_cond_broadcast() unblocks all threads waiting on the specified condition variable cond. For further information about actions when threads are present, refer to the pthread_cond_broadcast() description.

Associated Routines

• tis_cond_destroy()
• tis_cond_init()
• tis_cond_signal()
• tis_cond_wait()

Destroys a condition variable.

Syntax

tis_cond_destroy(
cond );

Argument	Data Type	Access
cond	opaque pthread_cond_t	write

int
tis_cond_destroy (
pthread_cond_t *cond);

ARGUMENTS

cond

Address of the condition variable (passed by reference) to be destroyed.

DESCRIPTION

This routine destroys the condition variable specified by cond. After this routine is called, DECthreads may reclaim internal storage used by the condition variable object. Call this routine when a condition variable will no longer be referenced.

The results of this routine are unpredictable, if the condition variable specified in cond does not exist or is not initialized.

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

Associated Routines

• tis_cond_broadcast()
• tis_cond_init()
• tis_cond_signal()
• tis_cond_wait()

Initializes a condition variable.

Syntax

tis_cond_init(
cond );

Argument	Data Type	Access
cond	opaque pthread_cond_t	write

int
tis_cond_init (
pthread_cond_t *cond);

ARGUMENTS

cond

Address of the condition variable (passed by reference) to be initialized.

DESCRIPTION

This routine initializes a condition variable (cond) with the DECthreads default condition variable attributes.

A condition variable is a synchronization object used in conjunction with a mutex. A mutex controls access to shared data. When threads are present, a condition variable allows threads to wait for data to enter a defined state.

For further information about actions when threads are present, refer to the pthread_cond_init() description.

Your program can use the macro PTHREAD_COND_INITIALIZER to initialize statically allocated condition variables to the default condition variable attributes. Use this macro as follows:
pthread_cond_t condition = PTHREAD_COND_INITIALIZER;

When statically initialized, a condition variable should not also be initialized using tis_cond_init(). Also, a statically initialized condition variable need not be destroyed using tis_cond_destroy().

• The routine returns an integer value indicating the type of error.
• The condition variable is not initialized.
• The contents of conditon variable (cond) are undefined.

The possible return values are as follows:

Return	Description
0	Successful completion.
[EAGAIN]	The system lacks the necessary resources to initialize another condition variable, or: The system-imposed limit on the total number of condition variables under execution by a single user is exceeded.
[EBUSY]	The implementation has detected an attempt to reinitialize the object referenced by cond, a previously initialized, but not yet destroyed condition variable.
[EINVAL]	The value specified by attr is invalid.
[ENOMEM]	Insufficient memory exists to initialize the condition variable.

Associated Routines

• tis_cond_broadcast()
• tis_cond_destroy()
• tis_cond_signal()
• tis_cond_wait()

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

Syntax

tis_cond_signal(
cond );

Argument	Data Type	Access
cond	opaque pthread_cond_t	modify

int
tis_cond_signal (
pthread_cond_t *cond);

ARGUMENTS

cond

Address of the condition variable (passed by reference) on which to signal.

DESCRIPTION

When threads are present, this routine unblocks at least one thread waiting on the specified condition variable cond.

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

Associated Routines

• tis_cond_broadcast()
• tis_cond_destroy()
• tis_cond_init()
• tis_cond_wait()

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

Syntax

tis_cond_wait(
cond ,
mutex );

Argument	Data Type	Access
cond	opaque pthread_cond_t	modify
mutex	opaque pthread_mutex_t	modify

int
tis_cond_wait (
pthread_cond_t *cond,
pthread_mutex_t *mutex);

ARGUMENTS

cond

Address of the condition variable (passed by reference) on which to wait.

mutex

Address of the mutex (passed by reference) which is associated with the condition variable specified in cond.

DESCRIPTION

When threads are present, this routine causes a thread to wait for a condition variable to be signaled or broadcasted.

Calling this routine in a nonthreaded environment is a coding error. Because no thread can execute in parallel to issue a tis_cond_signal() or tis_cond_broadcast(), using this routine in a single-threaded environment forces the program to exit.

For further information about actions when threads are present, refer to the pthread_cond_wait() 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 cond or mutex is invalid, or: Different mutexes are supplied for concurrent tis_cond_wait() operations on the same condition variable, or: The mutex was not owned by the current thread at the time of the call.

Associated Routines

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

Obtains the data associated with the specified key.

Syntax

tis_getspecific(
key );

Argument	Data Type	Access
key	opaque pthread_key_t	read

void *
tis_getspecific (
pthread_key_t key);

ARGUMENTS

key

key identifies a value returned by a call to tis_key_create(). This routine returns the data value associated with the key.

DESCRIPTION

This routine returns the value currently bound to the specified key.

This routine may 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 will receive 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 only used when threads are present.

DESCRIPTION

This routine generates a unique thread-specific data key. The variable key provided by this routine is 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.)

An optional destructor function may be associated 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 concerning 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 a 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

Context key to be deleted.

DESCRIPTION

This routine deletes a thread-specific data key key previously returned by tis_key_create(). 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 call.

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, shall 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 when threads are present, refer to the pthread_lock_global_np() description.

Associated Routines

• tis_unlock_global()

Destroys a mutex.

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 (passed by reference) to be destroyed.

DESCRIPTION

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

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

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 a mutex.

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 (passed by reference) that is initialized.

DESCRIPTION

This routine initializes a mutex 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 is initialized and set to the unlocked state. Mutexes can be allocated in heap or static memory, but not on a stack.

The PTHREAD_MUTEX_INITIALIZER macro can be used to statically initialize a mutex 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_lock()
• tis_mutex_trylock()
• tis_mutex_unlock()
• tis_mutex_destroy()

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 a mutex. A deadlock can result if the owner of a mutex calls this routine in an attempt to lock the mutex a second time. (The deadlock is not detected or reported.)

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 a mutex.

Syntax

tis_mutex_trylock(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	read

  6493P013.HTM
  OSSG Documentation
  22-NOV-1996 13:20:16.10

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal