Monitors

Monitor creation, locking, unlocking, and freeing. More...

Functions
syscall	lock (monitor mon)
syscall	moncount (monitor mon)
monitor	moncreate (void)
syscall	monfree (monitor mon)
syscall	unlock (monitor mon)

Detailed Description

Monitor creation, locking, unlocking, and freeing.

Function Documentation

syscall lock

(

monitor

mon

)

Lock a monitor.

If no thread owns the monitor, its owner is set to the current thread and its count is set to 1.

If the current thread already owns the monitor, its count is incremented and no further action is taken.

If another thread owns the monitor, the current thread waits for the monitor to become fully unlocked by that thread, then sets its owner to the current thread and its count to 1.

Parameters

mon	The monitor to lock.

Returns

::OK on success; ::SYSERR on failure (mon did not specify a valid, allocated monitor).

syscall moncount

(

monitor

mon

)

Retrieve the count of a monitor — that is, the number of times it has been locked by the owning thread, or 0 if no thread currently owns the monitor.

This function performs no locking. The caller must temporarily disable interrupts if the specified monitor could potentially be freed, locked, or unlocked concurrently.

Parameters

mon	The monitor to retrieve the count of.

Returns

If mon specified a valid, allocated monitor, its count is returned. Otherwise, ::SYSERR is returned.

monitor moncreate

(

void

)

Create and initialize a new monitor.

Returns

On success, returns the new monitor. On failure (system is out of monitors or semaphores), returns ::SYSERR.

syscall monfree

(

monitor

mon

)

Free a monitor previously allocated with moncreate().

A monitor must only be freed when no thread has it locked – that is, either the monitor is unowned, or is owned by a thread that has been killed.

Parameters

mon	The monitor to free.

Returns

::OK on success; ::SYSERR on failure (mon did not specify a valid, allocated monitor).

syscall unlock

(

monitor

mon

)

Unlock a monitor.

The monitor's lock count (indicating the number of times the owning thread has locked the monitor) is decremented. If the count remains greater than zero, no further action is taken. If the count reaches zero, the monitor is set to unowned and up to one thread that may be waiting to lock() the monitor is awakened.

This normally should be called by the owning thread of the monitor subsequently to a lock() by the same thread, but this also may be called moncount(mon) times to fully unlock a monitor that was owned by a thread that has been killed.

Parameters

mon	The monitor to unlock.

Returns

::OK on success; ::SYSERR on failure (mon did not specify a valid, allocated monitor with nonzero lock count).