OSAPI SharedMemorySegment

Functions
RTIBool	OSAPI_SharedMemorySegment_create_or_attach (struct OSAPI_SharedMemorySegmentHandle *handle, RTI_INT32 *status_out, RTI_INT32 key, RTI_UINT32 size, OSAPI_ProcessId pid_in)
	Attempts to create a new shared memory segment. If the segment already exists and the creator process is dead, attach and recycle it.
RTIBool	OSAPI_SharedMemorySegment_create (struct OSAPI_SharedMemorySegmentHandle *handle, RTI_INT32 *status_out, RTI_INT32 key, RTI_UINT32 size, OSAPI_ProcessId pid_in)
	Creates a new shared memory segment with the provided key and returns the handle to access it.
RTIBool	OSAPI_SharedMemorySegment_delete (struct OSAPI_SharedMemorySegmentHandle *handle)
	deletes the shared memory segment previously create with OSAPI_SharedMemorySegment_create. If the segment is still attached, it is detached first.
RTIBool	OSAPI_SharedMemorySegment_attach (struct OSAPI_SharedMemorySegmentHandle *handle, RTI_INT32 *status_out, RTI_INT32 key)
	Attach to the shared memory previously initialized with OSAPI_SharedMemorySegment_create_or_attach and returns a handle to it.
RTIBool	OSAPI_SharedMemorySegment_detach (struct OSAPI_SharedMemorySegmentHandle *handle)
	Detach from the shared memory previously created with OSAPI_SharedMemorySegment_attach.
char *	OSAPI_SharedMemorySegment_get_address (struct OSAPI_SharedMemorySegmentHandle *handle)
	Get the address of the shared memory attached by the handle.
RTI_INT32	OSAPI_SharedMemorySegment_get_size (struct OSAPI_SharedMemorySegmentHandle *handle)
	Get the size (available for user data) of the shared memory segment.
RTI_UINT32	OSAPI_SharedMemorySegment_get_max_size ()
	Maximum allowable size of a shared memory segment.

---

Detailed Description

---

Function Documentation

RTIBool OSAPI_SharedMemorySegment_create_or_attach	(	struct OSAPI_SharedMemorySegmentHandle *	handle,
		RTI_INT32 *	status_out,
		RTI_INT32	key,
		RTI_UINT32	size,
		OSAPI_ProcessId	pid_in
	)

Attempts to create a new shared memory segment. If the segment already exists and the creator process is dead, attach and recycle it.

Parameters:

[in,out]	handle	The shared memory segment handle to initialize.
[out]	status_out	Optional: if not NULL is set to the reason why the call has succeeded or failed. In particular, OSAPI_SHARED_MEMORY_FAIL_REASON_PRECONDITION = precondition check failed. OSAPI_SHARED_MEMORY_FAIL_REASON_UNKNOWN = an error occurred in the os-specific shared memory implementation (see error log for details). OSAPI_SHARED_MEMORY_FAIL_REASON_ALREADY_CLAIMED = someone is already sitting on this address. OSAPI_SHARED_MEMORY_CREATED = the segment has been created new. OSAPI_SHARED_MEMORY_ATTACHED = the segment was reused from an existing one.
[in]	key	Key to identify the shared memory segment Across processes. Other processes should call OSAPI_SharedMemorySegment_attach with the same key to attach to this segment.
[in]	size	Size of memory to be initialized.
[in]	pid_in	PID of the process that calls this method.

Returns:

RTI_TRUE if success, or RTI_FALSE if something failed.

RTIBool OSAPI_SharedMemorySegment_create	(	struct OSAPI_SharedMemorySegmentHandle *	handle,
		RTI_INT32 *	status_out,
		RTI_INT32	key,
		RTI_UINT32	size,
		OSAPI_ProcessId	pid_in
	)

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

Parameters:

[in,out]	handle	The shared memory segment handle to initialize.
[out]	status_out	Optional: if not NULL is set to the reason why the call has succeeded or failed. In particular, OSAPI_SHARED_MEMORY_FAIL_REASON_PRECONDITION = precondition check failed. OSAPI_SHARED_MEMORY_FAIL_REASON_UNKNOWN = an error occurred in the os-specific shared memory implementation (see error log for details). OSAPI_SHARED_MEMORY_FAIL_REASON_ALREADY_CLAIMED = segment already exist (no checks is performed whether the creator is still alive or not). OSAPI_SHARED_MEMORY_CREATED = the segment has been successfully created.
[in]	key	Key to identify the shared memory segment across processes. Other processes should call OSAPI_SharedMemorySegment_attach with the same key to attach to this segment.
[in]	size	Size of memory to be initialized.
[in]	pid_in	PID of the process that calls this method.

Returns:

RTI_TRUE if success, or RTI_FALSE if something failed.

Note:

Depending on the underlying OS, the key may need to be transformed to the actual representation needed by the operating system

RTIBool OSAPI_SharedMemorySegment_delete

(

struct OSAPI_SharedMemorySegmentHandle *

handle

)

deletes the shared memory segment previously create with OSAPI_SharedMemorySegment_create. If the segment is still attached, it is detached first.

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 couldn't be removed (i.e. the user running this app is not the owner or creator).

Note:

This function does not perform any control on the ownership of the segment. If you attach to a segment, then when you call this function the segment will be destroyed (if you have enough permission to complete the operation)

When you create a segment with OSAPI_SharedMemorySegment_create or with OSAPI_SharedMemorySegment_create_or_attach, you can delete it by calling directly OSAPI_SharedMemorySegment_delete without calling OSAPI_SharedMemorySegment_detach.

Once called this function (even if it returns RTI_FALSE) you cannot use anymore this shared memory segment.

RTIBool OSAPI_SharedMemorySegment_attach	(	struct OSAPI_SharedMemorySegmentHandle *	handle,
		RTI_INT32 *	status_out,
		RTI_INT32	key
	)

Attach to the shared memory previously initialized with OSAPI_SharedMemorySegment_create_or_attach and returns a handle to it.

Parameters:

[in,out]	handle	The shared memory segment handle to initialize.
[out]	status_out	Optional. If not NULL, will be set to: OSAPI_SHARED_MEMORY_FAIL_REASON_PRECONDITION = precondition check failed. OSAPI_SHARED_MEMORY_FAIL_REASON_UNKNOWN = an error occurred in the os-specific shared memory implementation (see error log for details). OSAPI_SHARED_MEMORY_FAIL_REASON_NO_ENTRY = no such a segment. OSAPI_SHARED_MEMORY_FAIL_REASON_OUT_OF_MEMORY = out of memory allocating the handle structure. OSAPI_SHARED_MEMORY_ATTACHED = segment attached successfully.
[in]	key	Key to identify the shared memory segment across processes. Must match that used by other processes calling OSAPI_SharedMemorySegment_create_or_attach or OSAPI_SharedMemorySegment_attach().

Returns:

RTI_TRUE on success. RTI_FALSE if an error occurred.

RTIBool OSAPI_SharedMemorySegment_detach

(

struct OSAPI_SharedMemorySegmentHandle *

handle

)

Detach from the shared memory previously created with OSAPI_SharedMemorySegment_attach.

Parameters:

[in]

handle

The shared memory segment handle identifying the segment to detach

Returns:

RTI_TRUE on success. RTI_FALSE if the precondition was not met.

The shared memory segment is always detached. Once the precondition is met, no errors will be generated.

Once called this function (even if it returns RTI_FALSE) you cannot use anymore this shared memory segment, except for destroying it.

char* OSAPI_SharedMemorySegment_get_address

(

struct OSAPI_SharedMemorySegmentHandle *

handle

)

Get the address of the shared memory attached by the handle.

Precondition:

Handle in the ATTACHED state.

Postcondition:

none

Parameters:

[in]

handle

Handle to the shared memory segment obtained from an OSAPI_SharedMemorySegment_attach or a OSAPI_SharedMemorySegment_create_or_attach

Returns:

the address that can be used to read and write the memory. For performance this function never checks pre-conditions. It is the caller's responsibility to ensure the handle is NON null and ATTACHED. A NULL handle will cause a seg-fault. An un-attached handle may give invalid values for the OSAPI_SharedMemorySegment_get_size

RTI_INT32 OSAPI_SharedMemorySegment_get_size

(

struct OSAPI_SharedMemorySegmentHandle *

handle

)

Get the size (available for user data) of the shared memory segment.

This size will match the one passed to the OSAPI_SharedMemorySegment_create_or_attach call

Precondition:

Handle in the ATTACHED state.

Postcondition:

none

Parameters:

[in]

handle

Handle to the shared memory segment obtained from an OSAPI_SharedMemorySegment_attach or a OSAPI_SharedMemorySegment_create_or_attach call.

Returns:

the number of bytes that can be read/written stating at the address provided by OSAPI_SharedMemorySegment_get_address. For performance this function never checks pre-conditions. It is the caller's responsibility to ensure the handle is NON null and ATTACHED. A NULL handle will cause a seg-fault. An un-attached handle may give invalid values for the size.

RTI_UINT32 OSAPI_SharedMemorySegment_get_max_size

(

)

Maximum allowable size of a shared memory segment.