RTI Connext DDS Micro C++ API  Version 4.1.0
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Classes | Functions
Shared Memory Segment API
NETIO Shared Memory API

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

Classes

struct  NETIO_SharedMemorySegmentHeader

Functions

NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySegment_create_or_attach (struct NETIO_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.
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySegment_create (struct NETIO_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.
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySegment_delete (struct NETIO_SharedMemorySegmentHandle *handle)
 deletes the shared memory segment previously create with NETIO_SharedMemorySegment_create. If the segment is still attached, it is detached first.
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySegment_attach (struct NETIO_SharedMemorySegmentHandle *handle, RTI_INT32 *status_out, RTI_INT32 key)
 Attach to the shared memory previously initialized with NETIO_SharedMemorySegment_create_or_attach and returns a handle to it.
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySegment_detach (struct NETIO_SharedMemorySegmentHandle *handle)
 Detach from the shared memory previously created with NETIO_SharedMemorySegment_attach.
NETIO_SHMEMDllExport char * NETIO_SharedMemorySegment_get_address (struct NETIO_SharedMemorySegmentHandle *handle)
 Get the address of the shared memory attached by the handle.
NETIO_SHMEMDllExport RTI_INT32 NETIO_SharedMemorySegment_get_size (struct NETIO_SharedMemorySegmentHandle *handle)
 Get the size (available for user data) of the shared memory segment.
NETIO_SHMEMDllExport RTI_UINT32 NETIO_SharedMemorySegment_get_max_size (void)
 Maximum allowable size of a shared memory segment.

Detailed Description

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

Function Documentation

NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySegment_create_or_attach ( struct NETIO_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 NETIO_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.
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySegment_create ( struct NETIO_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 NETIO_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
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySegment_delete ( struct NETIO_SharedMemorySegmentHandle *  handle)

deletes the shared memory segment previously create with NETIO_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 NETIO_SharedMemorySegment_create or with NETIO_SharedMemorySegment_create_or_attach, you can delete it by calling directly NETIO_SharedMemorySegment_delete without calling NETIO_SharedMemorySegment_detach.

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

NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySegment_attach ( struct NETIO_SharedMemorySegmentHandle *  handle,
RTI_INT32 *  status_out,
RTI_INT32  key 
)

Attach to the shared memory previously initialized with NETIO_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 NETIO_SharedMemorySegment_create_or_attach or NETIO_SharedMemorySegment_attach().
Returns:
RTI_TRUE on success. RTI_FALSE if an error occurred.
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySegment_detach ( struct NETIO_SharedMemorySegmentHandle *  handle)

Detach from the shared memory previously created with NETIO_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.

NETIO_SHMEMDllExport char* NETIO_SharedMemorySegment_get_address ( struct NETIO_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 NETIO_SharedMemorySegment_attach or a NETIO_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 NETIO_SharedMemorySegment_get_size
NETIO_SHMEMDllExport RTI_INT32 NETIO_SharedMemorySegment_get_size ( struct NETIO_SharedMemorySegmentHandle *  handle)

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

This size will match the one passed to the NETIO_SharedMemorySegment_create_or_attach call

Precondition:
Handle in the ATTACHED state.
Postcondition:
none
Parameters:
[in]handleHandle to the shared memory segment obtained from an NETIO_SharedMemorySegment_attach or a NETIO_SharedMemorySegment_create_or_attach call.
Returns:
the number of bytes that can be read/written stating at the address provided by NETIO_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.
NETIO_SHMEMDllExport RTI_UINT32 NETIO_SharedMemorySegment_get_max_size ( void  )

Maximum allowable size of a shared memory segment.

RTI Connext DDS Micro C++ API Version 4.1.0 Copyright © Sun Dec 8 2024 Real-Time Innovations, Inc