Condition.h

Go to the documentation of this file.

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef _DECAF_UTIL_CONCURRENT_LOCKS_CONDITION_H_
#define _DECAF_UTIL_CONCURRENT_LOCKS_CONDITION_H_

#include <decaf/util/Config.h>

#include <decaf/util/Date.h>
#include <decaf/util/concurrent/TimeUnit.h>
#include <decaf/lang/exceptions/RuntimeException.h>
#include <decaf/lang/exceptions/InterruptedException.h>
#include <decaf/lang/exceptions/IllegalMonitorStateException.h>

namespace decaf {
namespace util {
namespace concurrent {
namespace locks {

    class DECAF_API Condition {
    public:

        virtual ~Condition();

        virtual void await() = 0;

        virtual void awaitUninterruptibly() = 0;

        virtual long long awaitNanos(long long nanosTimeout) = 0;

        virtual bool await(long long time, const TimeUnit& unit) = 0;

        /*
         * Causes the current thread to wait until it is signaled or interrupted, or the
         * specified deadline elapses.
         *
         * The lock associated with this condition is atomically released and the current
         * thread becomes disabled for thread scheduling purposes and lies dormant until one
         * of five things happens:
         *
         *   * Some other thread invokes the signal() method for this Condition and the
         *     current thread happens to be chosen as the thread to be awakened; or
         *   * Some other thread invokes the signalAll() method for this Condition; or
         *   * Some other thread interrupts the current thread, and interruption of thread
         *     suspension is supported; or
         *   * The specified deadline elapses; or
         *   * A "spurious wakeup" occurs.
         *
         * In all cases, before this method can return the current thread must re-acquire the
         * lock associated with this condition. When the thread returns it is guaranteed to
         * hold this lock.
         *
         * If the current thread:
         *
         *   * has its interrupted status set on entry to this method; or
         *   * is interrupted while waiting and interruption of thread suspension is supported,
         *
         * then InterruptedException is thrown and the current thread's interrupted status is
         * cleared. It is not specified, in the first case, whether or not the test for
         * interruption occurs before the lock is released.
         *
         * The return value indicates whether the deadline has elapsed, which can be used as
         * follows:
         *
         *   bool aMethod( const Date& deadline ) {
         *      bool stillWaiting = true;
         *      while (!conditionBeingWaitedFor) {
         *        if (stillWaiting)
         *            stillWaiting = theCondition->awaitUntil(deadline);
         *         else
         *           return false;
         *      }
         *      // ...
         *   }
         *
         * Implementation Considerations
         *
         * The current thread is assumed to hold the lock associated with this Condition when
         * this method is called. It is up to the implementation to determine if this is the
         * case and if not, how to respond. Typically, an exception will be thrown (such as
         * IllegalMonitorStateException) and the implementation must document that fact.
         *
         * An implementation can favor responding to an interrupt over normal method return
         * in response to a signal, or over indicating the passing of the specified deadline.
         * In either case the implementation must ensure that the signal is redirected to
         * another waiting thread, if there is one.
         *
         * @param deadline - the absolute time to wait until
         *
         * @returns false if the deadline has elapsed upon return, else true
         *
         * @throws RuntimeException
         *         if an unexpected error occurs while trying to wait on the Condition.
         *
         * @throws InterruptedException
         *         if the current thread is interrupted (and interruption of thread suspension
         *         is supported)
         *
         * @throws IllegalMonitorStateException
         *         if the caller is not the lock owner.
         */
        virtual bool awaitUntil(const Date& deadline) = 0;

        virtual void signal() = 0;

        virtual void signalAll() = 0;

    };

}}}}

#endif /*_DECAF_UTIL_CONCURRENT_LOCKS_CONDITION_H_*/