ot
class Monitor

By combining a Mutex and ConditionVariable in this way, the Monitor class provides a simple and safe means for making a class thread-safe. However, it should be noted that this gain in simplicity is achieved with some loss of flexibility and, possibly, efficiency. In particular there is no requirement for a ConditionVariable to be associated with a single Mutex, nor is there a requirement for a Mutex to be associated with a single ConditionVariable.

As an example, we show a simple class that implements a thread-safe counter. For the purposes of demonstration, we have decided that whenever the count changes, all waiting threads should be woken so that they can re-inspect the count.

    class ActiveCounter : public Monitor
    {
    public:
        ActiveCounter() : m_count(0) {}

        void updateBy(long diff)
        {
            OT_SYNCHRONIZED  // creates a locked scope
            m_count+=diff;
            notifyAll();      // notifies all waiting threads
        }

        long getValue() const
        {
            OT_SYNCHRONIZED  // creates a locked scope
            return m_count;
        }

    private:
        long m_count;
    };

notify

void notify()

Wakes up one thread that is currently waiting on this Monitor. Before calling this function, the caller must own the lock on this SynchronizedObject. On return from this function, the lock on this SynchronizedObject is still owned.

The following example demonstrates how to obtain the lock before calling the notify() method:-

    void MyObject::doNotify()
    {
        OT_SYNCHRONIZED  // obtain and hold the lock for this object
        ...              // do something interesting
        notify();        // notify a single waiting thread
                         // mutex lock is released at end of scope
    }

See SynchronizedObject for information about the OT_SYNCHRONIZED macro.

Exceptions:

IllegalMonitorStateException - if the caller does not own the lock on this SynchronizedObject

See also:

notifyAll()

notifyAll

void notifyAll()

Wakes up all threads that are currently waiting on this Monitor. When each thread awakes it will compete for the lock on this SynchronizedObject before continuing.

Before calling this function, the caller must own the lock on this SynchronizedObject. On return from this function, the lock on this SynchronizedObject is still owned, and must be released before other threads can execute. See notify() for an example.

Exceptions:

IllegalMonitorStateException - if the caller does not own the lock on this SynchronizedObject

See also:

notify()

wait

void wait()

Atomically releases the lock on this SynchronizedObject and waits for this Monitor to become notified for the current thread. Before calling this function, the caller must own the lock on this SynchronizedObject. On return from this function, the lock on this SynchronizedObject is re-acquired.

The following example demonstrates how to obtain the lock before calling the wait() method:-

    void MyObject::waitForSomething()
    {
        OT_SYNCHRONIZED  // obtain and hold the lock for this object
        wait();          // atomically release the lock and wait for mutex
        ...              // do something interesting
                         // mutex lock is released at end of scope
    }

See SynchronizedObject for information about the OT_SYNCHRONIZED macro.

Exceptions:

IllegalMonitorStateException - if the caller does not own the lock on this SynchronizedObject
InterruptedException - if the current thread is interrupted

See also:

notify() , notifyAll()

wait

void wait(unsigned long millis)

Atomically releases the lock on this SynchronizedObject and waits for up to millis milliseconds for this Monitor to become notified for the current thread. Before calling this function, the caller must own the lock on this SynchronizedObject. On return from this function, the lock on this SynchronizedObject is re-acquired. See wait() for an example of how to achieve this.

Parameters:

millis - the number of milliseconds to wait

Exceptions:

IllegalMonitorStateException - if the caller does not own the lock on this SynchronizedObject
InterruptedException - if the current thread is interrupted

See also:

wait() , notify() , notifyAll()