Home Libraries Author Links

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

Collaboration diagram for Abstract Data Type StmMutex:

Detailed Description

A StmMutex object provides a means to protect resources used by several threads of the calling process by mutual exclusively locking the object.

Mutex.

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

StmMutex objects with the value NULL are invalid or undefined.

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

static StmMutex mutex;

static int counter;

static void *handler (void *data)
{
    int i, id = * (int *) data;
    for (i = 0; i < 10; ++ i)
    {
        stmMutexLock (mutex);
        ++ counter;
        printf ("thread%d: Counter value: %d\n", id, counter);
        stmMutexUnlock (mutex);
    }
    return NULL;
}

int main ()
{
    static int id [] = {1, 2};
    mutex = stmMutexCreate (StmFalse);
    {
        StmThread thread1 = stmThreadCreate (handler, id + 0);
        StmThread thread2 = stmThreadCreate (handler, id + 1);
        stmThreadJoin (thread1, NULL);
        stmThreadJoin (thread2, NULL);
        stmThreadDestroy (thread1);
        stmThreadDestroy (thread2);
    }
    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
thread2: Counter value: 3
thread1: Counter value: 4
thread2: Counter value: 5
thread1: Counter value: 6
thread2: Counter value: 7
thread1: Counter value: 8
thread2: Counter value: 9
thread1: Counter value: 10
thread2: Counter value: 11
thread1: Counter value: 12
thread2: Counter value: 13
thread1: Counter value: 14
thread2: Counter value: 15
thread1: Counter value: 16
thread2: Counter value: 17
thread1: Counter value: 18
thread2: Counter value: 19
thread2: Counter value: 20


Files

file  mutextest.c
 Usage sample and test of the Abstract Data Type StmMutex.
file  StmMutexAdtDoc.h
 Documentation of the abstract structure data type type StmMutex.

StmMutex Representation

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

typedef struct StmMutexImpl_ StmMutexImpl_
 Type name of implementation structure.
typedef StmMutexImpl_StmMutex
 Pointer to implementation.
typedef const StmMutexImpl_ConstStmMutex
 Pointer to constant implementation.

StmMutex Creation and Destruction

StmMutex stmMutexCreate (StmBool recursive)
 Creation of a new StmMutex object.
int stmMutexDestroy (StmMutex mutex)
 Destruction of the StmMutex object mutex.

StmMutex Method Functions

int stmMutexLock (StmMutex mutex)
 Lock the StmMutex object mutex.
int stmMutexTryLock (StmMutex mutex)
 Try to lock the StmMutex object mutex.
int stmMutexTimedLock (StmMutex mutex, StmInt64 absTimeMs)
 Try to lock the StmMutex object mutex till the number absTimeMs of milliseconds elapsed since the Epoch (1970-01-01).
int stmMutexUnlock (StmMutex mutex)
 Unlock the StmMutex object mutex.

Functions

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

Variables

static StmMutex mutex
 The mutex object.
static int counter
 The shared resource.


Typedef Documentation

typedef struct StmMutexImpl_ StmMutexImpl_

Type name of implementation structure.

Definition at line 60 of file StmMutexAdtDoc.h.

typedef StmMutexImpl_* StmMutex

Pointer to implementation.

Examples:
conditiontest.c, and mutextest.c.

Definition at line 63 of file StmMutexAdtDoc.h.

typedef const StmMutexImpl_* ConstStmMutex

Pointer to constant implementation.

Definition at line 66 of file StmMutexAdtDoc.h.


Function Documentation

StmMutex stmMutexCreate ( StmBool  recursive  ) 

Creation of a new StmMutex object.

Parameters:
[in] recursive StmTrue, if the StmMutex object to be created shall be recursive.
Note:
On Windows all StmMutex objects are recursive, regardless of the value of recursive.
Effects:
The function creates a StmMutex object. This object has to be used as argument of the other StmMutex functions.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The StmMutex object created on success.

See also:
stmMutexDestroy().
Examples:
conditiontest.c, and mutextest.c.

Referenced by main().

int stmMutexDestroy ( StmMutex  mutex  ) 

Destruction of the StmMutex object mutex.

Parameters:
[in] mutex The StmMutex object to be destroyed.
Effects:
The function destroys the StmMutex object mutex. It is no error to call the function for a StmMutex 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 StmMutex object is not destroyed.

0 on success.

See also:
stmMutexCreate().
Examples:
conditiontest.c, and mutextest.c.

Referenced by main().

int stmMutexLock ( StmMutex  mutex  ) 

Lock the StmMutex object mutex.

Parameters:
[in] mutex The StmMutex object to lock.
Effects:
The calling thread blocks until it can achieve ownership of mutex thus locking it.
Returns:
0 on success.

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

See also:
stmMutexTryLock(), stmMutexTimedLock(), stmMutexUnlock().
Examples:
conditiontest.c, and mutextest.c.

Referenced by handler(), and main().

int stmMutexTryLock ( StmMutex  mutex  ) 

Try to lock the StmMutex object mutex.

Parameters:
[in] mutex The StmMutex object to lock.
Effects:
The calling thread tries to achieve ownership of mutex without blocking. If that is possible it thus locks it.
Returns:
0 on successful trial.

1 on unsuccessful trial. Then the variable errno is set to EBUSY.

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

See also:
stmMutexLock(), stmMutexTimedLock(), stmMutexUnlock().

int stmMutexTimedLock ( StmMutex  mutex,
StmInt64  absTimeMs 
)

Try to lock the StmMutex object mutex till the number absTimeMs of milliseconds elapsed since the Epoch (1970-01-01).

Parameters:
[in] mutex The StmMutex object to lock.
[in] absTimeMs The number of milliseconds elapsed since 00:00:00 UTC on January 1, 1970 till the calling thread maximally blocks.
Effects:
The calling thread blocks until it can achieve ownership of mutex thus locking it or till absTimeMs have been elapsed since the Epoch.
Returns:
0 on successful lock.

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:
stmMutexLock(), stmMutexTryLock(), stmMutexUnlock().

int stmMutexUnlock ( StmMutex  mutex  ) 

Unlock the StmMutex object mutex.

Parameters:
[in] mutex The StmMutex object to unlock.
Effects:
The calling thread gives up the ownership of mutex thus unlocking it.
Returns:
0 on success.

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

See also:
stmMutexLock(), stmMutexTryLock(), stmMutexTimedLock().
Examples:
conditiontest.c, and mutextest.c.

Referenced by handler(), and main().

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

The worker thread function.

Definition at line 82 of file mutextest.c.

int main (  ) 

Main function implementing the command mutextest.

Definition at line 98 of file mutextest.c.


Variable Documentation

StmMutex mutex [static]

The mutex object.

Definition at line 74 of file mutextest.c.

int counter [static]

The shared resource.

Definition at line 78 of file mutextest.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).