datatypes(3)

NAME

threads data types - Data Types used by DCE Threads

DESCRIPTION

The DCE Threads data types can be divided into two broad categories, Primitive System and Application Level.

Primitive System Data Types

The first consists of types that represent structures used by (and internal to) DCE Threads. These are defined as being primitive system data types:

•pthread_attr_t

•pthread_cond_t

•pthread_condattr_t

•pthread_key_t

•pthread_mutex_t

•pthread_mutexattr_t

•pthread_once_t

•pthread_t

Although applications must know about these types, passing them in and receiving them from various DCE Threads routines, the structures themselves are opaque: they cannot be directly modified by applications, and they can be manipulated only (and only in some cases) through specific DCE Threads routines. (The pthread_key_t type is somewhat different from the others in this list, in that it is essentially a handle to a thread-private block of memory requested by a call to pthread_keycreate().)

Application Level Data Types

The second category of DCE Threads data consists of types used to describe objects that originate in the application:

•pthread_addr_t

•pthread_destructor_t

•pthread_initroutine_t

•pthread_startroutine_t

•sigset_t

All of the above types, with the exception of the last, are various kinds of memory addresses that must be passed by callers of certain DCE Threads routines. These types are extensions to POSIX. They permit DCE Threads to be used on platforms that are not fully ANSI C compliant. While being extensions to permit the use of compilers that are not ANSI C compatible, they are fully portable data types. The last data type, sigset_t, exhibits properties of both primitive system and application level data types. While objects of this type originate in the application, the data type is opaque. A set of functions is provided to manipulate objects of this type. For further information, see the following descriptions, listed in sorted order.

DATA TYPE DESCRIPTIONS

Following are individual descriptions of each of the DCE Threads data types. The descriptions include the routines where the data type is modified, e.g., created, changed or deleted/destroyed, but not the routines referencing or using them that do not change them.

•pthread_addr_t A miscellaneous data type representing an address value that must be passed by the caller of various Threads routines. Usually the pthread_addr_t value is the address of an area which contains various parameters to be made accessible to an implicitly called routine. For example, when the pthread_create() routine is called, one of the parameters passed is a pthread_addr_t value that contains an address which will be passed to the start_routine which the thread is being created to execute; presumably the routine will extract necessary parameters from the area referenced by this address.

•pthread_attr_t Threads attribute object, used to specify the attributes of a thread when it is created by a call to pthread_create(). The object is created by a call to pthread_attr_create(), then modified as desired by calls to:

—pthread_attr_setinheritsched()

—pthread_attr_setprio()

—pthread_attr_setsched()

—pthread_attr_setstacksize()

(Note that there are _get versions of these four calls, which can be used to retrieve the respective values.)

•pthread_cond_t Data type representing a Threads condition variable. The variable is created by a call to pthread_cond_init(), and destroyed by a call to pthread_cond_destroy().

•pthread_condattr_t Data type representing a Threads condition variable attributes object. Created by a call to pthread_condattr_create(). The range of possible modifications to a condition variable attributes object is not great: creation (via pthread_condattr_create()) and deletion (via pthread_condattr_delete()) are all. The object is created with default values.

•pthread_destructor_t Data type, passed in a call to pthread_keycreate(), representing the address of a procedure to be called to destroy a data value associated with a unique thread-specific data key value when the thread terminates .

•pthread_initroutine_t Data type representing the address of a procedure that performs a one-time initialization for a thread. It is passed in a call to pthread_once(). The pthread_once() routine, when called, executes the initialization routine. The specified routine is guaranteed to be executed only once, even though the pthread_once() call occurs in multi-threaded code.

•pthread_key_t Data type representing a thread-specific data key, created by a call to pthread_keycreate(). The key is an address of memory. Associating a static block of memory with a specific thread in this way is an alternative to using stack memory for the thread. The key is destroyed by the application-supplied procedure specified by the routine specified using the pthread_destructor_t data type in the call to pthread_keycreate().

•pthread_mutex_t Data type representing a mutex object. It is created by a call to pthread_mutex_init() and destroyed by a call to pthread_mutex_destroy(). Care should be taken not to attempt to destroy a locked object.

•pthread_mutexattr_t Data type representing an attributes object which defines the characteristics of a mutex. Created by a call to pthread_mutexattr_create(); modified by calls to pthread_mutexattr_setkind_np() (which allows you to specify fast, recursive, or non-recursive mutexes); passed to pthread_mutex_init() to create the mutex with the specified atttributes. The only other modification allowed is to destroy the mutex attributes object, with pthread_mutexattr_delete().

•pthread_once_t A data structure that defines the characteristics of the one-time initialization routine executed by calling pthread_once(). The structure is opaque to the application, and cannot be modified by it, but it must be explicitly declared by the client code, and initialized by a call to pthread_once_init(). The pthread_once_t type must not be an array.

•pthread_startroutine_t Data type representing the address of the application routine or other routine, whatever it is, that a new thread is created to execute as its start routine.

•pthread_t Data type representing a thread handle, created by a call to pthread_create(). The thread handle is used thenceforth to identify the thread to calls such as pthread_cancel(), pthread_detach(), pthread_equal() (to which two handles are passed for comparison), etc.

•sigset_t Data type representing a set of signals. It is always an integral or structure type. If a structure, it is intended to be a simple structure, e.g., a set of arrays as opposed to a set of pointers. It is opaque in that a set of functions called the sigsetops primitives is provided to manipulate signal sets. They operate on signal set data objects addressable by the application, not on any objects known to the system. The primitives are sigemptyset() and sigfillset() which initialize the set as either empty or full, sigaddset() and sigdelset() which add or delete signals from the set, and sigismember() which permits the application to check if a object (signal) of type sigset_t is a member of the signal set. Applications must call at least one of the initialization primitives at least once for each object of type sigset_t prior to any other use of that object (signal set). The object, or objects, represented by this data type when used by sigaction() is (are) used in conjunction with a sigaction structure by the sigaction function to describe an action to be taken with (a) specified sigset_t-type object(s).