Home Libraries Author Links

Abstract Data Type StmThreadSpecific
[System: Operating System Dependent Facilities]

Collaboration diagram for Abstract Data Type StmThreadSpecific:

Detailed Description

StmThreadSpecific is an abstract data type for thread-specific items represented as void pointers.

ThreadSpecific.

Programs often need global or static variables that have different values in different threads. Since all StmThread threds share one memory space, this cannot be achieved with regular variables.

Thread-specific items represented as void pointers is the answer to this need. Such thread-specific items are held and managed by a StmThreadSpecific object which is common to all StmThread threads of a process but holds a different void pointer for each thread. These void pointers are initially NULL for each thread as they are for newly created threads. When a thread terminates, and the void pointer held by that thread in not NULL and a destructor function has been defined for the StmThreadSpecific object, that destructor function is called with the void pointer as its sole argument.

On Windows systems StmThread operations are implemented using Windows Platform SDK functions, whereas on non-Windows systems they are implemented as thin wrappers of the corresponding POSIX.1c threads related functions.

A valid StmThreadSpecific object can be achieved only as non-NULL return value of stmThreadSpecificCreate() and is intended to be used as argument of the other StmThreadSpecific method functions.

StmThreadSpecific objects with the value NULL are invalid or undefined.


Files

file  StmThreadSpecificAdtDoc.h
 Documentation of the abstract structure data type type StmThreadSpecific.

StmThreadSpecific Representation

An object of abstract data type StmThreadSpecific is represented as a pointer to its implementation.

typedef struct
StmThreadSpecificImpl_ 
StmThreadSpecificImpl_
 Type name of implementation structure.
typedef StmThreadSpecificImpl_StmThreadSpecific
 Pointer to implementation.
typedef const
StmThreadSpecificImpl_
ConstStmThreadSpecific
 Pointer to constant implementation.

StmThreadSpecific Creation and Destruction

StmThreadSpecific stmThreadSpecificCreate (void(*destructor)(void *))
 Creation of a new StmThreadSpecific object.
int stmThreadSpecificDestroy (StmThreadSpecific threadSpecific)
 Destruction of the StmThreadSpecific object threadSpecific.

StmThreadSpecific Method Functions

void * stmThreadSpecificGet (StmThreadSpecific threadSpecific)
 Return the void pointer of threadSpecific associated with the calling thread.
int stmThreadSpecificSet (StmThreadSpecific threadSpecific, const void *value)
 Set the void pointer of threadSpecific associated with the calling thread.


Typedef Documentation

typedef struct StmThreadSpecificImpl_ StmThreadSpecificImpl_

Type name of implementation structure.

Definition at line 60 of file StmThreadSpecificAdtDoc.h.

typedef StmThreadSpecificImpl_* StmThreadSpecific

Pointer to implementation.

Definition at line 63 of file StmThreadSpecificAdtDoc.h.

typedef const StmThreadSpecificImpl_* ConstStmThreadSpecific

Pointer to constant implementation.

Definition at line 66 of file StmThreadSpecificAdtDoc.h.


Function Documentation

StmThreadSpecific stmThreadSpecificCreate ( void(*)(void *)  destructor  ) 

Creation of a new StmThreadSpecific object.

Parameters:
[in] destructor If non-NULL, Pointer to a destuctor function.
Effects:
The function creates a StmThreadSpecific object visible to all threads in the process. The StmThreadSpecific objects provided by stmThreadSpecificCreate() are used to locate thread-specific data. Although the same StmThreadSpecific object may be used by different threads, the values bound to the StmThreadSpecific object by stmThreadSpecificSet() are maintained on a per-thread basis and persist for the life of the calling thread.
Upon StmThreadSpecific object creation, the value NULL is associated with the new object in all active threads. Upon thread creation, the value NULL is associated with all defined StmThreadSpecific objects in the new thread.
An optional destructor function may be associated with each StmThreadSpecific object. At thread exit, if a StmThreadSpecific object has a non-NULL destructor pointer, and the thread has a non-NULL value associated with that object, the value of the object is set to NULL, and then the function pointed to is called with the previously associated value as its sole argument. The order of destructor calls is unspecified if more than one destructor exists for a thread when it exits.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The StmThreadSpecific object created on success.

See also:
stmThreadSpecificDestroy(), stmThreadSpecificGet(), stmThreadSpecificSet().

int stmThreadSpecificDestroy ( StmThreadSpecific  threadSpecific  ) 

Destruction of the StmThreadSpecific object threadSpecific.

Parameters:
[in] threadSpecific The StmThreadSpecific object to be destroyed.
Effects:
The function destroys the StmThreadSpecific object threadSpecific. It is no error to call the function for a StmThreadSpecific object with value NULL in which case the function does nothing.
The thread-specific data values associated with threadSpecific need not be NULL at the time stmThreadSpecificDestroy() is called. It is the responsibility of the application to free any application storage or perform any cleanup actions for data structures related to the deleted object or associated thread-specific data in any threads. This cleanup can be done either before or after stmThreadSpecificDestroy() is called. Any attempt to use threadSpecific following the call to stmThreadSpecificDestroy() results in undefined behavior.
The stmThreadSpecificDestroy() function is callable from within StmThreadSpecific destructor functions. No destructor function is invoked by stmThreadSpecificDestroy(). Any destructor function that may have been associated with threadSpecific is no longer called upon thread exit.
Returns:
-1 on error. Then the variable errno contains the error's cause and the StmThreadSpecific object is not destroyed.

0 on success.

See also:
stmThreadSpecificCreate(), stmThreadSpecificGet(), stmThreadSpecificSet().

void* stmThreadSpecificGet ( StmThreadSpecific  threadSpecific  ) 

Return the void pointer of threadSpecific associated with the calling thread.

Parameters:
[in] threadSpecific The StmThreadSpecific object.
Returns:
NULL, if no thread-specific void pointer is associated with threadSpecific for the calling thread.

The void pointer currently bound to threadSpecific on behalf of the calling thread.

Note:
For performance reasons no error return is provided.
See also:
stmThreadSpecificCreate(), stmThreadSpecificDestroy(), stmThreadSpecificSet().

int stmThreadSpecificSet ( StmThreadSpecific  threadSpecific,
const void *  value 
)

Set the void pointer of threadSpecific associated with the calling thread.

Parameters:
[in] threadSpecific The StmThreadSpecific object.
[in] value The void pointer to be associated.
Effects:
The function associates for the calling thread the thread-specific value with the StmThreadSpecific object threadSpecific.
Note:
Different threads may bind different values to the same StmThreadSpecific object. These values are typically pointers to blocks of dynamically allocated memory that have been reserved for use by the calling thread.
Returns:
-1 on error. Then the variable errno contains the error's cause and the void pointer is not set.

0 on success.

See also:
stmThreadSpecificCreate(), stmThreadSpecificDestroy(), stmThreadSpecificGet().


© Copyright Tom Michaelis 2002-2007

Distributed under the SysToMath Software License (See the accompanying file license.txt or a copy at www.SysToMath.com).