RTI Connext DDS Micro C API  Version 4.1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Data Structures | Enumerations | Functions
OSAPI_SharedMemorySegment
OS 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  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 }

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.
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.
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.
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.
RTI_BOOL OSAPI_SharedMemorySegment_delete_impl (struct OSAPI_SharedMemorySegmentHandle *handle)
 Delete a shared memory segment.
RTI_BOOL OSAPI_SharedMemorySegment_attach_impl (struct OSAPI_SharedMemorySegmentHandle *handle, const char *name, OSAPI_SHMEM_MODE mode)
 Attach to the shared memory and initialize a handle to it.
RTI_BOOL OSAPI_SharedMemorySegment_detach_impl (struct OSAPI_SharedMemorySegmentHandle *handle)
 detach the shared memory segment.
RTI_BOOL OSAPI_SharedMemorySegment_lock_impl (struct OSAPI_SharedMemorySegmentHandle *handle, OSAPI_SHMEM_STATUS *status_out)
 Lock a shared memory segment.
RTI_BOOL OSAPI_SharedMemorySegment_unlock_impl (struct OSAPI_SharedMemorySegmentHandle *handle)
 Unlock a shared memory segment previously locked with OSAPI_SharedMemorySegment_lock_impl.
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.
RTI_BOOL OSAPI_SharedMemory_is_robust_mutex_supported ()
 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

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

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

Function Documentation

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.
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]handleThe shared memory segment handle identifying the segment.
[out]aliveIf 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.

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]modeThe creation or attachment mode of the handle.
Returns:
Number of bytes required to store a handle.
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]modeThe 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.

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]handleHandle to be initialized.
[in]nameName to identify the shared memory segment.
[in]sizeSize of memory to be allocated.
[in]modeMode used to create the shared memory segment. The mode determines the capabilities of the segment. The mode must be >= OSAPI_SHMEM_MODE_WRITE.
[out]existsIf 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').

RTI_BOOL OSAPI_SharedMemorySegment_delete_impl ( struct OSAPI_SharedMemorySegmentHandle *  handle)

Delete a shared memory segment.

Parameters:
[in]handleThe 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.

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

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

Parameters:
[in,out]handleHandle to be initialized.
[in]nameName to identify the shared memory segment.
[in]modeMode used to attach the shared memory segment.
Returns:
RTI_TRUE on success. RTI_FALSE if an error occurred.
RTI_BOOL OSAPI_SharedMemorySegment_detach_impl ( struct OSAPI_SharedMemorySegmentHandle *  handle)

detach the shared memory segment.

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

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

Lock a shared memory segment.

Parameters:
[in]handleThe shared memory segment handle identifying the segment to lock.
[out]status_outSuccess or failure reason of acquiring the lock.
Returns:
RTI_TRUE on success. RTI_FALSE if an error occurred.
RTI_BOOL OSAPI_SharedMemorySegment_unlock_impl ( struct OSAPI_SharedMemorySegmentHandle *  handle)

Unlock a shared memory segment previously locked with OSAPI_SharedMemorySegment_lock_impl.

Parameters:
[in]handleThe 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.

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]handleThe shared memory segment handle identifying the segment to mark consistent.
Returns:
RTI_TRUE on success. RTI_FALSE if an error occurred.
RTI_BOOL OSAPI_SharedMemory_is_robust_mutex_supported ( )

Checks wether robust mutex is supported or not .

Returns:
RTI_TRUE is supported. RTI_FALSE if not supported.
RTI Connext DDS Micro C API Version 4.1.0 Copyright © Sun Dec 8 2024 Real-Time Innovations, Inc