OSAPI_SharedMemorySegment

Allow access to a shared memory segment (memory block) so that multiple processes can read-and write a common memory area. More...

Data Structures
struct	OSAPI_SharedMemorySegmentHeader
struct	OSAPI_SharedMemorySegmentHandle

Enumerations
enum	OSAPI_SHMEM_MODE {   OSAPI_SHMEM_MODE_UNKNOWN , OSAPI_SHMEM_MODE_READ , OSAPI_SHMEM_MODE_WRITE , OSAPI_SHMEM_MODE_LOCKABLE ,   OSAPI_SHMEM_MODE_ROBUST }
enum	OSAPI_SHMEM_STATUS { OSAPI_SHMEM_STATUS_OK , OSAPI_SHMEM_STATUS_OWNER_DEAD }
enum	OSAPI_SHMEM_ATTACH_STATUS { OSAPI_SHMEM_ATTACH_STATUS_OK , OSAPI_SHMEM_ATTACH_STATUS_SEGMENT_NOT_FOUND }

Functions
RTI_UINT64	OSAPI_SharedMemorySegment_get_max_size (void)
	Get maximum size of a shared memory segment on the current platform.
RTI_BOOL	OSAPI_SharedMemorySegment_is_owner_alive (struct OSAPI_SharedMemorySegmentHandle *handle, RTI_BOOL *alive)
	Check if the process which created the shared memory segment is still alive.
NETIOPSLDllExport RTI_SIZE_T	OSAPI_SharedMemorySegmentHandle_get_size (OSAPI_SHMEM_MODE mode)
	Get the amount of memory required to store a OSAPI_SharedMemorySegmentHandle on the current platform for a given mode.
NETIOPSLDllExport RTI_SIZE_T	OSAPI_SharedMemorySegmentHeader_get_size (OSAPI_SHMEM_MODE mode)
	Get the amount of memory, aligned to the maximum alignment, required to store a OSAPI_SharedMemorySegmentHeader on the current platform for a given mode.
NETIOPSLDllExport RTI_BOOL	OSAPI_SharedMemorySegment_create_impl (struct OSAPI_SharedMemorySegmentHandle *handle, const char *name, RTI_UINT64 size, OSAPI_SHMEM_MODE mode, RTI_BOOL *exists)
	Creates a new shared memory segment with the provided key and initialize a handle to it.
NETIOPSLDllExport RTI_BOOL	OSAPI_SharedMemorySegment_delete_impl (struct OSAPI_SharedMemorySegmentHandle *handle)
	Delete a shared memory segment.
NETIOPSLDllExport RTI_BOOL	OSAPI_SharedMemorySegment_attach_impl (struct OSAPI_SharedMemorySegmentHandle *handle, const char *name, OSAPI_SHMEM_MODE mode, OSAPI_SHMEM_ATTACH_STATUS *status_out)
	Attach to the shared memory and initialize a handle to it.
NETIOPSLDllExport RTI_BOOL	OSAPI_SharedMemorySegment_detach_impl (struct OSAPI_SharedMemorySegmentHandle *handle)
	detach the shared memory segment.
NETIOPSLDllExport RTI_BOOL	OSAPI_SharedMemorySegment_lock_impl (struct OSAPI_SharedMemorySegmentHandle *handle, OSAPI_SHMEM_STATUS *status_out)
	Lock a shared memory segment.
NETIOPSLDllExport RTI_BOOL	OSAPI_SharedMemorySegment_unlock_impl (struct OSAPI_SharedMemorySegmentHandle *handle)
	Unlock a shared memory segment previously locked with OSAPI_SharedMemorySegment_lock_impl.
NETIOPSLDllExport RTI_BOOL	OSAPI_SharedMemorySegment_mark_consistent_impl (struct OSAPI_SharedMemorySegmentHandle *handle)
	Mark a shared memory segment as consistent. This function can only be called if a previous call to OSAPI_SharedMemorySegment_lock_impl returned OSAPI_SHMEM_FAIL_REASON_OWNER_DEAD.
NETIOPSLDllExport RTI_BOOL	OSAPI_SharedMemory_is_robust_mutex_supported (void)
	Checks wether robust mutex is supported or not .

Detailed Description

Allow access to a shared memory segment (memory block) so that multiple processes can read-and write a common memory area.

Enumeration Type Documentation

OSAPI_SHMEM_MODE

enum OSAPI_SHMEM_MODE

Mode used to create or attach to a shared memory segment. Each mode defines specific capabilities of the segment.

Enumerator
OSAPI_SHMEM_MODE_UNKNOWN	Invalid mode
OSAPI_SHMEM_MODE_READ	Read permission
OSAPI_SHMEM_MODE_WRITE	Write permission, implies OSAPI_SHMEM_MODE_READ
OSAPI_SHMEM_MODE_LOCKABLE	Locking capability, implies OSAPI_SHMEM_MODE_WRITE
OSAPI_SHMEM_MODE_ROBUST	Robust locking capability, implies OSAPI_SHMEM_MODE_LOCKABLE

OSAPI_SHMEM_STATUS

enum OSAPI_SHMEM_STATUS

Status used to convey the state of a shared memory object.

Enumerator
OSAPI_SHMEM_STATUS_OK	Success
OSAPI_SHMEM_STATUS_OWNER_DEAD	Previous owner of lock died while holding it

OSAPI_SHMEM_ATTACH_STATUS

enum OSAPI_SHMEM_ATTACH_STATUS

Status used to convey the state of a shared memory object's attachment to a shared memory segment.

Enumerator
OSAPI_SHMEM_ATTACH_STATUS_OK	Success
OSAPI_SHMEM_ATTACH_STATUS_SEGMENT_NOT_FOUND	Segment was not found when trying to attach

Function Documentation

OSAPI_SharedMemorySegment_get_max_size()

RTI_UINT64 OSAPI_SharedMemorySegment_get_max_size

(

void

)

Get maximum size of a shared memory segment on the current platform.

Returns

RTI_TRUE on success. RTI_FALSE if an error occurred.

OSAPI_SharedMemorySegment_is_owner_alive()

RTI_BOOL OSAPI_SharedMemorySegment_is_owner_alive	(	struct OSAPI_SharedMemorySegmentHandle *	handle,
		RTI_BOOL *	alive )

Check if the process which created the shared memory segment is still alive.

Parameters

[in]	handle	The shared memory segment handle identifying the segment.
[out]	alive	If the process is alive.

Returns

RTI_TRUE on success. RTI_FALSE if an error occurred.

The behavior or this function is undefined if the segment is not currently attached.

OSAPI_SharedMemorySegmentHandle_get_size()

NETIOPSLDllExport RTI_SIZE_T OSAPI_SharedMemorySegmentHandle_get_size

(

OSAPI_SHMEM_MODE

mode

)

Get the amount of memory required to store a OSAPI_SharedMemorySegmentHandle on the current platform for a given mode.

Parameters

[in]

mode

The creation or attachment mode of the handle.

Returns

Number of bytes required to store a handle.

OSAPI_SharedMemorySegmentHeader_get_size()

NETIOPSLDllExport RTI_SIZE_T OSAPI_SharedMemorySegmentHeader_get_size

(

OSAPI_SHMEM_MODE

mode

)

Get the amount of memory, aligned to the maximum alignment, required to store a OSAPI_SharedMemorySegmentHeader on the current platform for a given mode.

Parameters

[in]

mode

The creation mode of the segment containing the header.

Returns

Number of bytes required to store a header.

The number of bytes returned by this function shall be aligned to the maximum alignment of the platform.

OSAPI_SharedMemorySegment_create_impl()

NETIOPSLDllExport RTI_BOOL OSAPI_SharedMemorySegment_create_impl	(	struct OSAPI_SharedMemorySegmentHandle *	handle,
		const char *	name,
		RTI_UINT64	size,
		OSAPI_SHMEM_MODE	mode,
		RTI_BOOL *	exists )

Creates a new shared memory segment with the provided key and initialize a handle to it.

Parameters

[in,out]	handle	Handle to be initialized.
[in]	name	Name to identify the shared memory segment.
[in]	size	Size of memory to be allocated.
[in]	mode	Mode used to create the shared memory segment. The mode determines the capabilities of the segment. The mode must be >= OSAPI_SHMEM_MODE_WRITE.
[out]	exists	If the segment already exists

Returns

RTI_TRUE on success. RTI_FALSE if an error occurred.

The new shared memory segment shall be initialized with null bytes ('\0').

References RTI_UINT64.

OSAPI_SharedMemorySegment_delete_impl()

NETIOPSLDllExport RTI_BOOL OSAPI_SharedMemorySegment_delete_impl

(

struct OSAPI_SharedMemorySegmentHandle *

handle

)

Delete a shared memory segment.

Parameters

[in]

handle

The shared memory segment handle identifying the segment to delete.

Returns

RTI_TRUE on success. RTI_FALSE if either the precondition was not met or the shared memory segment could not be deleted.

Once this function is called (even if it returns RTI_FALSE) you can no longer use this shared memory segment.

OSAPI_SharedMemorySegment_attach_impl()

NETIOPSLDllExport RTI_BOOL OSAPI_SharedMemorySegment_attach_impl	(	struct OSAPI_SharedMemorySegmentHandle *	handle,
		const char *	name,
		OSAPI_SHMEM_MODE	mode,
		OSAPI_SHMEM_ATTACH_STATUS *	status_out )

Attach to the shared memory and initialize a handle to it.

Parameters

[in,out]	handle	Handle to be initialized.
[in]	name	Name to identify the shared memory segment.
[in]	mode	Mode used to attach the shared memory segment.
[out]	status_out	If successful, the attachment status of the shared memory segment.

Returns

RTI_TRUE on success. Note that the attachment status may still be different from OK, so checking the value of status_out is mandatory. RTI_FALSE if an error occurred.

OSAPI_SharedMemorySegment_detach_impl()

NETIOPSLDllExport RTI_BOOL OSAPI_SharedMemorySegment_detach_impl

(

struct OSAPI_SharedMemorySegmentHandle *

handle

)

detach the shared memory segment.

Parameters

[in]

handle

The shared memory segment handle identifying the segment to detach.

Returns

RTI_TRUE on success. RTI_FALSE if either the precondition was not met or the shared memory segment could not be detached.

Once this function is called (even if it returns RTI_FALSE) you can no longer use this shared memory segment handle.

OSAPI_SharedMemorySegment_lock_impl()

NETIOPSLDllExport RTI_BOOL OSAPI_SharedMemorySegment_lock_impl	(	struct OSAPI_SharedMemorySegmentHandle *	handle,
		OSAPI_SHMEM_STATUS *	status_out )

Lock a shared memory segment.

Parameters

[in]	handle	The shared memory segment handle identifying the segment to lock.
[out]	status_out	Success or failure reason of acquiring the lock.

Returns

RTI_TRUE on success. RTI_FALSE if an error occurred.

OSAPI_SharedMemorySegment_unlock_impl()

NETIOPSLDllExport RTI_BOOL OSAPI_SharedMemorySegment_unlock_impl

(

struct OSAPI_SharedMemorySegmentHandle *

handle

)

Unlock a shared memory segment previously locked with OSAPI_SharedMemorySegment_lock_impl.

Parameters

[in]

handle

The shared memory segment handle identifying the segment to unlock.

Returns

RTI_TRUE on success. RTI_FALSE if an error occurred.

The behavior of this method is undefined if the calling process has not previously acquired the lock with OSAPI_SharedMemorySegment_lock_impl.

OSAPI_SharedMemorySegment_mark_consistent_impl()

NETIOPSLDllExport RTI_BOOL OSAPI_SharedMemorySegment_mark_consistent_impl

(

struct OSAPI_SharedMemorySegmentHandle *

handle

)

Mark a shared memory segment as consistent. This function can only be called if a previous call to OSAPI_SharedMemorySegment_lock_impl returned OSAPI_SHMEM_FAIL_REASON_OWNER_DEAD.

Parameters

[in]

handle

The shared memory segment handle identifying the segment to mark consistent.

Returns

RTI_TRUE on success. RTI_FALSE if an error occurred.

OSAPI_SharedMemory_is_robust_mutex_supported()

NETIOPSLDllExport RTI_BOOL OSAPI_SharedMemory_is_robust_mutex_supported

(

void

)

Checks wether robust mutex is supported or not .

Returns

RTI_TRUE is supported. RTI_FALSE if not supported.