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

Functions

NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySignalingSemaphore_create (struct NETIO_SharedMemorySignalingSemaphoreHandle *handle, RTI_INT32 *status_out, RTI_INT32 key)
 Initializes a shared memory binary semaphore with the provided key and sets up the handle to access it.
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySignalingSemaphore_attach (struct NETIO_SharedMemorySignalingSemaphoreHandle *handle, RTI_INT32 *status_out, RTI_INT32 key)
 Attach to an existing shared memory binary semaphore with the provided key and sets up the handle to access it.
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySignalingSemaphore_create_or_attach (struct NETIO_SharedMemorySignalingSemaphoreHandle *handle, RTI_INT32 *status_out, RTI_INT32 key)
 Attempts to create a new binary semaphore with the provided key and if the semaphore already exist, attach to it.
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySignalingSemaphore_signal (struct NETIO_SharedMemorySignalingSemaphoreHandle *handle, RTI_INT32 *status_out)
 Give the semaphore.
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySignalingSemaphore_wait (struct NETIO_SharedMemorySignalingSemaphoreHandle *handle, RTI_INT32 *status_out)
 Take the semaphore.
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySignalingSemaphore_detach (struct NETIO_SharedMemorySignalingSemaphoreHandle *handle)
 Detach from the shared memory binary semaphore.
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySignalingSemaphore_delete (struct NETIO_SharedMemorySignalingSemaphoreHandle *handle)
 Detach from the shared memory semaphore and deletes it.

Detailed Description

Function Documentation

NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySignalingSemaphore_create ( struct NETIO_SharedMemorySignalingSemaphoreHandle *  handle,
RTI_INT32 *  status_out,
RTI_INT32  key 
)

Initializes a shared memory binary semaphore with the provided key and sets up the handle to access it.

Precondition:
Handle in the DETACHED state. Signaling semaphore in the INITIAL, that is, Nobody has called create() before with that same key
Postcondition:
handle in the ATTACHED state, Semaphore exists and ready to be used.
Parameters:
[in,out]handleThe shared memory semaphore 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 = semaphore already exist (no checks is performed whether the creator is still alive or not).
  • OSAPI_SHARED_MEMORY_CREATED = the semaphore has been successfully created.
[in]keyKey to identify the shared memory semaphore across processes. Other processes should call NETIO_SharedMemorySignalingSemaphore_attach with the same key to attach to this semaphore.
Returns:
RTI_TRUE on success. RTI_FALSE on error.
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySignalingSemaphore_attach ( struct NETIO_SharedMemorySignalingSemaphoreHandle *  handle,
RTI_INT32 *  status_out,
RTI_INT32  key 
)

Attach to an existing shared memory binary semaphore with the provided key and sets up the handle to access it.

Precondition:
Handle in the DETACHED state. Signaling semaphore in the CREATED state. Some other process has called NETIO_SharedMemorySignalingSemaphore_create using the same key in the shared memory semaphore
Postcondition:
handle in the ATTACHED state, Semaphore exists and is ready to be used.
Parameters:
[out]handleThe shared memory semaphore 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 semaphore.
  • OSAPI_SHARED_MEMORY_ATTACHED = semaphore attached successfully.
[in]keyKey to identify the shared memory semaphore across processes.
Returns:
RTI_TRUE on success. RTI_FALSE on error.
Note:
On some platforms this method makes sure that the given key represent a shared memory semaphore object (to avoid situations like the same key is used to create a mutex and then used to attach it as a semaphore). If such a situation is detected, the function will fail and set status_out to: OSAPI_SHARED_MEMORYFAIL_REASON_NO_ENTRY. Not all the platforms support this feature.
See also:
NETIO_SharedMemorySignalingSemaphore_detach
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySignalingSemaphore_create_or_attach ( struct NETIO_SharedMemorySignalingSemaphoreHandle *  handle,
RTI_INT32 *  status_out,
RTI_INT32  key 
)

Attempts to create a new binary semaphore with the provided key and if the semaphore already exist, attach to it.

Precondition:
Handle in the DETACHED state. Signaling semaphore in the INITIAL, that is, Nobody has called create() before with that same key.
Postcondition:
handle in the ATTACHED state, Semaphore is in the CREATED state and ready to be used.
Parameters:
[in,out]handleThe shared memory semaphore 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_NO_ENTRY = this error should never happen and is caused by a failed create() followed by a failed attach().
  • OSAPI_SHARED_MEMORY_CREATED = the semaphore has been successfully created.
[in]keyKey to identify the shared memory binary semaphore across processes.
Returns:
RTI_TRUE on success. RTI_FALSE on error.
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySignalingSemaphore_signal ( struct NETIO_SharedMemorySignalingSemaphoreHandle *  handle,
RTI_INT32 *  status_out 
)

Give the semaphore.

Precondition:
Handle in the ATTACHED state.
Postcondition:
Semaphore count is set to 1 and any thread blocked on this semaphore is awaken.
Parameters:
[in]handleHandle to the semaphore. Must match the one returned by NETIO_SharedMemorySignalingSemaphore_create
[out]status_outOptional: if not NULL, will be set to:
  • 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 = the creator of the mutex has shutdown and removed this mutex. This is expected to happen routinely.
  • OSAPI_SHARED_MEMORY_SUCCESS = Generic no error condition.
Returns:
RTI_TRUE if the semaphore is given. RTI_FALSE if an error occurs. If an error occurs the handle should not be used anymore. In particular detach() should not be called either. An error may occur in certain OSs if the handle that created the semaphore calls NETIO_SharedMemorySignalingSemaphore_detach.
See also:
NETIO_SharedMemorySignalingSemaphore_wait
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySignalingSemaphore_wait ( struct NETIO_SharedMemorySignalingSemaphoreHandle *  handle,
RTI_INT32 *  status_out 
)

Take the semaphore.

Precondition:
Handle in the ATTACHED state.
Postcondition:
Semaphore count is decremented.
Parameters:
[in]handleHandle to the semaphore. Must match the one returned by NETIO_SharedMemorySignalingSemaphore_create
[out]status_outOptional: if not NULL, will be set to:
  • 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 = the creator of the mutex has shutdown and removed this mutex. This is expected to happen routinely.
  • OSAPI_SHARED_MEMORY_SUCCESS = Generic no error condition.
Returns:
RTI_TRUE if the semaphore is taken. RTI_FALSE if an error occurs. If an error occurs the handle should not be used anymore. In particular NETIO_SharedMemorySignalingSemaphore_detach should not be called either.
See also:
NETIO_SharedMemorySignalingSemaphore_signal
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySignalingSemaphore_detach ( struct NETIO_SharedMemorySignalingSemaphoreHandle *  handle)

Detach from the shared memory binary semaphore.

Precondition:
Handle in the ATTACHED state.
Postcondition:
handle in the DETACHED state.
Parameters:
[in]handleHandle to the shared memory semaphore obtained from NETIO_SharedMemorySignalingSemaphore_attach
See also:
NETIO_SharedMemorySignalingSemaphore_attach
NETIO_SHMEMDllExport RTIBool NETIO_SharedMemorySignalingSemaphore_delete ( struct NETIO_SharedMemorySignalingSemaphoreHandle *  handle)

Detach from the shared memory semaphore and deletes it.

The exact behavior of this may be OS dependent. In some OSs calling this will immediately cause the semaphore to be removed, and other threads waiting on it to be woken up. This is the typical behavior on Unix. In other OSs (windows) this call just requests the semaphore to be removed but delay the removal until all handles are detached.

The only way to ensure the same behavior across multiple OSs is to only call this method on the handle that created the semaphore after all the other handles have been closed. In this scenario no handles will get an error. Alternatively the code could be written to always expect the NETIO_SharedMemorySignalingSemaphore_wait or NETIO_SharedMemorySignalingSemaphore_signal call to fail and when that occurs close the handle.

Precondition:
Handle in the ATTACHED state.
Postcondition:
handle in the DETACHED state. The numHandles to the semaphore is decremented. When the last handle is detached, the semaphore is removed by the OS.
Parameters:
[in]handleHandle to the shared memory semaphore obtained from NETIO_SharedMemorySignalingSemaphore_create
See also:
NETIO_SharedMemorySignalingSemaphore_create
RTI Connext DDS Micro C++ API Version 4.1.0 Copyright © Sun Dec 8 2024 Real-Time Innovations, Inc