Home Libraries Author Links

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

Collaboration diagram for Abstract Data Type StmThread:

Detailed Description

The abstract data type StmThread represents threads of execution, and provides the functionality to create and manage such threads.

Thread.

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 StmThread object can be achieved only as non-NULL return value of stmThreadCreate() or stmThreadSelf() and is intended to be used as argument of the other StmThread method functions.

StmThread objects with the value NULL are invalid or undefined.


Files

file  StmThreadAdtDoc.h
 Documentation of the abstract structure data type type StmThread.

StmThread Representation

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

typedef struct StmThreadImpl_ StmThreadImpl_
 Type name of implementation structure.
typedef StmThreadImpl_StmThread
 Pointer to implementation.
typedef const StmThreadImpl_ConstStmThread
 Pointer to constant implementation.

StmThread Creation and Destruction

StmThread stmThreadCreate (void *(*routine)(void *), void *arg)
 Creation of a new StmThread object.
int stmThreadDestroy (StmThread thread)
 Destruction of the StmThread object thread.

StmThread Method Functions

int stmThreadAtExit (void(*routine)(void))
 Register a function to run at normal termination of the calling thread.
StmThread stmThreadSelf (void)
 Return the StmThread object representing the calling thread.
int stmThreadCmp (StmThread thread1, StmThread thread2)
 Compare two StmThread objects.
int stmThreadJoin (StmThread thread, void **pResult)
 Join the StmThread object thread.


Typedef Documentation

typedef struct StmThreadImpl_ StmThreadImpl_

Type name of implementation structure.

Definition at line 60 of file StmThreadAdtDoc.h.

typedef StmThreadImpl_* StmThread

Pointer to implementation.

Examples:
conditiontest.c, mutextest.c, and processsemaphoretest.c.

Definition at line 63 of file StmThreadAdtDoc.h.

typedef const StmThreadImpl_* ConstStmThread

Pointer to constant implementation.

Definition at line 66 of file StmThreadAdtDoc.h.


Function Documentation

StmThread stmThreadCreate ( void *(*)(void *)  routine,
void *  arg 
)

Creation of a new StmThread object.

Parameters:
[in] routine Pointer to the thread function taking a sole argument arg and returning a void pointer.
[in] arg Argument of the thread function routine.
Effects:
The function creates a StmThread object and starts its thread function routine with the argument arg. This object has to be used as argument of the other StmThread functions.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The StmThread object created on success.

See also:
stmThreadDestroy(), stmThreadJoin().
Examples:
conditiontest.c, mutextest.c, and processsemaphoretest.c.

Referenced by main().

int stmThreadDestroy ( StmThread  thread  ) 

Destruction of the StmThread object thread.

Parameters:
[in] thread The StmThread object to be destroyed.
Effects:
The function destroys the StmThread object thread. It is no error to call the function for a StmThread object with value NULL in which case the function does nothing.
Note:
Destroying a StmThread object does not mean terminating its thread function.
Returns:
-1 on error. Then the variable errno contains the error's cause and the StmThread object is not destroyed.

0 on success.

See also:
stmThreadCreate(), stmThreadJoin().
Examples:
conditiontest.c, mutextest.c, and processsemaphoretest.c.

Referenced by main().

int stmThreadAtExit ( void(*)(void)  routine  ) 

Register a function to run at normal termination of the calling thread.

Parameters:
[in] routine Address of the function to register.
Effects:
The function registers the function pointed to by routine, to be called without arguments at normal termination of the calling thread. At normal thread termination, all functions registered by the stmThreadAtExit() function are called, in the reverse order of their registration.
Note:
As for Windows DLLs the Win32 function ExitProcess (either called explicitly by the application or implicitly by the system) terminates all other still running threads abnormally and thus the functions registered for them are not called, it is recommended to register a function by means of stmAtExit() which terminates all other still running threads normally thus ensuring that the functions registered with stmThreadAtExit() are called.
Returns:
0 on success.

-1 on error. Then the variable errno contains the error's cause.

StmThread stmThreadSelf ( void   ) 

Return the StmThread object representing the calling thread.

Returns:
NULL on error. Then the variable errno contains the error's cause.

The StmThread object representing the calling thread.

See also:
stmThreadCreate().

int stmThreadCmp ( StmThread  thread1,
StmThread  thread2 
)

Compare two StmThread objects.

Parameters:
[in] thread1 Left StmThread object to compare.
[in] thread2 Right StmThread object to compare.
Returns:
-1, if thread1 is less than thread2.

0, if thread1 is equal to thread2.

1, if thread1 is greater than thread2.

int stmThreadJoin ( StmThread  thread,
void **  pResult 
)

Join the StmThread object thread.

Parameters:
[in] thread The StmThread object to join.
[out] pResult If not NULL, the address of a void pointer for the result of the thread function.
Effects:
The calling thread blocks until the thread function of thread has returned.
Returns:
0 on success.

-1 on error. Then the variable errno contains the error's cause.

See also:
stmThreadCreate(), stmThreadDestroy().
Examples:
conditiontest.c, mutextest.c, and processsemaphoretest.c.

Referenced by main().


© Copyright Tom Michaelis 2002-2007

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