/usr/include/x86_64-linux-gnu/qcc/windows/Condition.h is in liballjoyn-common-dev-1509 15.09a+dfsg.1-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 | /**
* @file
*
* This file declares a Mesa-Semantics Condition Variable class for Windows
* systems.
*/
/******************************************************************************
*
*
* Copyright AllSeen Alliance. All rights reserved.
*
* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
******************************************************************************/
#ifndef _OS_QCC_CONDITION_H
#define _OS_QCC_CONDITION_H
#include <qcc/platform.h>
#include <qcc/Mutex.h>
#include <Status.h>
namespace qcc {
/**
* Declaration of a Mesa-Semantics condition variable. This class provides the
* mechanism used to implement the system aspects of a condition variable but
* does not implement the variable itself. It would be possible to implement a
* templated virtual class to allow this to all be encapsulated into the the
* condition variable, but in the interests of simplicity and flexibility, that
* is left to the user of this class.
*
* The condition variable was invented to solve the bound buffer problem, and to
* illustrate that use, the following code snippet shows how this class could be
* used to address that type of problem using an STL deque as the protected
* buffer.
*
* Since there are two conditions, buffer empty and buffer full, there are two
* condition variables. There is one Mutex protecting the shared buffer.
* Notice that the Produce() function Wait()s on the full condition and
* Signal()s the empty condition; while the Consume() function Wait()s on the
* empty condition and Signal()s the full condition.
*
* @verbatim
* std::deque<int32_t> prot;
* const uint32_t B_MAX = 2;
*
* qcc:: Condition emtpy;
* qcc:: Condition full;
* qcc::Mutex m;
*
* void Produce(qcc::Condition& empty, qcc::Condition& full, qcc::Mutex& m, uint32_t thing)
* {
* m.Lock();
* while (prot.size() == B_MAX) {
* full.Wait(m);
* }
* prot.push_back(thing);
* empty.Signal();
* m.Unlock();
* }
*
* uint32_t Consume(qcc::Condition& empty, qcc::Condition& full, qcc::Mutex& m)
* {
* m.Lock();
* while (prot.size() == 0) {
* empty.Wait(m);
* }
* uint32_t thing = prot.front();
* prot.pop_front();
* full.Signal();
* m.Unlock();
* return thing;
* }
* @endverbatim
*/
class Condition {
public:
/**
* @brief Construct a condition variable with Mesa semantics.
*/
Condition();
/**
* @brief Destroy a condition variable.
*/
virtual ~Condition();
/**
* @brief Wait on the condition.
*
* A condition variable is always associated with a specific lock. In
* AllJoyn a lock is a Mutex. According to Mesa Semantics, a call to Wait()
* will enqueue the currenly executing thread on the condition variable
* (suspending its execution) and Unlock() the associated Mutex in a single
* atomic action. When the thread resumes exucution the condition variable
* will Lock() the associated mutex and return.
*
* @param m The Mutex associated with the condition variable
*
* @return ER_OK if successful; otherwise an error.
*/
QStatus Wait(qcc::Mutex& m);
/**
* @brief Wait on the condition.
*
* A condition variable is always associated with a specific lock. In
* AllJoyn a lock is a Mutex. According to Mesa Semantics, a call to Wait()
* will enqueue the currenly executing thread on the condition variable
* (suspending its execution) and Unlock() the associated Mutex in a single
* atomic action. When the thread resumes exucution the condition variable
* will Lock() the associated mutex and return.
*
* @param m The Mutex associated with the condition variable.
* @param ms The maximum time to wait for the condition to become signaled.
*
* @return ER_OK if successful; otherwise an error.
*/
QStatus TimedWait(qcc::Mutex& m, uint32_t ms);
/**
* @brief Signal the condition variable waking one thread.
*
* This function examines the queue of threads associated with the condition
* and if at least one thread is blocked waiting on the condition variable,
* exactly one thread will be allowed to resume execution.
*
* @return ER_OK if successful; otherwise an error.
*/
QStatus Signal();
/**
* @brief Signal the condition variable waking all threads
*
* This function examines the queue of threads associated with the condition
* and if any threads are blocked waiting on the condition variable, all
* will be allowed to resume execution.
*
* @return ER_OK if successful; otherwise an error.
*/
QStatus Broadcast();
private:
/**
* The Windows condition variable that is going to do all of the work for us.
*/
CONDITION_VARIABLE c;
/**
* Declare copy constructor private without implementation to prevent usage.
*/
Condition(const Condition& other);
/**
* Declare assignment operator private without implementation to prevent usage.
*/
Condition& operator=(const Condition& other);
};
} // namespace qcc
#endif // _OS_QCC_CONDITION_H
|