RTI Connext DDS Micro C API  Version 3.0.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Functions
OSAPI SharedMemorySignalingSemaphore
OSAPI SharedMemory

Functions

RTIBool OSAPI_SharedMemorySignalingSemaphore_create (struct OSAPI_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.
RTIBool OSAPI_SharedMemorySignalingSemaphore_attach (struct OSAPI_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.
RTIBool OSAPI_SharedMemorySignalingSemaphore_create_or_attach (struct OSAPI_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.
RTIBool OSAPI_SharedMemorySignalingSemaphore_signal (struct OSAPI_SharedMemorySignalingSemaphoreHandle *handle, RTI_INT32 *status_out)
 Give the semaphore.
RTIBool OSAPI_SharedMemorySignalingSemaphore_wait (struct OSAPI_SharedMemorySignalingSemaphoreHandle *handle, RTI_INT32 *status_out)
 Take the semaphore.
RTIBool OSAPI_SharedMemorySignalingSemaphore_detach (struct OSAPI_SharedMemorySignalingSemaphoreHandle *handle)
 Detach from the shared memory binary semaphore.
RTIBool OSAPI_SharedMemorySignalingSemaphore_delete (struct OSAPI_SharedMemorySignalingSemaphoreHandle *handle)
 Detach from the shared memory semaphore and deletes it.

Detailed Description

Function Documentation

RTIBool OSAPI_SharedMemorySignalingSemaphore_create ( struct OSAPI_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 OSAPI_SharedMemorySignalingSemaphore_attach with the same key to attach to this semaphore.
Returns:
RTI_TRUE on success. RTI_FALSE on error.
RTIBool OSAPI_SharedMemorySignalingSemaphore_attach ( struct OSAPI_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 OSAPI_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:
OSAPI_SharedMemorySignalingSemaphore_detach
RTIBool OSAPI_SharedMemorySignalingSemaphore_create_or_attach ( struct OSAPI_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.
RTIBool OSAPI_SharedMemorySignalingSemaphore_signal ( struct OSAPI_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 OSAPI_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 OSAPI_SharedMemorySignalingSemaphore_detach.
See also:
OSAPI_SharedMemorySignalingSemaphore_wait
RTIBool OSAPI_SharedMemorySignalingSemaphore_wait ( struct OSAPI_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 OSAPI_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 OSAPI_SharedMemorySignalingSemaphore_detach should not be called either.
See also:
OSAPI_SharedMemorySignalingSemaphore_signal
RTIBool OSAPI_SharedMemorySignalingSemaphore_detach ( struct OSAPI_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 OSAPI_SharedMemorySignalingSemaphore_attach
See also:
OSAPI_SharedMemorySignalingSemaphore_attach
RTIBool OSAPI_SharedMemorySignalingSemaphore_delete ( struct OSAPI_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 OSAPI_SharedMemorySignalingSemaphore_wait or OSAPI_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 OSAPI_SharedMemorySignalingSemaphore_create
See also:
OSAPI_SharedMemorySignalingSemaphore_create
RTI Connext DDS Micro C API Version 3.0.3 Copyright © Wed Jun 24 2020 Real-Time Innovations, Inc