OSAPI_SharedMemoryMonitor

A shared memory monitor to provide mutual exclusion between processes and inter-process signaling. More...

Functions
RTI_SIZE_T	OSAPI_SharedMemoryMonitor_get_size (void)
	Get the amount of memory required to store OSAPI_SharedMemoryMonitor on the current platform.
RTI_BOOL	OSAPI_SharedMemoryMonitor_initialize (RTI_SIZE_T mem_len, void *mem, struct OSAPI_SharedMemoryMonitor **self_out)
	Initialize a shared memory monitor in a provided memory segment.
RTI_BOOL	OSAPI_SharedMemoryMonitor_finalize (struct OSAPI_SharedMemoryMonitor *self)
	Finalize a shared memory monitor.
RTI_BOOL	OSAPI_SharedMemoryMonitor_acquire (struct OSAPI_SharedMemoryMonitor *self, OSAPI_SHMEM_STATUS *status_out)
	Acquire the lock protecting the monitor.
RTI_BOOL	OSAPI_SharedMemoryMonitor_release (struct OSAPI_SharedMemoryMonitor *self)
	Release the lock protecting the monitor.
RTI_BOOL	OSAPI_SharedMemoryMonitor_wait (struct OSAPI_SharedMemoryMonitor *self, OSAPI_SHMEM_STATUS *status_out)
	Wait for the monitor to be signaled.
RTI_BOOL	OSAPI_SharedMemoryMonitor_signal (struct OSAPI_SharedMemoryMonitor *self)
	Signal a thread waiting on a monitor to wake up.
RTI_BOOL	OSAPI_SharedMemoryMonitor_mark_consistent (struct OSAPI_SharedMemoryMonitor *self)
	Mark the shared state protected by the monitor as consistent after a process died while holding the lock on the monitor.

---

Detailed Description

A shared memory monitor to provide mutual exclusion between processes and inter-process signaling.

---

Function Documentation

RTI_SIZE_T OSAPI_SharedMemoryMonitor_get_size

(

void

)

Get the amount of memory required to store OSAPI_SharedMemoryMonitor on the current platform.

Returns:

The number of bytes required to store a shared memory monitor.

RTI_BOOL OSAPI_SharedMemoryMonitor_initialize	(	RTI_SIZE_T	mem_len,
		void *	mem,
		struct OSAPI_SharedMemoryMonitor **	self_out
	)

Initialize a shared memory monitor in a provided memory segment.

Parameters:

[in]	mem_len	Size of provided memory.
[in]	mem	Memory segment.
[out]	self_out	Pointer to initialized monitor.

Returns:

RTI_TRUE on success. RTI_FALSE if an error occurred.

RTI_BOOL OSAPI_SharedMemoryMonitor_finalize

(

struct OSAPI_SharedMemoryMonitor *

self

)

Finalize a shared memory monitor.

Parameters:

[in]

self

Monitor to finalize.

Returns:

RTI_TRUE on success. RTI_FALSE if an error occurred.

Once this function is called (even if it returns RTI_FALSE) you can no longer use this monitor.

RTI_BOOL OSAPI_SharedMemoryMonitor_acquire	(	struct OSAPI_SharedMemoryMonitor *	self,
		OSAPI_SHMEM_STATUS *	status_out
	)

Acquire the lock protecting the monitor.

If this function returns RTI_TRUE, the calling thread is guaranteed mutual exclusion by the monitor. No other thread can acquire the lock until the lock is returned with OSAPI_SharedMemoryMonitor_release. This function shall not be called by a thread which currently holds the lock.

If this function returns status_out=OSAPI_SHMEM_STATUS_OWNER_DEAD, then any shared data protected by the monitor may be in an inconsistent state. If the shared data can be restored to a consistent state, then it can be marked as consistent with OSAPI_SharedMemoryMonitor_mark_consistent. Otherwise, any subsequent attempts to acquire or wait on the monitor will fail.

Parameters:

[in]	self	Monitor to acquire.
[out]	status_out	If successful, the status of the protected state.

Returns:

RTI_TRUE on success. RTI_FALSE if an error occurred.

RTI_BOOL OSAPI_SharedMemoryMonitor_release

(

struct OSAPI_SharedMemoryMonitor *

self

)

Release the lock protecting the monitor.

Parameters:

[in]

self

Monitor to release.

Returns:

RTI_TRUE on success. RTI_FALSE if an error occurred.

This function can only be called on a monitor which is currently locked by the calling thread.

RTI_BOOL OSAPI_SharedMemoryMonitor_wait	(	struct OSAPI_SharedMemoryMonitor *	self,
		OSAPI_SHMEM_STATUS *	status_out
	)

Wait for the monitor to be signaled.

Only one thread can wait on a monitor at any one time. This function can only be called on a monitor which is currently locked by the calling thread. The function will return successfully only when another thread has called OSAPI_SharedMemoryMonitor_signal and when the calling thread has acquired the lock.

If this function returns status_out=OSAPI_SHMEM_STATUS_OWNER_DEAD, then any shared data protected by the monitor may be in an inconsistent state. If the shared data can be restored to a consistent state, then it can be marked as consistent with OSAPI_SharedMemoryMonitor_mark_consistent. Otherwise, any subsequent attempts to acquire or wait on the monitor will fail.

Parameters:

[in]	self	Monitor to wait on.
[out]	status_out	If successful, the status of the protected state.

Returns:

RTI_TRUE on success. RTI_FALSE if an error occurred.

RTI_BOOL OSAPI_SharedMemoryMonitor_signal

(

struct OSAPI_SharedMemoryMonitor *

self

)

Signal a thread waiting on a monitor to wake up.

Parameters:

[in]

self

Monitor to signal.

Returns:

RTI_TRUE on success. RTI_FALSE if an error occurred.

This function can only be called on a monitor which is currently locked by the calling thread.

RTI_BOOL OSAPI_SharedMemoryMonitor_mark_consistent

(

struct OSAPI_SharedMemoryMonitor *

self

)

Mark the shared state protected by the monitor as consistent after a process died while holding the lock on the monitor.

This function can only be called on a monitor which is currently locked by the calling thread and currently inconsistent. The function shall return the monitor to a consistent state and allow other functions to be called on it. This function may not be supported on all platforms.

Parameters:

[in]

self

Monitor to mark consistent.

Returns:

RTI_TRUE on success. RTI_FALSE if an error occurred.