Home Libraries Author Links

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

Collaboration diagram for Abstract Data Type StmProcessSemaphore:

Detailed Description

A StmProcessSemaphore object provides a counting semaphore serving as synchronization primitive between the threads of the calling processes.

ProcessSemaphore.

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

StmProcessSemaphore objects with the value NULL are invalid or undefined.

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

static StmProcessSemaphore semaphore;

static int counter;

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

int main ()
{
    static int id [] = {1, 2};
    semaphore = stmProcessSemaphoreCreate (1);
    {
        StmThread thread1 = stmThreadCreate (handler, id + 0);
        StmThread thread2 = stmThreadCreate (handler, id + 1);
        stmThreadJoin (thread1, NULL);
        stmThreadJoin (thread2, NULL);
        stmThreadDestroy (thread1);
        stmThreadDestroy (thread2);
    }
    stmProcessSemaphoreDestroy (semaphore);
    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  processsemaphoretest.c
 Usage sample and test of the Abstract Data Type StmProcessSemaphore.
file  StmProcessSemaphoreAdtDoc.h
 Documentation of the abstract structure data type type StmProcessSemaphore.

StmProcessSemaphore Representation

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

typedef struct
StmProcessSemaphoreImpl_ 
StmProcessSemaphoreImpl_
 Type name of implementation structure.
typedef StmProcessSemaphoreImpl_StmProcessSemaphore
 Pointer to implementation.
typedef const
StmProcessSemaphoreImpl_
ConstStmProcessSemaphore
 Pointer to constant implementation.

StmProcessSemaphore Creation and Destruction

StmProcessSemaphore stmProcessSemaphoreCreate (unsigned int value)
 Creation of a new StmProcessSemaphore object.
int stmProcessSemaphoreDestroy (StmProcessSemaphore semaphore)
 Destruction of the StmProcessSemaphore object semaphore.

StmProcessSemaphore Method Functions

int stmProcessSemaphoreAcquire (StmProcessSemaphore semaphore)
 Acquire the StmProcessSemaphore object semaphore.
int stmProcessSemaphoreTryAcquire (StmProcessSemaphore semaphore)
 Try to acquire the StmProcessSemaphore object semaphore.
int stmProcessSemaphoreTimedAcquire (StmProcessSemaphore semaphore, StmInt64 absTimeMs)
 Try to acquire the StmProcessSemaphore object semaphore till the number absTimeMs of milliseconds elapsed since the Epoch (1970-01-01).
int stmProcessSemaphoreRelease (StmProcessSemaphore semaphore)
 Release the StmProcessSemaphore object semaphore.

Functions

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

Variables

static StmProcessSemaphore semaphore
 The process semaphore object.
static int counter
 The shared resource.


Typedef Documentation

typedef struct StmProcessSemaphoreImpl_ StmProcessSemaphoreImpl_

Type name of implementation structure.

Definition at line 60 of file StmProcessSemaphoreAdtDoc.h.

typedef StmProcessSemaphoreImpl_* StmProcessSemaphore

Pointer to implementation.

Examples:
processsemaphoretest.c.

Definition at line 63 of file StmProcessSemaphoreAdtDoc.h.

typedef const StmProcessSemaphoreImpl_* ConstStmProcessSemaphore

Pointer to constant implementation.

Definition at line 66 of file StmProcessSemaphoreAdtDoc.h.


Function Documentation

StmProcessSemaphore stmProcessSemaphoreCreate ( unsigned int  value  ) 

Creation of a new StmProcessSemaphore object.

Parameters:
[in] value The initial value of the semaphore created.
Note:
On Win32 systems value must not be greater than LONG_MAX.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The StmProcessSemaphore object created on success.

See also:
stmProcessSemaphoreDestroy().
Examples:
processsemaphoretest.c.

Referenced by main().

int stmProcessSemaphoreDestroy ( StmProcessSemaphore  semaphore  ) 

Destruction of the StmProcessSemaphore object semaphore.

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

0 on success.

See also:
stmProcessSemaphoreCreate().
Examples:
processsemaphoretest.c.

Referenced by main().

int stmProcessSemaphoreAcquire ( StmProcessSemaphore  semaphore  ) 

Acquire the StmProcessSemaphore object semaphore.

Parameters:
[in] semaphore The StmProcessSemaphore 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:
stmProcessSemaphoreTryAcquire(), stmProcessSemaphoreTimedAcquire(), stmProcessSemaphoreRelease().
Examples:
processsemaphoretest.c.

Referenced by handler().

int stmProcessSemaphoreTryAcquire ( StmProcessSemaphore  semaphore  ) 

Try to acquire the StmProcessSemaphore object semaphore.

Parameters:
[in] semaphore The StmProcessSemaphore 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:
stmProcessSemaphoreAcquire(), stmProcessSemaphoreTimedAcquire(), stmProcessSemaphoreRelease().

int stmProcessSemaphoreTimedAcquire ( StmProcessSemaphore  semaphore,
StmInt64  absTimeMs 
)

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

Parameters:
[in] semaphore The StmProcessSemaphore 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:
stmProcessSemaphoreAcquire(), stmProcessSemaphoreTryAcquire(), stmProcessSemaphoreRelease().

int stmProcessSemaphoreRelease ( StmProcessSemaphore  semaphore  ) 

Release the StmProcessSemaphore object semaphore.

Parameters:
[in] semaphore The StmProcessSemaphore 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:
stmProcessSemaphoreAcquire(), stmProcessSemaphoreTryAcquire(), stmProcessSemaphoreTimedAcquire().
Examples:
processsemaphoretest.c.

Referenced by handler().

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

The worker thread function.

Definition at line 83 of file processsemaphoretest.c.

int main (  ) 

Main function implementing the command processsemaphoretest.

Definition at line 99 of file processsemaphoretest.c.


Variable Documentation

StmProcessSemaphore semaphore [static]

The process semaphore object.

Examples:
processsemaphoretest.c, and semaphoretest.c.

Definition at line 75 of file processsemaphoretest.c.

Referenced by handler(), and main().

int counter [static]

The shared resource.

Definition at line 79 of file processsemaphoretest.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).