Home Libraries Author Links

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

Collaboration diagram for Abstract Data Type StmCondition:

Detailed Description

A StmCondition object is a synchronization primitive used to cause a thread to wait until a particular shared-data condition (or time) is met by another thread of the calling process.

Condition.

A StmCondition object is always used in conjunction with a StmMutex object, which must be locked prior to waiting on the condition. On Windows systems StmCondition 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 StmCondition object can be achieved only as non-NULL return value of stmConditionCreate() and is intended to be used as argument of the other StmCondition method functions.

StmCondition objects with the value NULL are invalid or undefined.

Example:
#include <stdio.h>
#include <string.h>
#include <errno.h>
#include <stm/system.h>

static StmMutex mutex;

static StmCondition cond;

static int counter;

static void *handler (void *data)
{
    int id = * (int *) data;
    stmMutexLock (mutex);
    while (counter < 20)
    {
        switch (stmConditionTimedWait (cond, mutex, stmGetMsTime () + 10))
        {
        case 0:
            if (counter < 20)
            {
                ++ counter;
                printf ("thread%d: Counter value: %d\n", id, counter);
            }
            break;
        case 1:
            break;
        default:
            counter = 20;
            printf ("thread%d: Error: %s: aborted\n", id, strerror (errno));
            break;
        }
    }
    stmMutexUnlock (mutex);
    return NULL;
}

int main ()
{
    static int id [] = {1, 2};
    mutex = stmMutexCreate (StmFalse);
    cond = stmConditionCreate ();
    {
        StmThread thread1 = stmThreadCreate (handler, id + 0);
        StmThread thread2 = stmThreadCreate (handler, id + 1);
        while (counter < 20)
        {
            stmMutexLock (mutex);
            stmConditionBroadcast (cond);
            stmMutexUnlock (mutex);
        }
        stmThreadJoin (thread1, NULL);
        stmThreadJoin (thread2, NULL);
        stmThreadDestroy (thread1);
        stmThreadDestroy (thread2);
    }
    stmConditionDestroy (cond);
    stmMutexDestroy (mutex);
    return 0;
}
If the example program above is run from the command line without arguments it will output something like this:
thread1: Counter value: 1
thread1: Counter value: 2
thread1: Counter value: 3
thread2: Counter value: 4
thread2: Counter value: 5
thread1: Counter value: 6
thread1: Counter value: 7
thread2: Counter value: 8
thread2: Counter value: 9
thread1: Counter value: 10
thread1: Counter value: 11
thread2: Counter value: 12
thread2: Counter value: 13
thread1: Counter value: 14
thread1: Counter value: 15
thread2: Counter value: 16
thread1: Counter value: 17
thread2: Counter value: 18
thread2: Counter value: 19
thread1: Counter value: 20


Files

file  conditiontest.c
 Usage sample and test of the Abstract Data Type StmCondition.
file  StmConditionAdtDoc.h
 Documentation of the abstract structure data type type StmCondition.

StmCondition Representation

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

typedef struct StmConditionImpl_ StmConditionImpl_
 Type name of implementation structure.
typedef StmConditionImpl_StmCondition
 Pointer to implementation.
typedef const StmConditionImpl_ConstStmCondition
 Pointer to constant implementation.

StmCondition Creation and Destruction

StmCondition stmConditionCreate (void)
 Creation of a new StmCondition object.
int stmConditionDestroy (StmCondition cond)
 Destruction of the StmCondition object cond.

StmCondition Method Functions

int stmConditionSignal (StmCondition cond)
 Signal one thread waiting on the StmCondition object cond.
int stmConditionBroadcast (StmCondition cond)
 Signal all threads waiting on the StmCondition object cond.
int stmConditionWait (StmCondition cond, StmMutex mutex)
 Wait for the StmCondition object cond to be signaled.
int stmConditionTimedWait (StmCondition cond, StmMutex mutex, StmInt64 absTimeMs)
 Wait for the StmCondition object cond to be signaled till the number absTimeMs of milliseconds elapsed since the Epoch (1970-01-01).

Functions

static void * handler (void *data)
 The worker thread function.
int main ()
 Main function implementing the command conditiontest.

Variables

static StmMutex mutex
 The mutex object.
static StmCondition cond
 The condition variable.
static int counter
 The shared resource.


Typedef Documentation

typedef struct StmConditionImpl_ StmConditionImpl_

Type name of implementation structure.

Definition at line 60 of file StmConditionAdtDoc.h.

typedef StmConditionImpl_* StmCondition

Pointer to implementation.

Examples:
conditiontest.c.

Definition at line 63 of file StmConditionAdtDoc.h.

typedef const StmConditionImpl_* ConstStmCondition

Pointer to constant implementation.

Definition at line 66 of file StmConditionAdtDoc.h.


Function Documentation

StmCondition stmConditionCreate ( void   ) 

Creation of a new StmCondition object.

Effects:
The function creates a StmCondition object. This object has to be used as argument of the other StmCondition functions.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The StmCondition object created on success.

See also:
stmConditionDestroy().
Examples:
conditiontest.c.

Referenced by main().

int stmConditionDestroy ( StmCondition  cond  ) 

Destruction of the StmCondition object cond.

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

0 on success.

See also:
stmConditionCreate().
Examples:
conditiontest.c.

Referenced by main().

int stmConditionSignal ( StmCondition  cond  ) 

Signal one thread waiting on the StmCondition object cond.

Parameters:
[in] cond The StmCondition object threads are waiting on.
Effects:
The calling thread signals one thread waiting on cond, if any.
Returns:
0 on success.

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

See also:
stmConditionBroadcast(), stmConditionWait(), stmConditionTimedWait().

int stmConditionBroadcast ( StmCondition  cond  ) 

Signal all threads waiting on the StmCondition object cond.

Parameters:
[in] cond The StmCondition object threads are waiting on.
Effects:
The calling thread signals all thread waiting on cond, if any.
Returns:
0 on success.

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

See also:
stmConditionSignal(), stmConditionWait(), stmConditionTimedWait().
Examples:
conditiontest.c.

Referenced by main().

int stmConditionWait ( StmCondition  cond,
StmMutex  mutex 
)

Wait for the StmCondition object cond to be signaled.

Parameters:
[in] cond The StmCondition object waited on.
[in] mutex The StmMutex object used for locking.
Requires:
The calling thread owns (has locked) mutex.
Effects:
The calling thread atomically unlocks mutex and blocks till being signaled by another thread, which in turn causes mutex to be owned by the calling thread again.
Returns:
0 on success.

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

See also:
stmConditionSignal(), stmConditionBroadcast(), stmConditionTimedWait().

int stmConditionTimedWait ( StmCondition  cond,
StmMutex  mutex,
StmInt64  absTimeMs 
)

Wait for the StmCondition object cond to be signaled till the number absTimeMs of milliseconds elapsed since the Epoch (1970-01-01).

Parameters:
[in] cond The StmCondition object waited on.
[in] mutex The StmMutex object used for locking.
[in] absTimeMs The number of milliseconds elapsed since 00:00:00 UTC on January 1, 1970 till the calling thread maximally blocks.
Requires:
The calling thread owns (has locked) mutex.
Effects:
The calling thread atomically unlocks mutex and blocks till being signaled by another thread or till absTimeMs have been elapsed since the Epoch, which both in turn causes mutex to be owned by the calling thread again.
Returns:
0 on successful wait.

1 on timeout. Then the variable errno is set to ETIMEDOUT.

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

See also:
stmConditionSignal(), stmConditionBroadcast(), stmConditionTimedWait().
Examples:
conditiontest.c.

Referenced by handler().

static void* handler ( void *  data  )  [static]

The worker thread function.

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

Definition at line 88 of file conditiontest.c.

Referenced by main().

int main (  ) 

Main function implementing the command conditiontest.

Examples:
conditiontest.c, cuglify.c, dsettst.c, matchtst.c, mutextest.c, namedconditiontest.c, namedmutextest.c, processsemaphoretest.c, semaphoretest.c, sharedmemorytest.c, and systemuniquetest.c.

Definition at line 118 of file conditiontest.c.


Variable Documentation

StmMutex mutex [static]

The mutex object.

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

Definition at line 76 of file conditiontest.c.

Referenced by handler(), and main().

StmCondition cond [static]

The condition variable.

Examples:
conditiontest.c.

Definition at line 80 of file conditiontest.c.

Referenced by handler(), and main().

int counter [static]

The shared resource.

Examples:
conditiontest.c, mutextest.c, namedconditiontest.c, processsemaphoretest.c, sharedmemorytest.c, and systemuniquetest.c.

Definition at line 84 of file conditiontest.c.

Referenced by handler(), main(), stmSampleItemTypeInit(), and stmSampleMboxTypeInit().


© Copyright Tom Michaelis 2002-2007

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