blob: 2fe2e4538762f5b26436f85ace601f023a1502de [file] [log] [blame]
/**
* 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_