SUMMARY:  INNER | FIELD | CONSTR | METHOD | FRIEND DETAIL:  FIELD | CONSTR | METHOD | FRIEND


Platform::Thread
Class Monitor

NonCopyableType
   |
   +-ILockable
        |
        +-Mutex
             |
             +-Monitor

Implemented in:
Platform.Thread.Monitor.h

class Monitor:
public Mutex

Represents a monitor synchronization primitive. A monitor provides mutual exclusion among multiple threads accessing a shared resource and cooperation allowing threads to work together towards a common goal.

Every execution thread created by the platform has an implicit monitor object.

Any type implementing Lang::TypeConcepts::SynchronizableType concept inherits an implicit monitor object.

A monitor inherits all of the properties provided by the Mutex type.

A monitor implements wait and notify mechanics allowing threads to block within a monitor and wait until some other thread sends a notify signal resuming the progression of one or multiple waiting threads.

A monitor implements a waiting queue. A thread that is in possession of the monitor (the owner) may suspend itself by calling the wait method. The thread is then blocked, placed in a waiting queue and is relieved of its ownership making the monitor available to other threads. An unlimited number of threads may be blocked on a monitor at any given time.

A thread that is the owner of the monitor may signal the threads placed in the monitor's waiting queue to resume their progress by calling the notify and notifyAll methods on that monitor. The signaled threads are then removed from the monitor's waiting queue and unblocked, and begin to compete for the ownership of the monitor. Whichever thread succeeds in acquiring the monitor (at system scheduler's discression) becomes the new owner of the monitor and can decide whether to proceed its operation or to block and wait on the monitor once again. This is the basic principle of cooperation provided by the monitor.

A monitor supports thread interruption and cancellation by making the wait method a cancellation- and interruption point. Any thread that has created new threads by using Thread::Task may use the task objects as handles to control the child threads. The parent thread may send interrupt and cancel signals using Task::interrupt and Task::cancel methods to the child threads. Once a child thread makes a blocking call that is a cancellation or interruption point an exception will be thrown in the child thread's context, either InterruptSignal or CancelSignal. This is the basic principle of inter-thread communication provided by the platform.

See Also:
Thread::ILockable, Thread::Mutex, Lang::TypeConcepts::SynchronizableType, Task::interrupt, Task::cancel, Thread::InterruptSignal, Thread::CancelSignal
http://en.wikipedia.org/wiki/Monitor_(synchronization)

Fields inherited from class Mutexcollapse
count, owner, state

Constructor Summarycollapse
Monitor()
          Creates a monitor.
~Monitor()
          Destroys this monitor.

Method Summarycollapse
Int notify()
          Unblocks one thread (if any) in this monitor's waiting queue.
Int notifyAll()
          Unblocks all the threads (if any) this monitor's waiting queue.
Bool wait(Int milliseconds = 0)
          Suspends (blocks) the calling thread and places it in the waiting queue of this monitor.

Methods inherited from class ILockablecollapse
acquire, acquire, release, tryAcquire, tryAcquire

Methods inherited from class Mutexcollapse
acquire, acquire, release, tryAcquire, tryAcquire

 

Constructor Detail

Monitor[nothrow, inline]

Monitor()

Creates a monitor. The initial state of the monitor is unacquired, i.e. no thread is in the possession of this monitor.


~Monitor[nothrow, inline]

~Monitor()

Destroys this monitor.

The owner thread must have released the monitor prior to its destruction.

If the owner thread has acquired this monitor multiple times it must release the monitor the corresponding number of times prior to its destruction.

Only the thread that currently owns this monitor may release the monitor.

 

Method Detail

notify[nothrow]

Int notify()

Unblocks one thread (if any) in this monitor's waiting queue.

Returns:
the number of threads that were unblocked and released from the waiting queue (i.e. zero or one)
Remarks:
If the calling thread is not the owner of this monitor this method triggers a run-time error Error_Thread_NotifyInvalidMonitor.
See Also:
Runtime::Error_Thread_NotifyInvalidMonitor, Runtime::ErrorHandler

notifyAll[nothrow]

Int notifyAll()

Unblocks all the threads (if any) this monitor's waiting queue.

Returns:
the number of threads that were unblocked and released from the waiting queue
Remarks:
If the calling thread is not the owner of this monitor this method triggers a run-time error Error_Thread_NotifyInvalidMonitor.
See Also:
Runtime::Error_Thread_NotifyInvalidMonitor, Runtime::ErrorHandler

wait

Bool wait(Int milliseconds = 0)

Suspends (blocks) the calling thread and places it in the waiting queue of this monitor. If the milliseconds parameter is zero, the thread is blocked indefinitely, until it is unblocked by another thread calling notify or notifyAll on this monitor. If the milliseconds parameter is greater than zero then the calling thread is blocked and enqueued in this monitor's waiting queue for the specified amount of time, after which it is unblocked and dequeued and thus no longer is the contender to become the owner of this monitor.

The calling thread must become the owner of this monitor prior to calling this method, i.e. the thread must have acquired the mutex of this monitor by calling acquire first. Once a thread is blocked on this monitor, it releases its ownership of the monitor thus allowing other threads to take over this monitor's ownership. When this method returns, either because of timeout or due to a notify signal from another thread, the ownership of the calling thread is restored.

Parameters:
milliseconds - a timeout, in milliseconds
Returns:
True if the calling thread was unblocked by a notify or notifyAll signal from the owner of this monitor, False if the calling thread was unblocked because of a timeout (only when the milliseconds parameter is greater than zero)
Remarks:
If the calling thread is not the owner of this monitor this method triggers a run-time error Error_Thread_WaitOnInvalidMonitor.
Throws:
Thread::InterruptSignal - if the calling thread received an interrupt signal
Thread::CancelSignal - if the calling thread received a cancel signal
See Also:
Runtime::Error_Thread_WaitOnInvalidMonitor, Runtime::ErrorHandler


SUMMARY:  INNER | FIELD | CONSTR | METHOD | FRIEND DETAIL:  FIELD | CONSTR | METHOD | FRIEND