Home Libraries Author Links

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

Collaboration diagram for Abstract Data Type StmSemaphore:

Detailed Description

A StmSemaphore object provides a named counting semaphore serving as synchronization primitive between the threads of one or more processes.

Semaphore.

On Windows systems StmSemaphore operations are implemented using Windows Platform SDK functions, whereas on non-Windows systems they are implemented as thin wrappers of the corresponding POSIX.1c semaphore related functions.

A valid StmSemaphore object can be achieved only as non-NULL return value of stmSemaphoreCreate() and is intended to be used as argument of the other StmSemaphore method functions.

StmSemaphore 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)
{
    struct
    {
        StmSemaphore semaphore;
        char *msg;
    }
    data [] =
    {
        {
            NULL,
            "Ping"
        },
        {
            NULL,
            "Pong"
        }
    };
    int i, j, k;
    char suff [16];
    char name [32];
    if (argc == 1)
    {
        char *const childArgv [] = {argv [0], suff, NULL};
        sprintf (suff, "%d", getpid ());
        if (stmProcessSpawn (argv [0], childArgv, StmFalse) < 0)
        {
            printf ("%s: stmProcessSpawn failed: %s\n",
                    argv [0], strerror (errno));
            exit (1);
        }
        j = 0;
    }
    else
    {
        strcpy (suff, argv [1]);
        j = 1;
    }
    for (k = 0; k < 2; ++ k)
    {
        sprintf (name, "TestSemaphore%s%s", data [k].msg, suff);
        if (! (data [k].semaphore = stmSemaphoreCreate (name, 1 - k, StmAttach)))
        {
            printf ("Process %d: stmSemaphoreCreate for '%s' failed: %s\n",
                    getpid (), name, strerror (errno));
        }
    }
    for (i = 0; i < 10; ++ i)
    {
        if (stmSemaphoreTimedAcquire (data [j].semaphore, stmGetMsTime () + 500))
        {
            printf ("Process %d: stmSemaphoreAcquire for '%s' failed: %s\n",
                    getpid (), stmSemaphoreName (data [j].semaphore), strerror (errno));
            exit (1);
        }
        printf ("Process %d: %s\n", getpid (), data [j].msg);
        if (stmSemaphoreRelease (data [1 - j].semaphore))
        {
            printf ("Process %d: stmSemaphoreRelease for '%s' failed: %s\n",
                    getpid (), stmSemaphoreName (data [1 - j].semaphore), strerror (errno));
            exit (1);
        }
    }
    stmSemaphoreDestroy (data [0].semaphore);
    stmSemaphoreDestroy (data [1].semaphore);
    return 0;
}
If the example program above is run from the command line without arguments it will output something like this:
Process 4808: Ping
Process 5444: Pong
Process 4808: Ping
Process 5444: Pong
Process 4808: Ping
Process 5444: Pong
Process 4808: Ping
Process 5444: Pong
Process 4808: Ping
Process 5444: Pong
Process 4808: Ping
Process 5444: Pong
Process 4808: Ping
Process 5444: Pong
Process 4808: Ping
Process 5444: Pong
Process 4808: Ping
Process 5444: Pong
Process 4808: Ping
Process 5444: Pong


Files

file  semaphoretest.c
 Usage sample and test of the Abstract Data Type StmSemaphore.
file  StmSemaphoreAdtDoc.h
 Documentation of the abstract structure data type type StmSemaphore.

StmSemaphore Representation

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

typedef struct StmSemaphoreImpl_ StmSemaphoreImpl_
 Type name of implementation structure.
typedef StmSemaphoreImpl_StmSemaphore
 Pointer to implementation.
typedef const StmSemaphoreImpl_ConstStmSemaphore
 Pointer to constant implementation.

StmSemaphore Creation and Destruction

StmSemaphore stmSemaphoreCreate (const char *name, unsigned int value, unsigned int attach)
 Creation of a new StmSemaphore object.
int stmSemaphoreDestroy (StmSemaphore semaphore)
 Destruction of the StmSemaphore object semaphore.

StmSemaphore Method Functions

int stmSemaphoreAdjustChild (StmSemaphore semaphore)
 Adjust the StmSemaphore object semaphore after a fork system call.
const char * stmSemaphoreName (StmSemaphore semaphore)
 Get the name of the StmSemaphore object semaphore.
int stmSemaphoreAcquire (StmSemaphore semaphore)
 Acquire the StmSemaphore object semaphore.
int stmSemaphoreTryAcquire (StmSemaphore semaphore)
 Try to acquire the StmSemaphore object semaphore.
int stmSemaphoreTimedAcquire (StmSemaphore semaphore, StmInt64 absTimeMs)
 Try to acquire the StmSemaphore object semaphore till the number absTimeMs of milliseconds elapsed since the Epoch (1970-01-01).
int stmSemaphoreRelease (StmSemaphore semaphore)
 Release the StmSemaphore object semaphore.

Functions

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


Typedef Documentation

typedef struct StmSemaphoreImpl_ StmSemaphoreImpl_

Type name of implementation structure.

Definition at line 60 of file StmSemaphoreAdtDoc.h.

typedef StmSemaphoreImpl_* StmSemaphore

Pointer to implementation.

Examples:
semaphoretest.c.

Definition at line 63 of file StmSemaphoreAdtDoc.h.

typedef const StmSemaphoreImpl_* ConstStmSemaphore

Pointer to constant implementation.

Definition at line 66 of file StmSemaphoreAdtDoc.h.


Function Documentation

StmSemaphore stmSemaphoreCreate ( const char *  name,
unsigned int  value,
unsigned int  attach 
)

Creation of a new StmSemaphore object.

Parameters:
[in] name The name of the StmSemaphore 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] value Initial value of the semaphore named by name, if it did not already exist in the system.
[in] attach Attach mode:
  • StmNoSystemFlag: Error causing the variable errno to be set to EINVAL.
  • StmAttachExisting: It is an error, if a semaphore named by name does not already exist in the system.
  • StmAttachCreated: It is an error, if a semaphore named by name already exists in the system.
  • StmAttach: If a semaphore named by name does not already exist in the system, it is created.
Effects:
On success the function creates a valid StmSemaphore object. This object has to be used as argument of the other StmSemaphore functions.
If a semaphore named by name does not yet exist in the system, it is created with value as its initial value and attached to the StmSemaphore object created, if attach allows so.
If a semaphore named by name already exists in the system, it is attached to the StmSemaphore object created, if attach allows so, and value is ignored in that case.
Note:
On Win32 systems value must not be greater than LONG_MAX.

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.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The StmSemaphore object created on success.

See also:
stmSemaphoreDestroy(), stmSemaphoreName().
Examples:
semaphoretest.c.

Referenced by main().

int stmSemaphoreDestroy ( StmSemaphore  semaphore  ) 

Destruction of the StmSemaphore object semaphore.

Parameters:
[in] semaphore The StmSemaphore object to be destroyed.
Effects:
The function destroys the StmSemaphore object semaphore. If semaphore represented the last reference in the system to the underlying semaphore, also that semaphore is destroyed.
It is no error to call the function for a NULL StmSemaphore object in which case the function does nothing.
Returns:
-1 on error. Then the variable errno contains the error's cause and the StmSemaphore object is not destroyed.

0 on success.

See also:
stmSemaphoreCreate().
Examples:
semaphoretest.c.

Referenced by main().

int stmSemaphoreAdjustChild ( StmSemaphore  semaphore  ) 

Adjust the StmSemaphore object semaphore after a fork system call.

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

Get the name of the StmSemaphore object semaphore.

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

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

See also:
stmSemaphoreCreate().
Examples:
semaphoretest.c.

Referenced by main().

int stmSemaphoreAcquire ( StmSemaphore  semaphore  ) 

Acquire the StmSemaphore object semaphore.

Parameters:
[in] semaphore The StmSemaphore object to acquire.
Effects:
The calling thread blocks until it can acquire semaphore. That is the case, if the value of semaphore before the operation is greater than 0. Then the value of semaphore is atomically decremented by 1 and semaphore is locked, if it reaches 0.
Returns:
0 on success.

-1 on error. Then the variable errno contains the error's cause and the state of semaphore is unchanged.

See also:
stmSemaphoreTryAcquire(), stmSemaphoreTimedAcquire(), stmSemaphoreRelease().

int stmSemaphoreTryAcquire ( StmSemaphore  semaphore  ) 

Try to acquire the StmSemaphore object semaphore.

Parameters:
[in] semaphore The StmSemaphore object to acquire.
Effects:
The calling thread tries to acquire semaphore without blocking. That is successful, if the value of semaphore before the operation is greater than 0. Then the value of semaphore is atomically decremented by 1 and semaphore is locked, if it reaches 0.
Returns:
0, if semaphore could be acquired.

1, if semaphore could not be acquired. Then the variable errno is set to EAGAIN.

-1 on error. Then the variable errno contains the error's cause and the state of semaphore is unchanged.

See also:
stmSemaphoreAcquire(), stmSemaphoreTimedAcquire(), stmSemaphoreRelease().

int stmSemaphoreTimedAcquire ( StmSemaphore  semaphore,
StmInt64  absTimeMs 
)

Try to acquire the StmSemaphore object semaphore till the number absTimeMs of milliseconds elapsed since the Epoch (1970-01-01).

Parameters:
[in] semaphore The StmSemaphore object to acquire.
[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 acquire semaphore or till absTimeMs have been elapsed since the Epoch. Acquisition is successful, once the value of semaphore is greater than 0 before the timeout defined by absTimeMs occurs. Then the value of semaphore is atomically decremented by 1 and semaphore is locked, if it reaches 0.
Returns:
0, if semaphore could be acquired.

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

-1 on error. Then the variable errno contains the error's cause and the state of semaphore is unchanged.

See also:
stmSemaphoreAcquire(), stmSemaphoreTryAcquire(), stmSemaphoreRelease().
Examples:
semaphoretest.c.

Referenced by main().

int stmSemaphoreRelease ( StmSemaphore  semaphore  ) 

Release the StmSemaphore object semaphore.

Parameters:
[in] semaphore The StmSemaphore object to release.
Effects:
The calling thread unlocks the semaphore by incrementing its value. If any thread was blocked waiting for the semaphore to become unlocked the value of semaphore atomically is decremented immediately and that thread acquires semaphore.
Returns:
0 on success.

-1 on error. Then the variable errno contains the error's cause and the state of semaphore is unchanged.

See also:
stmSemaphoreAcquire(), stmSemaphoreTryAcquire(), stmSemaphoreTimedAcquire().
Examples:
semaphoretest.c.

Referenced by main().

int main ( int  argc,
char **  argv 
)

Main function implementing the command semaphoretest.

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 semaphoretest.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).