Home Libraries Author Links

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

Collaboration diagram for Abstract Data Type StmNamedCondition:

Detailed Description

A StmNamedCondition 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 an arbitrary process.

NamedCondition.

A StmNamedCondition object is always used in conjunction with a StmNamedMutex object, which must be locked prior to waiting on the condition.

On Windows systems StmNamedCondition 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 StmNamedCondition object can be achieved only as non-NULL return value of stmNamedConditionCreate() and is intended to be used as argument of the other StmNamedCondition method functions.

StmNamedCondition objects with the value NULL are invalid or undefined.

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

int main (int argc, char **argv)
{
    pid_t child = (pid_t) -1;
    StmNamedMutex requestMutex = stmNamedMutexCreate
    (
        argc == 1 ? "RequestMutex%p" : argv [1],
        StmFalse,
        StmAttach
    );
    StmNamedCondition requestCond = stmNamedConditionCreate
    (
        argc == 1 ? "RequestCondition%p" : argv [2]
    );
    StmNamedMutex responseMutex = stmNamedMutexCreate
    (
        argc == 1 ? "ResponseMutex%p" : argv [3],
        StmFalse,
        StmAttach
    );
    StmNamedCondition responseCond = stmNamedConditionCreate
    (
        argc == 1 ? "ResponseCondition%p" : argv [4]
    );
    if (argc == 1)
    {
        int counter = 0;
        char *const childArgv [] =
        {
            argv [0],
            (char *) stmNamedMutexName (requestMutex),
            (char *) stmNamedConditionName (requestCond),
            (char *) stmNamedMutexName (responseMutex),
            (char *) stmNamedConditionName (responseCond),
            NULL
        };
        if ((child = stmProcessSpawn (argv [0], childArgv, StmFalse)) < 0)
        {
            printf ("%s: stmProcessSpawn failed: %s\n",
                    argv [0], strerror (errno));
            exit (1);
        }
        stmNamedMutexLock (requestMutex);
        while (counter < 20)
        {
            switch
            (
                stmNamedConditionTimedWait
                (
                    requestCond,
                    requestMutex,
                    stmGetMsTime () + 10
                )
            )
            {
            case 0:
                stmNamedMutexLock (responseMutex);
                stmNamedConditionSignal (responseCond);
                printf ("Server %d: Got request %d from client\n",
                        getpid (), ++ counter);
                stmNamedMutexUnlock (responseMutex);
                break;
            case 1:
                break;
            default:
                counter = 20;
                printf ("Server %d: Waiting for request failed: %s: aborted\n",
                        getpid (), strerror (errno));
                break;
            }
        }
        stmNamedMutexUnlock (requestMutex);
        stmProcessWait (child, NULL);
    }
    else
    {
        int counter = 0;
        stmNamedMutexLock (responseMutex);
        while (counter < 20)
        {
            if
            (
                stmNamedMutexLock (requestMutex) ||
                stmNamedConditionSignal (requestCond) ||
                stmNamedMutexUnlock (requestMutex) ||
                stmNamedConditionTimedWait
                (
                    responseCond,
                    responseMutex,
                    stmGetMsTime () + 100
                )
            )
            {
                counter = 20;
                printf ("Client %d: Request for server failed: %s: aborted\n",
                        getpid (), strerror (errno));
            }
            else
            {
                printf ("Client %d: Got response %d from server\n",
                        getpid (), ++ counter);
            }
        }
        stmNamedMutexUnlock (responseMutex);
    }
    stmNamedConditionDestroy (responseCond);
    stmNamedMutexDestroy (responseMutex);
    stmNamedConditionDestroy (requestCond);
    stmNamedMutexDestroy (requestMutex);
    return 0;
}
If the example program above is run from the command line without arguments it will output something like this:
Server 4388: Got request 1 from client
Client 312: Got response 1 from server
Server 4388: Got request 2 from client
Client 312: Got response 2 from server
Server 4388: Got request 3 from client
Client 312: Got response 3 from server
Server 4388: Got request 4 from client
Client 312: Got response 4 from server
Server 4388: Got request 5 from client
Client 312: Got response 5 from server
Server 4388: Got request 6 from client
Client 312: Got response 6 from server
Server 4388: Got request 7 from client
Client 312: Got response 7 from server
Server 4388: Got request 8 from client
Client 312: Got response 8 from server
Server 4388: Got request 9 from client
Client 312: Got response 9 from server
Server 4388: Got request 10 from client
Client 312: Got response 10 from server
Server 4388: Got request 11 from client
Client 312: Got response 11 from server
Server 4388: Got request 12 from client
Client 312: Got response 12 from server
Server 4388: Got request 13 from client
Client 312: Got response 13 from server
Server 4388: Got request 14 from client
Client 312: Got response 14 from server
Server 4388: Got request 15 from client
Client 312: Got response 15 from server
Server 4388: Got request 16 from client
Client 312: Got response 16 from server
Server 4388: Got request 17 from client
Client 312: Got response 17 from server
Server 4388: Got request 18 from client
Client 312: Got response 18 from server
Server 4388: Got request 19 from client
Client 312: Got response 19 from server
Server 4388: Got request 20 from client
Client 312: Got response 20 from server


Files

file  namedconditiontest.c
 Usage sample and test of the Abstract Data Type StmNamedCondition.
file  StmNamedConditionAdtDoc.h
 Documentation of the abstract structure data type type StmNamedCondition.

StmNamedCondition Representation

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

typedef struct
StmNamedConditionImpl_ 
StmNamedConditionImpl_
 Type name of implementation structure.
typedef StmNamedConditionImpl_StmNamedCondition
 Pointer to implementation.
typedef const
StmNamedConditionImpl_
ConstStmNamedCondition
 Pointer to constant implementation.

StmNamedCondition Creation and Destruction

StmNamedCondition stmNamedConditionCreate (const char *name)
 Creation of a new StmNamedCondition object.
int stmNamedConditionDestroy (StmNamedCondition cond)
 Destruction of the StmNamedCondition object cond.

StmNamedCondition Method Functions

int stmNamedConditionAdjustChild (StmNamedCondition cond)
 Adjust the StmNamedCondition object cond after a fork system call.
const char * stmNamedConditionName (StmNamedCondition cond)
 Get the name of the StmNamedCondition object cond.
int stmNamedConditionSignal (StmNamedCondition cond)
 Signal one thread waiting on the StmNamedCondition object cond.
int stmNamedConditionBroadcast (StmNamedCondition cond)
 Signal all threads waiting on the StmNamedCondition object cond.
int stmNamedConditionWait (StmNamedCondition cond, StmNamedMutex mutex)
 Wait for the StmNamedCondition object cond to be signaled.
int stmNamedConditionTimedWait (StmNamedCondition cond, StmNamedMutex mutex, StmInt64 absTimeMs)
 Wait for the StmNamedCondition object cond to be signaled till the number absTimeMs of milliseconds elapsed since the Epoch (1970-01-01).

Functions

int main (int argc, char **argv)
 Main function implementing the command namedconditiontest.


Typedef Documentation

typedef struct StmNamedConditionImpl_ StmNamedConditionImpl_

Type name of implementation structure.

Definition at line 60 of file StmNamedConditionAdtDoc.h.

typedef StmNamedConditionImpl_* StmNamedCondition

Pointer to implementation.

Examples:
namedconditiontest.c.

Definition at line 63 of file StmNamedConditionAdtDoc.h.

typedef const StmNamedConditionImpl_* ConstStmNamedCondition

Pointer to constant implementation.

Definition at line 66 of file StmNamedConditionAdtDoc.h.


Function Documentation

StmNamedCondition stmNamedConditionCreate ( const char *  name  ) 

Creation of a new StmNamedCondition object.

Parameters:
[in] name The name of the StmNamedCondition object to be created. That name shall be a valid path name whose first component does not begin with '_' optionally followed by '%p' which is replaced by the process identifier of the calling process as decimal number. It is an error, if name is NULL or the empty string.
Note:
On Win32 systems a leading '/' character of a name is removed.
On non-Win32 sytems a '/' character is prepended to name, if it is lacking one.
Effects:
The function creates a StmNamedCondition object. This object has to be used as argument of the other StmNamedCondition functions.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The StmNamedCondition object created on success.

See also:
stmNamedConditionDestroy().
Examples:
namedconditiontest.c.

Referenced by main().

int stmNamedConditionDestroy ( StmNamedCondition  cond  ) 

Destruction of the StmNamedCondition object cond.

Parameters:
[in] cond The StmNamedCondition object to be destroyed.
Effects:
The function destroys the StmNamedCondition object cond. If cond represented the last reference in the system to the underlying condition, also that condition is destroyed.
It is no error to call the function for a StmNamedCondition 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 StmNamedCondition object is not destroyed.

0 on success.

See also:
stmNamedConditionCreate().
Examples:
namedconditiontest.c.

Referenced by main().

int stmNamedConditionAdjustChild ( StmNamedCondition  cond  ) 

Adjust the StmNamedCondition object cond after a fork system call.

Parameters:
[in] cond The StmNamedCondition object to adjust.
Effects:
Increments the reference count of the StmNamedCondition object cond on systems with fork system call.
Note:
The method function is intended to be called by the child process after a fork system call.
Returns:
-1 on error. Then the variable errno contains the error's cause.

0 on success.

const char* stmNamedConditionName ( StmNamedCondition  cond  ) 

Get the name of the StmNamedCondition object cond.

Parameters:
[in] cond The StmNamedCondition object to get the name of.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The name of cond as it is adjusted by the system on success.

See also:
stmNamedConditionCreate().
Examples:
namedconditiontest.c.

Referenced by main().

int stmNamedConditionSignal ( StmNamedCondition  cond  ) 

Signal one thread waiting on the StmNamedCondition object cond.

Parameters:
[in] cond The StmNamedCondition 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:
stmNamedConditionBroadcast(), stmNamedConditionWait(), stmNamedConditionTimedWait().
Examples:
namedconditiontest.c.

Referenced by main().

int stmNamedConditionBroadcast ( StmNamedCondition  cond  ) 

Signal all threads waiting on the StmNamedCondition object cond.

Parameters:
[in] cond The StmNamedCondition 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:
stmNamedConditionSignal(), stmNamedConditionWait(), stmNamedConditionTimedWait().

int stmNamedConditionWait ( StmNamedCondition  cond,
StmNamedMutex  mutex 
)

Wait for the StmNamedCondition object cond to be signaled.

Parameters:
[in] cond The StmNamedCondition object waited on.
[in] mutex The StmNamedMutex 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:
stmNamedConditionSignal(), stmNamedConditionBroadcast(), stmNamedConditionTimedWait().

int stmNamedConditionTimedWait ( StmNamedCondition  cond,
StmNamedMutex  mutex,
StmInt64  absTimeMs 
)

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

Parameters:
[in] cond The StmNamedCondition object waited on.
[in] mutex The StmNamedMutex 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:
stmNamedConditionSignal(), stmNamedConditionBroadcast(), stmNamedConditionWait().
Examples:
namedconditiontest.c.

Referenced by main().

int main ( int  argc,
char **  argv 
)

Main function implementing the command namedconditiontest.

Main function implementing the command matchtst.

Main function implementing the command dsettst.

Main function implementing the command cuglify.

Parameters:
[in] argc Argument count.
[in] argv Pointer to an array of argc argument strings followed by an additional NULL array element (only used internally).
Returns:
0, if no error occurred.

1, if an error occurred.

Definition at line 87 of file namedconditiontest.c.


© Copyright Tom Michaelis 2002-2007

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