RTI Connext DDS Micro C API  Version 3.0.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
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 (void)
 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]handleThe shared memory segment handle to initialize.
[out]status_outOptional: 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]keyKey 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]sizeSize of memory to be initialized.
[in]pid_inPID 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]handleThe shared memory segment handle to initialize.
[out]status_outOptional: 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]keyKey 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]sizeSize of memory to be initialized.
[in]pid_inPID 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]handleThe 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]handleThe shared memory segment handle to initialize.
[out]status_outOptional. 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]keyKey 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]handleThe 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]handleHandle 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]handleHandle 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 ( void  )

Maximum allowable size of a shared memory segment.


RTI Connext DDS Micro C API Version 3.0.3 Copyright © Wed Jun 24 2020 Real-Time Innovations, Inc