Home Libraries Author Links

StmSystemUnique<ItemType> Example
[Abstract Data Type Family StmSystemUnique<ItemType>]

Collaboration diagram for StmSystemUnique<ItemType> Example:

Detailed Description

Example of an abstract system-unique type with the abstract item type SampleMboxType.

SampleSystemUnique.


Files

file  systemuniquetest.c
 Usage sample and test of the Abstract Data Type StmSystemUnique<ItemType>.
file  StmSystemUniqueSampleMboxTypeDoc.h
 Documentation of the abstract system-unique singelton type StmSystemUniqueSampleMboxType.
file  SampleMboxTypeAdtDoc.h
 Documentation of the abstract structure data type type SampleMboxType.

Modules

 StmSystemUniqueSampleMboxType Implementation
 Implementation of the abstract system unique type StmSystemUniqueSampleMboxType.

Data Structures

struct  SampleMboxTypeImpl_
 Implementation structure of the abstract data type SampleMboxType. More...

StmSystemUniqueSampleMboxType Representation

An object of abstract data type StmSystemUniqueSampleMboxType is represented as a StmSharedMemorySampleMboxType object.

Valid objects of type StmSystemUniqueSampleMboxType can be achieved only as return values of stmSystemUniqueSampleMboxTypeCreate(). Moreover, variables of type StmSystemUniqueSampleMboxType may have the value NULL meaning invalid or undefined.

typedef
StmSharedMemorySampleMboxType 
StmSystemUniqueSampleMboxType
 Object type.
typedef
ConstStmSharedMemorySampleMboxType 
ConstStmSystemUniqueSampleMboxType
 Constant object type.

SampleMboxType Representation

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

typedef struct SampleMboxTypeImpl_ SampleMboxTypeImpl_
 Type name of implementation structure.
typedef SampleMboxTypeImpl_SampleMboxType
 Pointer to implementation.
typedef const SampleMboxTypeImpl_ConstSampleMboxType
 Pointer to constant implementation.

StmSystemUniqueSampleMboxType Creation and Destruction

static
StmSystemUniqueSampleMboxType 
stmSystemUniqueSampleMboxTypeCreate (void *data)
 Creation of a new StmSystemUniqueSampleMboxType object.
static int stmSystemUniqueSampleMboxTypeDestroy (StmSystemUniqueSampleMboxType sui)
 Destruction of the StmSystemUniqueSampleMboxType object sui.

StmSystemUniqueSampleMboxType Method Functions

static int stmSystemUniqueSampleMboxTypeInitStatus (StmSystemUniqueSampleMboxType sui)
 Get the initialization status of the system-unique SampleMboxType object.
static int stmSystemUniqueSampleMboxTypeAdjustChild (StmSystemUniqueSampleMboxType sui)
 Adjust the system-unique SampleMboxType object after a fork system call.
static SampleMboxType stmSystemUniqueSampleMboxTypeItem (StmSystemUniqueSampleMboxType sui)
 Get the system-unique SampleMboxType object.
static SampleMboxType stmSystemUniqueSampleMboxTypeLock (StmSystemUniqueSampleMboxType sui)
 Lock and get the system-unique SampleMboxType object.
static SampleMboxType stmSystemUniqueSampleMboxTypeTryLock (StmSystemUniqueSampleMboxType sui)
 Try to lock and get the system-unique SampleMboxType object.
static SampleMboxType stmSystemUniqueSampleMboxTypeTimedLock (StmSystemUniqueSampleMboxType sui, StmInt64 absTimeMs)
 Try to lock and get the system-unique SampleMboxType object till the number absTimeMs of milliseconds elapsed since the Epoch (1970-01-01).
static int stmSystemUniqueSampleMboxTypeUnlock (StmSystemUniqueSampleMboxType sui)
 Unlock the system-unique SampleMboxType object.

Functions

static int stmSampleMboxTypeInit (SampleMboxType item, void *data)
 SampleMboxType initialization function required by the StmSystemUniqueItemDefine macro.
static int stmSampleMboxTypeDeinit (SampleMboxType item)
 SampleMboxType deinitialization function required by the StmSystemUniqueItemDefine macro.
int main (int argc, char **argv)
 Main function implementing the command systemuniquetest.

Variables

static
StmSystemUniqueSampleMboxType 
sui
 Definition of the system-unique type and its method functions.


Typedef Documentation

typedef StmSharedMemorySampleMboxType StmSystemUniqueSampleMboxType

Object type.

Examples:
systemuniquetest.c.

Definition at line 86 of file StmSystemUniqueSampleMboxTypeDoc.h.

typedef ConstStmSharedMemorySampleMboxType ConstStmSystemUniqueSampleMboxType

Constant object type.

Definition at line 91 of file StmSystemUniqueSampleMboxTypeDoc.h.

typedef struct SampleMboxTypeImpl_ SampleMboxTypeImpl_

Type name of implementation structure.

Definition at line 60 of file SampleMboxTypeAdtDoc.h.

typedef SampleMboxTypeImpl_* SampleMboxType

Pointer to implementation.

Definition at line 63 of file SampleMboxTypeAdtDoc.h.

typedef const SampleMboxTypeImpl_* ConstSampleMboxType

Pointer to constant implementation.

Definition at line 66 of file SampleMboxTypeAdtDoc.h.


Function Documentation

static int stmSampleMboxTypeInit ( SampleMboxType  item,
void *  data 
) [static]

SampleMboxType initialization function required by the StmSystemUniqueItemDefine macro.

Examples:
systemuniquetest.c.

Definition at line 103 of file systemuniquetest.c.

static int stmSampleMboxTypeDeinit ( SampleMboxType  item  )  [static]

SampleMboxType deinitialization function required by the StmSystemUniqueItemDefine macro.

Examples:
systemuniquetest.c.

Definition at line 113 of file systemuniquetest.c.

int main ( int  argc,
char **  argv 
)

Main function implementing the command systemuniquetest.

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 138 of file systemuniquetest.c.

static StmSystemUniqueSampleMboxType stmSystemUniqueSampleMboxTypeCreate ( void *  data  )  [static]

Creation of a new StmSystemUniqueSampleMboxType object.

Parameters:
[in] data If non-NULL the address of caller supplied data used as second argument for the function stmSampleMboxTypeInit(). It is no error, if data is NULL.
Effects:
On success the function creates a valid StmSystemUniqueSampleMboxType object. This object has to be used as argument of the other StmSystemUniqueSampleMboxType functions.
If the system-unique SampleMboxType object did not yet exist, it is created, attached to the StmSystemUniqueSampleMboxType object created and its method function stmSampleMboxTypeInit() is executed for it and with data as second argument. Then the return value of that method function is stored as the initialization status of the system-unique SampleMboxType object, where a value of 0 shall mean success.
During creation a timout of 100 milliseconds is used.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The StmSystemUniqueSampleMboxType object created on success.

See also:
stmSystemUniqueSampleMboxTypeDestroy(), stmSystemUniqueSampleMboxTypeInitStatus().
Examples:
systemuniquetest.c.

Referenced by main().

static int stmSystemUniqueSampleMboxTypeDestroy ( StmSystemUniqueSampleMboxType  sui  )  [static]

Destruction of the StmSystemUniqueSampleMboxType object sui.

Parameters:
[in] sui The StmSystemUniqueSampleMboxType object to be destroyed.
Effects:
If sui is NULL (invalid), the function does nothing.
Else if sui represents the last reference in the system to the system-unique SampleMboxType object, the method function stmSampleMboxTypeDeinit() is executed for it. It is an error, if that method function does not return 0, in which case that return value is stored as initialization status and the variable errno is set to EFAULT. If the return value was 0, the system-unique SampleMboxType object is destroyed.
On success the StmSystemUniqueSampleMboxType object is destroyed. If sui represented the last reference in the system to the system-unique SampleMboxType object, also the underlying shared memory is released.
During destruction a timout of 100 milliseconds is used.
Returns:
-1 on error. Then the variable errno contains the error's cause.

0 on success.

See also:
stmSystemUniqueSampleMboxTypeCreate(), stmSystemUniqueSampleMboxTypeInitStatus().
Examples:
systemuniquetest.c.

Referenced by main().

static int stmSystemUniqueSampleMboxTypeInitStatus ( StmSystemUniqueSampleMboxType  sui  )  [static]

Get the initialization status of the system-unique SampleMboxType object.

Parameters:
[in] sui The StmSystemUniqueSampleMboxType object.
Returns:
-1 on error. Then the variable errno contains the error's cause.

The initialization status of the system-unique SampleMboxType object of sui being 0 for OK.

See also:
stmSystemUniqueSampleMboxTypeCreate(), stmSystemUniqueSampleMboxTypeDestroy().

static int stmSystemUniqueSampleMboxTypeAdjustChild ( StmSystemUniqueSampleMboxType  sui  )  [static]

Adjust the system-unique SampleMboxType object after a fork system call.

Parameters:
[in] sui The StmSystemUniqueSampleMboxType object.
Effects:
Increments the reference count of the system-unique SampleMboxType of sui 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.

static SampleMboxType stmSystemUniqueSampleMboxTypeItem ( StmSystemUniqueSampleMboxType  sui  )  [static]

Get the system-unique SampleMboxType object.

Parameters:
[in] sui The StmSystemUniqueSampleMboxType object.
Returns:
NULL on error. Then the reference count of the system-unique SampleMboxType object is > 0 and the variable errno contains the error's cause.

The system-unique SampleMboxType object of sui on success.

Note:
The system-unique SampleMboxType object of sui returned on success is not locked. Access synchronization has to be done by the user.
See also:
stmSystemUniqueSampleMboxTypeLock (), stmSystemUniqueSampleMboxTypeTryLock (), stmSystemUniqueSampleMboxTypeTimedLock (), stmSystemUniqueSampleMboxTypeUnlock ().

static SampleMboxType stmSystemUniqueSampleMboxTypeLock ( StmSystemUniqueSampleMboxType  sui  )  [static]

Lock and get the system-unique SampleMboxType object.

Parameters:
[in] sui The StmSystemUniqueSampleMboxType object.
Effects:
Blocks the calling thread until the system-unique SampleMboxType object could be locked. It is an error, if the system-unique SampleMboxType object was already locked in which case errno is set to EBUSY.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The locked system-unique SampleMboxType object of sui on success.

See also:
stmSystemUniqueSampleMboxTypeItem (), stmSystemUniqueSampleMboxTypeTryLock (), stmSystemUniqueSampleMboxTypeTimedLock (), stmSystemUniqueSampleMboxTypeUnlock ().
Examples:
systemuniquetest.c.

Referenced by main().

static SampleMboxType stmSystemUniqueSampleMboxTypeTryLock ( StmSystemUniqueSampleMboxType  sui  )  [static]

Try to lock and get the system-unique SampleMboxType object.

Parameters:
[in] sui The StmSystemUniqueSampleMboxType object.
Effects:
The function succeeds, if the calling thread can lock the system-unique SampleMboxType object without blocking. It is an error, if the system-unique SampleMboxType object was already locked in which case errno is set to EBUSY.
Returns:
NULL on error. Then variable errno contains the error's cause, which is EAGAIN, if the system-unique SampleMboxType object of sui is already locked.

The locked system-unique SampleMboxType object of sui on success.

See also:
stmSystemUniqueSampleMboxTypeItem (), stmSystemUniqueSampleMboxTypeLock (), stmSystemUniqueSampleMboxTypeTimedLock (), stmSystemUniqueSampleMboxTypeUnlock ().

static SampleMboxType stmSystemUniqueSampleMboxTypeTimedLock ( StmSystemUniqueSampleMboxType  sui,
StmInt64  absTimeMs 
) [static]

Try to lock and get the system-unique SampleMboxType object till the number absTimeMs of milliseconds elapsed since the Epoch (1970-01-01).

Parameters:
[in] sui The StmSystemUniqueSampleMboxType object.
[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 lock the system-unique SampleMboxType object or till absTimeMs have been elapsed since the Epoch. It is an error, if the system-unique SampleMboxType object was already locked in which case errno is set to EBUSY.
Returns:
NULL on error. Then variable errno contains the error's cause, which is ETIMEDOUT, if absTimeMs milliseconds have been elapsed since the Epoch.

The locked system-unique SampleMboxType object of sui on success.

See also:
stmSystemUniqueSampleMboxTypeItem (), stmSystemUniqueSampleMboxTypeLock (), stmSystemUniqueSampleMboxTypeTryLock (), stmSystemUniqueSampleMboxTypeUnlock ().

static int stmSystemUniqueSampleMboxTypeUnlock ( StmSystemUniqueSampleMboxType  sui  )  [static]

Unlock the system-unique SampleMboxType object.

Parameters:
[in] sui The StmSystemUniqueSampleMboxType object.
Effects:
Unlocks the system-unique SampleMboxType object. It is an error, if the system-unique SampleMboxType object was not locked in which case errno is set to EFAULT.
Returns:
-1 on error. Then the variable errno contains the error's cause.

0 if the locked system-unique SampleMboxType object of sui was successfully unlocked.

See also:
stmSystemUniqueSampleMboxTypeItem (), stmSystemUniqueSampleMboxTypeLock (), stmSystemUniqueSampleMboxTypeTryLock (), stmSystemUniqueSampleMboxTypeTimedLock ().
Examples:
systemuniquetest.c.

Referenced by main().


Variable Documentation

StmSystemUniqueSampleMboxType sui [static]

Definition of the system-unique type and its method functions.

The ssytem-unique object.

Examples:
systemuniquetest.c.

Definition at line 124 of file systemuniquetest.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).