/**
 *   Copyright 2011-2015 Quickstep Technologies LLC.
 *   Copyright 2015 Pivotal Software, Inc.
 *
 *   Licensed 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 QUICKSTEP_THREADING_CONDITION_VARIABLE_HPP_
#define QUICKSTEP_THREADING_CONDITION_VARIABLE_HPP_

#include <cstdint>

#include "threading/ThreadingConfig.h"

namespace quickstep {

/** \addtogroup Threading
 *  @{
 */

/**
 * @brief A condition variable associated with a Mutex.
 * @note A ConditionVariable should not be created directly. All
 *       ConditionVariables are created by calling
 *       Mutex::createConditionVariable(), and are owned by the Mutex which
 *       creates them.
 * @note This interface exists to provide a central point of documentation for
 *       platform-specific ConditionVariable implementations, you should never
 *       use it directly. Instead, simply use the ConditionVariable class,
 *       which will be typedefed to the appropriate implementation.
 **/
class ConditionVariableInterface {
 public:
  /**
   * @brief Virtual destructor.
   **/
  virtual ~ConditionVariableInterface() = 0;

  /**
   * @brief Block the calling thread and wait for this condition variable to
   *        be signalled.
   * @note Calling this method unlocks the associated Mutex. The calling thread
   *       will automatically acquire a lock on the Mutex again when returning
   *       from this method.
   * @warning The actual predicate this ConditionVariable represents should be
   *          re-checked after this method returns.
   **/
  virtual void await() = 0;

  /**
   * @brief Block the calling thread and wait for this condition variable to
   *        be signalled or after the specified timeout duration.
   * @param milliseconds The timeout period (in milliseconds).
   * @note Calling this method unlocks the associated Mutex. The calling thread
   *       will automatically acquire a lock on the Mutex again when returning
   *       from this method.
   * @warning The actual predicate this ConditionVariable represents should be
   *          re-checked after this method returns.
   *
   * @return Return true if this condition variable is signalled. Return false
   *         if the specified timeout expired.
   **/
  virtual bool awaitWithTimeout(std::uint64_t milliseconds) = 0;

  /**
   * @brief Wake up a single thread which is waiting on this ConditionVariable.
   * @note This method has no effect if no threads are waiting on this
   *       ConditionVariable.
   * @note This method can be called whether or not the associated Mutex is
   *       locked. If called while holding the lock, the waiting thread will
   *       not actually resume until the Mutex is unlocked so that it can be
   *       reacquired by the waiting thread.
   **/
  virtual void signalOne() = 0;

  /**
   * @brief Wake up all threads which are waiting on this ConditionVariable.
   * @note This method has no effect if no threads are waiting on this
   *       ConditionVariable.
   * @note This method can be called whether or not the associated Mutex is
   *       locked. If called while holding the lock, the waiting threads will
   *       not actually resume until the Mutex is unlocked so that it can be
   *       reacquired by waiting threads.
   * @note If multiple threads are waiting on this condition variable, they
   *       will be woken up one-at-a-time, since each one will re-acquire the
   *       Mutex as it wakes.
   **/
  virtual void signalAll() = 0;
};

/** @} */

}  // namespace quickstep

#ifdef QUICKSTEP_HAVE_CPP11_THREADS
#include "threading/cpp11/ConditionVariable.hpp"
#endif

#ifdef QUICKSTEP_HAVE_POSIX_THREADS
#include "threading/posix/ConditionVariable.hpp"
#endif

#ifdef QUICKSTEP_HAVE_WINDOWS_THREADS
#include "threading/windows/ConditionVariable.hpp"
#endif

#endif  // QUICKSTEP_THREADING_CONDITION_VARIABLE_HPP_