Shared Memory Mutex API

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

---

Detailed Description

---

Function Documentation

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

NETIO_SHMEMDllExport 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

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

NETIO_SHMEMDllExport 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

NETIO_SHMEMDllExport 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

NETIO_SHMEMDllExport 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_SHMEMDllExport 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