ChorusOS man pages section 2K: Kernel System Calls

monitorNotifyAll(2K)

NAME

monitor, monitorInit, monitorGet, monitorNotify, monitorNotifyAll, monitorRel, monitorWait- initialize a monitor; acquire a monitor; release a monitor; wait within a monitor for notification; notify a thread waiting within a monitor; notify all threads waiting within a monitor

#include <sync/chMonitor.h>

monitor

timeout

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

FEATURES

MONITOR

DESCRIPTION

A monitor is a synchronization object used to protect shared procedures and data against simultaneous access. Once the monitor is acquired by a thread, the thread can suspend its ownership and wait until it is notified or a timeout occurs.

Monitors are KnMonitor structures allocated in memory.

monitorInit() initializes the monitor whose address is monitor . The monitor is initialized as unlocked.

Statically allocated monitors can be initialized using the K_KNMONITOR_INITIALIZER macro, which initializes the monitor as unlocked. This macro is used as follows:

KnMonitor myMonitor = K_KNMONITOR_INITIALIZER

monitorGet() is used by a thread to acquire a monitor. If the monitor is unlocked, it becomes locked by the thread and the caller continues its execution normally. If the monitor is already locked by the current thread, execution also continues normally. If the monitor is locked by another thread, the caller is blocked until the monitor is released.

monitorWait() is used by a thread which has acquired a monitor to relinquish its lock on it, to lie dormant until another thread notifies it using monitorNotify() or monitorNotifyAll() , or until the amount of time specified by timeout has elapsed, and finally to re-acquire its lock on the monitor.

monitorNotify() is used by a thread which has acquired the monitor specified by monitor to notify a thread waiting within monitorWait() to resume. The calling thread must then call monitorRel() so that the waiting thread may actually resume.

monitorNotifyAll() notifies all threads waiting within monitorWait() to resume.

monitorRel() is used by a thread which has acquired a monitor to release it. If threads are blocked behind the monitor, one of them is awakened.

A blocking monitorGet() is NONABORTABLE (see threadAbort(2K) ). monitorWait() is ABORTABLE, that is, when a threadAbort() is addressed to a waiting thread, it behaves as if its time-out had expired.

RESTRICTIONS

A user application and a supervisor application may not share a monitor.

Conversely, two applications running in the same mode (user or supervisor) may share a monitor by mapping it in both address spaces. Such shared monitors must be dynamically allocated monitors. In supervisor mode, the same address may be used by both applications, but care must be taken to keep the monitor's region allocated because the system may crash otherwise.

RETURN VALUES

Upon successful completion, 0 is returned. Otherwise a negative error code is returned.

ERRORS

K_EFAULT: Some of the data provided are outside the address space of the current actor.
K_EINVAL: waitLimit is not a valid KnTimeVal .
K_EINVAL: The calling thread is not the current owner of the monitor on monitorRel , monitorNotify , monitorNotifyAll , monitorWait .

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving