Shared Memory Mutex API

Functions
RTIBool	NETIO_SharedMemoryMutex_create (struct NETIO_SharedMemoryMutexHandle *handle, RTI_INT32 *status_out, RTI_INT32 key)
	Create a shared memory mutex.
RTIBool	NETIO_SharedMemoryMutex_attach (struct NETIO_SharedMemoryMutexHandle *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_SharedMemoryMutex_create_or_attach (struct NETIO_SharedMemoryMutexHandle *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_SharedMemoryMutex_unlock (struct NETIO_SharedMemoryMutexHandle *handle, RTI_INT32 *status_out)
	Give the semaphore.
RTIBool	NETIO_SharedMemoryMutex_lock (struct NETIO_SharedMemoryMutexHandle *handle, RTI_INT32 *status_out)
	Take the semaphore.
RTIBool	NETIO_SharedMemoryMutex_detach (struct NETIO_SharedMemoryMutexHandle *handle)
	Detach from the shared memory binary semaphore.
RTIBool	NETIO_SharedMemoryMutex_delete (struct NETIO_SharedMemoryMutexHandle *handle)
	Detach from the shared memory semaphore and deletes it.

Detailed Description

Function Documentation

NETIO_SharedMemoryMutex_create()

RTIBool NETIO_SharedMemoryMutex_create	(	struct NETIO_SharedMemoryMutexHandle *	handle,
		RTI_INT32 *	status_out,
		RTI_INT32	key )

Create a shared memory mutex.

Parameters

handle	out Pointer to handle on successful return
status_out	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.
key	in. Key to identify the shared memory semaphore across processes.

Returns

RTI_TRUE on success. RTI_FALSE on error.

References RTI_INT32.

NETIO_SharedMemoryMutex_attach()

RTIBool NETIO_SharedMemoryMutex_attach	(	struct NETIO_SharedMemoryMutexHandle *	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_SharedMemoryMutex_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

handle	out. The shared memory semaphore handle to initialize.
status_out	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.
key	in. 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_SharedMemoryMutex_detach

References RTI_INT32.

NETIO_SharedMemoryMutex_create_or_attach()

RTIBool NETIO_SharedMemoryMutex_create_or_attach	(	struct NETIO_SharedMemoryMutexHandle *	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

handle	inOut. The shared memory semaphore handle to initialize.
status_out	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.
key	in. Key to identify the shared memory binary semaphore across processes.

Returns

RTI_TRUE on success. RTI_FALSE on error.

References RTI_INT32.

NETIO_SharedMemoryMutex_unlock()

RTIBool NETIO_SharedMemoryMutex_unlock	(	struct NETIO_SharedMemoryMutexHandle *	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

handle	in. Handle to the semaphore. Must match the one returned by NETIO_SharedMemoryMutex_create
status_out	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_SharedMemoryMutex_detach.

See also

NETIO_SharedMemorySignalingSemaphore_wait

References RTI_INT32.

NETIO_SharedMemoryMutex_lock()

RTIBool NETIO_SharedMemoryMutex_lock	(	struct NETIO_SharedMemoryMutexHandle *	handle,
		RTI_INT32 *	status_out )

Take the semaphore.

Precondition

Handle in the ATTACHED state.

Postcondition

Semaphore count is decremented.

Parameters

handle	in. Handle to the semaphore. Must match the one returned by NETIO_SharedMemoryMutex_create
status_out	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_SharedMemoryMutex_detach should not be called either.

See also

NETIO_SharedMemorySignalingSemaphore_signal

References RTI_INT32.

NETIO_SharedMemoryMutex_detach()

RTIBool NETIO_SharedMemoryMutex_detach

(

struct NETIO_SharedMemoryMutexHandle *

handle

)

Detach from the shared memory binary semaphore.

Precondition

Handle in the ATTACHED state.

Postcondition

handle in the DETACHED state.

Parameters

handle

in handle. Handle to the shared memory semaphore obtained from NETIO_SharedMemoryMutex_attach

See also

NETIO_SharedMemoryMutex_attach

NETIO_SharedMemoryMutex_delete()

RTIBool NETIO_SharedMemoryMutex_delete

(

struct NETIO_SharedMemoryMutexHandle *

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

handle

in handle. Handle to the shared memory semaphore obtained from NETIO_SharedMemoryMutex_create

See also

NETIO_SharedMemoryMutex_create

References RTI_INT32.