RTI Connext Micro C API Version 4.2.0
Loading...
Searching...
No Matches
Data Structures | Functions
Shared Memory Segment API
Shared Memory Transport 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...

Data Structures

struct  NETIO_SharedMemorySegmentHeader
 

Functions

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.
 
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.
 
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.
 
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.
 
RTIBool NETIO_SharedMemorySegment_detach (struct NETIO_SharedMemorySegmentHandle *handle)
 Detach from the shared memory previously created with NETIO_SharedMemorySegment_attach.
 
char * NETIO_SharedMemorySegment_get_address (struct NETIO_SharedMemorySegmentHandle *handle)
 Get the address of the shared memory attached by the handle.
 
NETIOPSLDllExport RTI_INT32 NETIO_SharedMemorySegment_get_size (struct NETIO_SharedMemorySegmentHandle *handle)
 Get the size (available for user data) of the shared memory segment.
 
NETIOPSLDllExport 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_SharedMemorySegment_create_or_attach()

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.

References RTI_INT32, and RTI_UINT32.

◆ NETIO_SharedMemorySegment_create()

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

References RTI_INT32, and RTI_UINT32.

◆ NETIO_SharedMemorySegment_delete()

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_SharedMemorySegment_attach()

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.

References RTI_INT32.

◆ NETIO_SharedMemorySegment_detach()

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_SharedMemorySegment_get_address()

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

References RTI_INT32.

◆ NETIO_SharedMemorySegment_get_size()

NETIOPSLDllExport 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.

References RTI_UINT32.

◆ NETIO_SharedMemorySegment_get_max_size()

NETIOPSLDllExport RTI_UINT32 NETIO_SharedMemorySegment_get_max_size ( void )

Maximum allowable size of a shared memory segment.

References RTI_INT32.