Home Libraries Author Links

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

Collaboration diagram for StmSharedMemory<ItemType> Example:

Detailed Description

Example of an abstract shared memory type with the abstract item type SampleItemType.

SampleSharedMemory.


Files

file  sharedmemorytest.c
 Usage sample and test of the Abstract Data Type StmSharedMemory<ItemType>.
file  StmSharedMemorySampleItemTypeDoc.h
 Documentation of the abstract shared memory type StmSharedMemorySampleItemType.
file  SampleItemTypeAdtDoc.h
 Documentation of the abstract structure data type type SampleItemType.

Data Structures

struct  SampleItemTypeImpl_
 Implementation structure of the abstract data type SampleItemType. More...

StmSharedMemorySampleItemType Representation

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

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

typedef struct
StmSharedMemorySampleItemTypeImpl_ * 
StmSharedMemorySampleItemType
 Pointer to implementation.
typedef struct
StmSharedMemorySampleItemTypeImpl_ * 
ConstStmSharedMemorySampleItemType
 Pointer to constant implementation.

SampleItemType Representation

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

typedef struct SampleItemTypeImpl_ SampleItemTypeImpl_
 Type name of implementation structure.
typedef SampleItemTypeImpl_SampleItemType
 Pointer to implementation.
typedef const SampleItemTypeImpl_ConstSampleItemType
 Pointer to constant implementation.

StmSharedMemorySampleItemType Creation and Destruction

static
StmSharedMemorySampleItemType 
stmSharedMemorySampleItemTypeCreate (const char *name, unsigned int flags, void *data)
 Creation of a new StmSharedMemorySampleItemType object.
static int stmSharedMemorySampleItemTypeDestroy (StmSharedMemorySampleItemType shm)
 Destruction of the StmSharedMemorySampleItemType object shm.

StmSharedMemorySampleItemType Method Functions

static int stmSharedMemorySampleItemTypeInitStatus (StmSharedMemorySampleItemType shm)
 Get the initialization status of the shared memory SampleItemType object.
static int stmSharedMemorySampleItemTypeAdjustChild (StmSharedMemorySampleItemType shm)
 Adjust the shared memory SampleItemType object after a fork system call.
static const char * stmSharedMemorySampleItemTypeName (StmSharedMemorySampleItemType shm)
 Get the name of the shared memory SampleItemType object.
static SampleItemType stmSharedMemorySampleItemTypeItem (StmSharedMemorySampleItemType shm)
 Get the shared memory SampleItemType object.
static SampleItemType stmSharedMemorySampleItemTypeLock (StmSharedMemorySampleItemType shm)
 Lock and get the shared memory SampleItemType object.
static SampleItemType stmSharedMemorySampleItemTypeTryLock (StmSharedMemorySampleItemType shm)
 Try to lock and get the shared memory SampleItemType object.
static SampleItemType stmSharedMemorySampleItemTypeTimedLock (StmSharedMemorySampleItemType shm, StmInt64 absTimeMs)
 Try to lock and get the shared memory SampleItemType object till the number absTimeMs of milliseconds elapsed since the Epoch (1970-01-01).
static int stmSharedMemorySampleItemTypeUnlock (StmSharedMemorySampleItemType shm)
 Unlock the shared memory SampleItemType object.

Functions

static int stmSampleItemTypeInit (SampleItemType item, void *data)
 SampleItemType initialization function required by the StmSharedMemoryItemDefine macro.
static int stmSampleItemTypeDeinit (SampleItemType item)
 SampleItemType deinitialization function required by the StmSharedMemoryItemDefine macro.
int main (int argc, char **argv)
 Main function implementing the command sharedmemorytest.

Variables

static
StmSharedMemorySampleItemType 
shm
 Definition of the shared memory type and its method functions.


Typedef Documentation

typedef struct StmSharedMemorySampleItemTypeImpl_* StmSharedMemorySampleItemType

Pointer to implementation.

Examples:
sharedmemorytest.c.

Definition at line 69 of file StmSharedMemorySampleItemTypeDoc.h.

typedef struct StmSharedMemorySampleItemTypeImpl_* ConstStmSharedMemorySampleItemType

Pointer to constant implementation.

Definition at line 74 of file StmSharedMemorySampleItemTypeDoc.h.

typedef struct SampleItemTypeImpl_ SampleItemTypeImpl_

Type name of implementation structure.

Definition at line 60 of file SampleItemTypeAdtDoc.h.

typedef SampleItemTypeImpl_* SampleItemType

Pointer to implementation.

Definition at line 63 of file SampleItemTypeAdtDoc.h.

typedef const SampleItemTypeImpl_* ConstSampleItemType

Pointer to constant implementation.

Definition at line 66 of file SampleItemTypeAdtDoc.h.


Function Documentation

static int stmSampleItemTypeInit ( SampleItemType  item,
void *  data 
) [static]

SampleItemType initialization function required by the StmSharedMemoryItemDefine macro.

Examples:
sharedmemorytest.c.

Definition at line 103 of file sharedmemorytest.c.

static int stmSampleItemTypeDeinit ( SampleItemType  item  )  [static]

SampleItemType deinitialization function required by the StmSharedMemoryItemDefine macro.

Examples:
sharedmemorytest.c.

Definition at line 113 of file sharedmemorytest.c.

int main ( int  argc,
char **  argv 
)

Main function implementing the command sharedmemorytest.

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 sharedmemorytest.c.

static StmSharedMemorySampleItemType stmSharedMemorySampleItemTypeCreate ( const char *  name,
unsigned int  flags,
void *  data 
) [static]

Creation of a new StmSharedMemorySampleItemType object.

Parameters:
[in] name If non-NULL the name of the shared memory object to be created. That name shall be a valid path name 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.
[in] flags 
  • Attach mode flags & StmAttachMask:
    • StmNoSystemFlag: Error causing the variable errno to be set to EINVAL.
    • StmAttachExisting: It is an error, if a shared memory named by name does not already exist in the system.
    • StmAttachCreated: It is an error, if a shared memory named by name already exists in the system.
    • StmAttach: If a shared memory named by name does not already exist in the system, it is created.
  • Keep locked flag flags & StmKeepLocked:
    • StmFalse: Unlock the shared memory object after creation.
    • StmTrue: Keep the shared memory object locked after successfull creation.
[in] data If non-NULL the address of caller supplied data used as second argument for the function stmSampleItemTypeInit(). It is no error, if data is NULL.
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.
Effects:
On success the function creates a valid StmSharedMemorySampleItemType object. This object has to be used as argument of the other StmSharedMemorySampleItemType functions.
If the shared memory SampleItemType object does not yet exist in the system, it is created and attached to the StmSharedMemorySampleItemType object created, if mode allows so and its method function stmSampleItemTypeInit() 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 shared memory SampleItemType object, where a value of 0 shall mean success.
If the shared memory SampleItemType object already exists in the system, it is attached to the StmSharedMemorySampleItemType object created, if mode allows so.
During creation a timeout of 100 milliseconds is used.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The StmSharedMemorySampleItemType object created on success.

See also:
stmSharedMemorySampleItemTypeDestroy(), stmSharedMemorySampleItemTypeInitStatus().
Examples:
sharedmemorytest.c.

Referenced by main().

static int stmSharedMemorySampleItemTypeDestroy ( StmSharedMemorySampleItemType  shm  )  [static]

Destruction of the StmSharedMemorySampleItemType object shm.

Parameters:
[in] shm The StmSharedMemorySampleItemType object to be destroyed.
Effects:
If shm is NULL (invalid), the function does nothing.
Else if shm represents the last reference in the system to the shared memory SampleItemType object, the method function stmSampleItemTypeDeinit() 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 shared memory SampleItemType object is destroyed.
On success the StmSharedMemorySampleItemType object is destroyed. If shm represented the last reference in the system to the shared memory SampleItemType 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:
stmSharedMemorySampleItemTypeCreate(), stmSharedMemorySampleItemTypeInitStatus().
Examples:
sharedmemorytest.c.

Referenced by main().

static int stmSharedMemorySampleItemTypeInitStatus ( StmSharedMemorySampleItemType  shm  )  [static]

Get the initialization status of the shared memory SampleItemType object.

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

The initialization status of the shared memory SampleItemType object of shm being 0 for OK.

See also:
stmSharedMemorySampleItemTypeCreate(), stmSharedMemorySampleItemTypeDestroy().

static int stmSharedMemorySampleItemTypeAdjustChild ( StmSharedMemorySampleItemType  shm  )  [static]

Adjust the shared memory SampleItemType object after a fork system call.

Parameters:
[in] shm The StmSharedMemorySampleItemType object.
Effects:
Increments the reference count of the shared memory SampleItemType of shm 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 const char* stmSharedMemorySampleItemTypeName ( StmSharedMemorySampleItemType  shm  )  [static]

Get the name of the shared memory SampleItemType object.

Parameters:
[in] shm The StmSharedMemorySampleItemType object.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The name of the shared memory SampleItemType object as it is adjusted by the system on success.

See also:
stmSharedMemorySampleItemTypeCreate().
Examples:
sharedmemorytest.c.

Referenced by main().

static SampleItemType stmSharedMemorySampleItemTypeItem ( StmSharedMemorySampleItemType  shm  )  [static]

Get the shared memory SampleItemType object.

Parameters:
[in] shm The StmSharedMemorySampleItemType object.
Returns:
NULL on error. Then the reference count of the shared memory SampleItemType object is > 0 and the variable errno contains the error's cause.

The shared memory SampleItemType object of shm on success.

Note:
The shared memory SampleItemType object of shm returned on success is not locked. Access synchronization has to be done by the user.
See also:
stmSharedMemorySampleItemTypeLock (), stmSharedMemorySampleItemTypeTryLock (), stmSharedMemorySampleItemTypeTimedLock (), stmSharedMemorySampleItemTypeUnlock ().

static SampleItemType stmSharedMemorySampleItemTypeLock ( StmSharedMemorySampleItemType  shm  )  [static]

Lock and get the shared memory SampleItemType object.

Parameters:
[in] shm The StmSharedMemorySampleItemType object.
Effects:
Blocks the calling thread until the shared memory SampleItemType object could be locked. It is an error, if the shared memory SampleItemType 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 shared memory SampleItemType object of shm on success.

See also:
stmSharedMemorySampleItemTypeItem (), stmSharedMemorySampleItemTypeTryLock (), stmSharedMemorySampleItemTypeTimedLock (), stmSharedMemorySampleItemTypeUnlock ().
Examples:
sharedmemorytest.c.

Referenced by main().

static SampleItemType stmSharedMemorySampleItemTypeTryLock ( StmSharedMemorySampleItemType  shm  )  [static]

Try to lock and get the shared memory SampleItemType object.

Parameters:
[in] shm The StmSharedMemorySampleItemType object.
Effects:
The function succeeds, if the calling thread can lock the shared memory SampleItemType object without blocking. It is an error, if the shared memory SampleItemType 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 shared memory SampleItemType object of shm is already locked.

The locked shared memory SampleItemType object of shm on success.

See also:
stmSharedMemorySampleItemTypeItem (), stmSharedMemorySampleItemTypeLock (), stmSharedMemorySampleItemTypeTimedLock (), stmSharedMemorySampleItemTypeUnlock ().

static SampleItemType stmSharedMemorySampleItemTypeTimedLock ( StmSharedMemorySampleItemType  shm,
StmInt64  absTimeMs 
) [static]

Try to lock and get the shared memory SampleItemType object till the number absTimeMs of milliseconds elapsed since the Epoch (1970-01-01).

Parameters:
[in] shm The StmSharedMemorySampleItemType 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 shared memory SampleItemType object or till absTimeMs have been elapsed since the Epoch. It is an error, if the shared memory SampleItemType 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 shared memory SampleItemType object of shm on success.

See also:
stmSharedMemorySampleItemTypeItem (), stmSharedMemorySampleItemTypeLock (), stmSharedMemorySampleItemTypeTryLock (), stmSharedMemorySampleItemTypeUnlock ().

static int stmSharedMemorySampleItemTypeUnlock ( StmSharedMemorySampleItemType  shm  )  [static]

Unlock the shared memory SampleItemType object.

Parameters:
[in] shm The StmSharedMemorySampleItemType object.
Effects:
Unlocks the shared memory SampleItemType object. It is an error, if the shared memory SampleItemType 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 shared memory SampleItemType object of shm was successfully unlocked.

See also:
stmSharedMemorySampleItemTypeItem (), stmSharedMemorySampleItemTypeLock (), stmSharedMemorySampleItemTypeTryLock (), stmSharedMemorySampleItemTypeTimedLock ().
Examples:
sharedmemorytest.c.

Referenced by main().


Variable Documentation

StmSharedMemorySampleItemType shm [static]

Definition of the shared memory type and its method functions.

The shared memory object.

Examples:
sharedmemorytest.c.

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