Shared Memory Signaling Semaphore

Functions
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.
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.
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.
RTIBool	NETIO_SharedMemorySignalingSemaphore_signal (struct NETIO_SharedMemorySignalingSemaphoreHandle *handle, RTI_INT32 *status_out)
	Give the semaphore.
RTIBool	NETIO_SharedMemorySignalingSemaphore_wait (struct NETIO_SharedMemorySignalingSemaphoreHandle *handle, RTI_INT32 *status_out)
	Take the semaphore.
RTIBool	NETIO_SharedMemorySignalingSemaphore_detach (struct NETIO_SharedMemorySignalingSemaphoreHandle *handle)
	Detach from the shared memory binary semaphore.
RTIBool	NETIO_SharedMemorySignalingSemaphore_delete (struct NETIO_SharedMemorySignalingSemaphoreHandle *handle)
	Detach from the shared memory semaphore and deletes it.

Detailed Description

Function Documentation

NETIO_SharedMemorySignalingSemaphore_create()

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]	handle	The shared memory semaphore handle to initialize.
[out]	status_out	Optional: 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]	key	Key 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.

References RTI_INT32.

NETIO_SharedMemorySignalingSemaphore_attach()

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]	handle	The shared memory semaphore handle to initialize.
[out]	status_out	Optional. 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]	key	Key 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

References RTI_INT32.

NETIO_SharedMemorySignalingSemaphore_create_or_attach()

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]	handle	The shared memory semaphore handle to initialize.
[out]	status_out	Optional: 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]	key	Key to identify the shared memory binary semaphore across processes.

Returns

RTI_TRUE on success. RTI_FALSE on error.

References RTI_INT32.

NETIO_SharedMemorySignalingSemaphore_signal()

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]	handle	Handle to the semaphore. Must match the one returned by NETIO_SharedMemorySignalingSemaphore_create
[out]	status_out	Optional: 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

References RTI_INT32.

NETIO_SharedMemorySignalingSemaphore_wait()

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]	handle	Handle to the semaphore. Must match the one returned by NETIO_SharedMemorySignalingSemaphore_create
[out]	status_out	Optional: 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

References RTI_INT32.

NETIO_SharedMemorySignalingSemaphore_detach()

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]

handle

Handle to the shared memory semaphore obtained from NETIO_SharedMemorySignalingSemaphore_attach

See also

NETIO_SharedMemorySignalingSemaphore_attach

NETIO_SharedMemorySignalingSemaphore_delete()

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]

handle

Handle to the shared memory semaphore obtained from NETIO_SharedMemorySignalingSemaphore_create

See also

NETIO_SharedMemorySignalingSemaphore_create