Home Libraries Author Links

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

Collaboration diagram for Abstract Data Type StmNamedMutex:

Detailed Description

A StmNamedMutex object provides a means to protect resources used by the threads of several processes by mutual exclusively locking the object.

NamedMutex.

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

StmNamedMutex 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;
    int i;
    StmNamedMutex mutex = stmNamedMutexCreate
    (
        argc == 1 ? "TestNamedMutex%p" : argv [1],
        StmFalse,
        StmAttach
    );
    if (!mutex)
    {
        printf ("Process %d: stmNamedMutexCreate failed: %s\n",
                getpid (), strerror (errno));
        exit (1);
    }
    if (argc == 1)
    {
        char *const childArgv [] =
        {
            argv [0],
            (char *) stmNamedMutexName (mutex),
            NULL
        };
        if ((child = stmProcessSpawn (argv [0], childArgv, StmFalse)) < 0)
        {
            printf ("%s: stmProcessSpawn failed: %s\n",
                    argv [0], strerror (errno));
            exit (1);
        }
    }
    for (i = 0; i < 10; ++ i)
    {
        if (stmNamedMutexLock (mutex))
        {
            printf ("Process %d: stmNamedMutexLock failed: %s\n",
                    getpid (), strerror (errno));
        }
        else
        {
            printf ("This is process %d\n", getpid ());
            stmNamedMutexUnlock (mutex);
            stmSleepMs (5);
        }
    }
    stmNamedMutexDestroy (mutex);
    if (child > 0)
    {
        stmProcessWait (child, NULL);
    }
    return 0;
}
If the example program above is run from the command line without arguments it will output something like this:
This is process 4812
This is process 324
This is process 4812
This is process 324
This is process 4812
This is process 324
This is process 4812
This is process 324
This is process 4812
This is process 324
This is process 4812
This is process 324
This is process 4812
This is process 324
This is process 4812
This is process 324
This is process 4812
This is process 324
This is process 4812
This is process 324


Files

file  namedmutextest.c
 Usage sample and test of the Abstract Data Type StmNamedMutex.
file  StmNamedMutexAdtDoc.h
 Documentation of the abstract structure data type type StmNamedMutex.

StmNamedMutex Representation

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

typedef struct StmNamedMutexImpl_ StmNamedMutexImpl_
 Type name of implementation structure.
typedef StmNamedMutexImpl_StmNamedMutex
 Pointer to implementation.
typedef const StmNamedMutexImpl_ConstStmNamedMutex
 Pointer to constant implementation.

StmNamedMutex Creation and Destruction

StmNamedMutex stmNamedMutexCreate (const char *name, StmBool recursive, unsigned int attach)
 Creation of a new StmNamedMutex object.
int stmNamedMutexDestroy (StmNamedMutex mutex)
 Destruction of the StmNamedMutex object mutex.

StmNamedMutex Method Functions

int stmNamedMutexAdjustChild (StmNamedMutex mutex)
 Adjust the StmNamedMutex object mutex after a fork system call.
const char * stmNamedMutexName (StmNamedMutex mutex)
 Get the name of the StmNamedMutex object mutex.
int stmNamedMutexLock (StmNamedMutex mutex)
 Lock the StmNamedMutex object mutex.
int stmNamedMutexTryLock (StmNamedMutex mutex)
 Try to lock the StmNamedMutex object mutex.
int stmNamedMutexTimedLock (StmNamedMutex mutex, StmInt64 absTimeMs)
 Try to lock the StmNamedMutex object mutex till the number absTimeMs of milliseconds elapsed since the Epoch (1970-01-01).
int stmNamedMutexUnlock (StmNamedMutex mutex)
 Unlock the StmNamedMutex object mutex.

Functions

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


Typedef Documentation

typedef struct StmNamedMutexImpl_ StmNamedMutexImpl_

Type name of implementation structure.

Definition at line 60 of file StmNamedMutexAdtDoc.h.

typedef StmNamedMutexImpl_* StmNamedMutex

Pointer to implementation.

Examples:
namedconditiontest.c, and namedmutextest.c.

Definition at line 63 of file StmNamedMutexAdtDoc.h.

typedef const StmNamedMutexImpl_* ConstStmNamedMutex

Pointer to constant implementation.

Definition at line 66 of file StmNamedMutexAdtDoc.h.


Function Documentation

StmNamedMutex stmNamedMutexCreate ( const char *  name,
StmBool  recursive,
unsigned int  attach 
)

Creation of a new StmNamedMutex object.

Parameters:
[in] name The name of the StmNamedMutex 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.
[in] recursive StmTrue, if the StmNamedMutex object to be created shall be recursive.
[in] attach Attach mode:
  • StmNoSystemFlag: Error causing the variable errno to be set to EINVAL.
  • StmAttachExisting: It is an error, if a mutex named by name does not already exist in the system.
  • StmAttachCreated: It is an error, if a mutex named by name already exists in the system.
  • StmAttach: If a mutex named by name does not already exist in the system, it is created.
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.
Note:
On Win32 systems and on Cygwin under Windows all StmNamedMutex objects are recursive, regardless of the value of recursive.
Effects:
On success the function creates a valid StmNamedMutex object. This object has to be used as argument of the other StmNamedMutex functions.
If a mutex named by name does not yet exist in the system, it is created with recursive and attached to the StmNamedMutex object created, if attach allows so.
If a mutex named by name already exists in the system, it is attached to the StmNamedMutex object created, if attach allows so, and recursive is ignored in that case.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The StmNamedMutex object created on success.

See also:
stmNamedMutexDestroy().
Examples:
namedconditiontest.c, and namedmutextest.c.

Referenced by main().

int stmNamedMutexDestroy ( StmNamedMutex  mutex  ) 

Destruction of the StmNamedMutex object mutex.

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

0 on success.

See also:
stmNamedMutexCreate().
Examples:
namedconditiontest.c, and namedmutextest.c.

Referenced by main().

int stmNamedMutexAdjustChild ( StmNamedMutex  mutex  ) 

Adjust the StmNamedMutex object mutex after a fork system call.

Parameters:
[in] mutex The StmNamedMutex object to adjust.
Effects:
Increments the reference count of the StmNamedMutex object mutex 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* stmNamedMutexName ( StmNamedMutex  mutex  ) 

Get the name of the StmNamedMutex object mutex.

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

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

See also:
stmNamedMutexCreate().
Examples:
namedconditiontest.c, and namedmutextest.c.

Referenced by main().

int stmNamedMutexLock ( StmNamedMutex  mutex  ) 

Lock the StmNamedMutex object mutex.

Parameters:
[in] mutex The StmNamedMutex 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:
stmNamedMutexTryLock(), stmNamedMutexTimedLock(), stmNamedMutexUnlock().
Examples:
namedconditiontest.c, and namedmutextest.c.

Referenced by main().

int stmNamedMutexTryLock ( StmNamedMutex  mutex  ) 

Try to lock the StmNamedMutex object mutex.

Parameters:
[in] mutex The StmNamedMutex 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:
stmNamedMutexLock(), stmNamedMutexTimedLock(), stmNamedMutexUnlock().

int stmNamedMutexTimedLock ( StmNamedMutex  mutex,
StmInt64  absTimeMs 
)

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

Parameters:
[in] mutex The StmNamedMutex 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:
stmNamedMutexLock(), stmNamedMutexTryLock(), stmNamedMutexUnlock().

int stmNamedMutexUnlock ( StmNamedMutex  mutex  ) 

Unlock the StmNamedMutex object mutex.

Parameters:
[in] mutex The StmNamedMutex 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:
stmNamedMutexLock(), stmNamedMutexTryLock(), stmNamedMutexTimedLock().
Examples:
namedconditiontest.c, and namedmutextest.c.

Referenced by main().

int main ( int  argc,
char **  argv 
)

Main function implementing the command namedmutextest.

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 86 of file namedmutextest.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).