Home Libraries Author Links

StmSystemUniqueSampleMboxType Implementation
[StmSystemUnique<ItemType> Example]

Collaboration diagram for StmSystemUniqueSampleMboxType Implementation:

Detailed Description

Implementation of the abstract system unique type StmSystemUniqueSampleMboxType.


Files

file  StmSharedMemorySampleMboxTypeDoc.h
 Documentation of the abstract shared memory type StmSharedMemorySampleMboxType.

StmSharedMemorySampleMboxType Representation

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

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

typedef struct
StmSharedMemorySampleMboxTypeImpl_ * 
StmSharedMemorySampleMboxType
 Pointer to implementation.
typedef struct
StmSharedMemorySampleMboxTypeImpl_ * 
ConstStmSharedMemorySampleMboxType
 Pointer to constant implementation.

StmSharedMemorySampleMboxType Creation and Destruction

static
StmSharedMemorySampleMboxType 
stmSharedMemorySampleMboxTypeCreate (const char *name, unsigned int flags, void *data)
 Creation of a new StmSharedMemorySampleMboxType object.
static int stmSharedMemorySampleMboxTypeDestroy (StmSharedMemorySampleMboxType shm)
 Destruction of the StmSharedMemorySampleMboxType object shm.

StmSharedMemorySampleMboxType Method Functions

static int stmSharedMemorySampleMboxTypeInitStatus (StmSharedMemorySampleMboxType shm)
 Get the initialization status of the shared memory SampleMboxType object.
static int stmSharedMemorySampleMboxTypeAdjustChild (StmSharedMemorySampleMboxType shm)
 Adjust the shared memory SampleMboxType object after a fork system call.
static const char * stmSharedMemorySampleMboxTypeName (StmSharedMemorySampleMboxType shm)
 Get the name of the shared memory SampleMboxType object.
static SampleMboxType stmSharedMemorySampleMboxTypeItem (StmSharedMemorySampleMboxType shm)
 Get the shared memory SampleMboxType object.
static SampleMboxType stmSharedMemorySampleMboxTypeLock (StmSharedMemorySampleMboxType shm)
 Lock and get the shared memory SampleMboxType object.
static SampleMboxType stmSharedMemorySampleMboxTypeTryLock (StmSharedMemorySampleMboxType shm)
 Try to lock and get the shared memory SampleMboxType object.
static SampleMboxType stmSharedMemorySampleMboxTypeTimedLock (StmSharedMemorySampleMboxType shm, StmInt64 absTimeMs)
 Try to lock and get the shared memory SampleMboxType object till the number absTimeMs of milliseconds elapsed since the Epoch (1970-01-01).
static int stmSharedMemorySampleMboxTypeUnlock (StmSharedMemorySampleMboxType shm)
 Unlock the shared memory SampleMboxType object.


Typedef Documentation

typedef struct StmSharedMemorySampleMboxTypeImpl_* StmSharedMemorySampleMboxType

Pointer to implementation.

Definition at line 69 of file StmSharedMemorySampleMboxTypeDoc.h.

typedef struct StmSharedMemorySampleMboxTypeImpl_* ConstStmSharedMemorySampleMboxType

Pointer to constant implementation.

Definition at line 74 of file StmSharedMemorySampleMboxTypeDoc.h.


Function Documentation

static StmSharedMemorySampleMboxType stmSharedMemorySampleMboxTypeCreate ( const char *  name,
unsigned int  flags,
void *  data 
) [static]

Creation of a new StmSharedMemorySampleMboxType 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 stmSampleMboxTypeInit(). 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 StmSharedMemorySampleMboxType object. This object has to be used as argument of the other StmSharedMemorySampleMboxType functions.
If the shared memory SampleMboxType object does not yet exist in the system, it is created and attached to the StmSharedMemorySampleMboxType object created, if mode allows so 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 shared memory SampleMboxType object, where a value of 0 shall mean success.
If the shared memory SampleMboxType object already exists in the system, it is attached to the StmSharedMemorySampleMboxType 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 StmSharedMemorySampleMboxType object created on success.

See also:
stmSharedMemorySampleMboxTypeDestroy(), stmSharedMemorySampleMboxTypeInitStatus().

static int stmSharedMemorySampleMboxTypeDestroy ( StmSharedMemorySampleMboxType  shm  )  [static]

Destruction of the StmSharedMemorySampleMboxType object shm.

Parameters:
[in] shm The StmSharedMemorySampleMboxType 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 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 shared memory SampleMboxType object is destroyed.
On success the StmSharedMemorySampleMboxType object is destroyed. If shm represented the last reference in the system to the shared memory 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:
stmSharedMemorySampleMboxTypeCreate(), stmSharedMemorySampleMboxTypeInitStatus().

static int stmSharedMemorySampleMboxTypeInitStatus ( StmSharedMemorySampleMboxType  shm  )  [static]

Get the initialization status of the shared memory SampleMboxType object.

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

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

See also:
stmSharedMemorySampleMboxTypeCreate(), stmSharedMemorySampleMboxTypeDestroy().

static int stmSharedMemorySampleMboxTypeAdjustChild ( StmSharedMemorySampleMboxType  shm  )  [static]

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

Parameters:
[in] shm The StmSharedMemorySampleMboxType object.
Effects:
Increments the reference count of the shared memory SampleMboxType 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* stmSharedMemorySampleMboxTypeName ( StmSharedMemorySampleMboxType  shm  )  [static]

Get the name of the shared memory SampleMboxType object.

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

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

See also:
stmSharedMemorySampleMboxTypeCreate().

static SampleMboxType stmSharedMemorySampleMboxTypeItem ( StmSharedMemorySampleMboxType  shm  )  [static]

Get the shared memory SampleMboxType object.

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

The shared memory SampleMboxType object of shm on success.

Note:
The shared memory SampleMboxType object of shm returned on success is not locked. Access synchronization has to be done by the user.
See also:
stmSharedMemorySampleMboxTypeLock (), stmSharedMemorySampleMboxTypeTryLock (), stmSharedMemorySampleMboxTypeTimedLock (), stmSharedMemorySampleMboxTypeUnlock ().

static SampleMboxType stmSharedMemorySampleMboxTypeLock ( StmSharedMemorySampleMboxType  shm  )  [static]

Lock and get the shared memory SampleMboxType object.

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

See also:
stmSharedMemorySampleMboxTypeItem (), stmSharedMemorySampleMboxTypeTryLock (), stmSharedMemorySampleMboxTypeTimedLock (), stmSharedMemorySampleMboxTypeUnlock ().

static SampleMboxType stmSharedMemorySampleMboxTypeTryLock ( StmSharedMemorySampleMboxType  shm  )  [static]

Try to lock and get the shared memory SampleMboxType object.

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

The locked shared memory SampleMboxType object of shm on success.

See also:
stmSharedMemorySampleMboxTypeItem (), stmSharedMemorySampleMboxTypeLock (), stmSharedMemorySampleMboxTypeTimedLock (), stmSharedMemorySampleMboxTypeUnlock ().

static SampleMboxType stmSharedMemorySampleMboxTypeTimedLock ( StmSharedMemorySampleMboxType  shm,
StmInt64  absTimeMs 
) [static]

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

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

See also:
stmSharedMemorySampleMboxTypeItem (), stmSharedMemorySampleMboxTypeLock (), stmSharedMemorySampleMboxTypeTryLock (), stmSharedMemorySampleMboxTypeUnlock ().

static int stmSharedMemorySampleMboxTypeUnlock ( StmSharedMemorySampleMboxType  shm  )  [static]

Unlock the shared memory SampleMboxType object.

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

See also:
stmSharedMemorySampleMboxTypeItem (), stmSharedMemorySampleMboxTypeLock (), stmSharedMemorySampleMboxTypeTryLock (), stmSharedMemorySampleMboxTypeTimedLock ().


© Copyright Tom Michaelis 2002-2007

Distributed under the SysToMath Software License (See the accompanying file license.txt or a copy at www.SysToMath.com).