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
176
177
178
179
180
181
|
// Copyright (c) 2011 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef BASE_SYNCHRONIZATION_WAITABLE_EVENT_H_
#define BASE_SYNCHRONIZATION_WAITABLE_EVENT_H_
#pragma once
#include "base/base_export.h"
#include "base/basictypes.h"
#if defined(OS_WIN)
#include <windows.h>
#endif
#if defined(OS_POSIX)
#include <list>
#include <utility>
#include "base/memory/ref_counted.h"
#include "base/synchronization/lock.h"
#endif
namespace base {
// This replaces INFINITE from Win32
static const int kNoTimeout = -1;
class TimeDelta;
// A WaitableEvent can be a useful thread synchronization tool when you want to
// allow one thread to wait for another thread to finish some work. For
// non-Windows systems, this can only be used from within a single address
// space.
//
// Use a WaitableEvent when you would otherwise use a Lock+ConditionVariable to
// protect a simple boolean value. However, if you find yourself using a
// WaitableEvent in conjunction with a Lock to wait for a more complex state
// change (e.g., for an item to be added to a queue), then you should probably
// be using a ConditionVariable instead of a WaitableEvent.
//
// NOTE: On Windows, this class provides a subset of the functionality afforded
// by a Windows event object. This is intentional. If you are writing Windows
// specific code and you need other features of a Windows event, then you might
// be better off just using an Windows event directly.
class BASE_EXPORT WaitableEvent {
public:
// If manual_reset is true, then to set the event state to non-signaled, a
// consumer must call the Reset method. If this parameter is false, then the
// system automatically resets the event state to non-signaled after a single
// waiting thread has been released.
WaitableEvent(bool manual_reset, bool initially_signaled);
#if defined(OS_WIN)
// Create a WaitableEvent from an Event HANDLE which has already been
// created. This objects takes ownership of the HANDLE and will close it when
// deleted.
explicit WaitableEvent(HANDLE event_handle);
// Releases ownership of the handle from this object.
HANDLE Release();
#endif
~WaitableEvent();
// Put the event in the un-signaled state.
void Reset();
// Put the event in the signaled state. Causing any thread blocked on Wait
// to be woken up.
void Signal();
// Returns true if the event is in the signaled state, else false. If this
// is not a manual reset event, then this test will cause a reset.
bool IsSignaled();
// Wait indefinitely for the event to be signaled. Returns true if the event
// was signaled, else false is returned to indicate that waiting failed.
bool Wait();
// Wait up until max_time has passed for the event to be signaled. Returns
// true if the event was signaled. If this method returns false, then it
// does not necessarily mean that max_time was exceeded.
bool TimedWait(const TimeDelta& max_time);
#if defined(OS_WIN)
HANDLE handle() const { return handle_; }
#endif
// Wait, synchronously, on multiple events.
// waitables: an array of WaitableEvent pointers
// count: the number of elements in @waitables
//
// returns: the index of a WaitableEvent which has been signaled.
//
// You MUST NOT delete any of the WaitableEvent objects while this wait is
// happening.
static size_t WaitMany(WaitableEvent** waitables, size_t count);
// For asynchronous waiting, see WaitableEventWatcher
// This is a private helper class. It's here because it's used by friends of
// this class (such as WaitableEventWatcher) to be able to enqueue elements
// of the wait-list
class Waiter {
public:
// Signal the waiter to wake up.
//
// Consider the case of a Waiter which is in multiple WaitableEvent's
// wait-lists. Each WaitableEvent is automatic-reset and two of them are
// signaled at the same time. Now, each will wake only the first waiter in
// the wake-list before resetting. However, if those two waiters happen to
// be the same object (as can happen if another thread didn't have a chance
// to dequeue the waiter from the other wait-list in time), two auto-resets
// will have happened, but only one waiter has been signaled!
//
// Because of this, a Waiter may "reject" a wake by returning false. In
// this case, the auto-reset WaitableEvent shouldn't act as if anything has
// been notified.
virtual bool Fire(WaitableEvent* signaling_event) = 0;
// Waiters may implement this in order to provide an extra condition for
// two Waiters to be considered equal. In WaitableEvent::Dequeue, if the
// pointers match then this function is called as a final check. See the
// comments in ~Handle for why.
virtual bool Compare(void* tag) = 0;
protected:
virtual ~Waiter() {}
};
private:
friend class WaitableEventWatcher;
#if defined(OS_WIN)
HANDLE handle_;
#else
// On Windows, one can close a HANDLE which is currently being waited on. The
// MSDN documentation says that the resulting behaviour is 'undefined', but
// it doesn't crash. However, if we were to include the following members
// directly then, on POSIX, one couldn't use WaitableEventWatcher to watch an
// event which gets deleted. This mismatch has bitten us several times now,
// so we have a kernel of the WaitableEvent, which is reference counted.
// WaitableEventWatchers may then take a reference and thus match the Windows
// behaviour.
struct WaitableEventKernel :
public RefCountedThreadSafe<WaitableEventKernel> {
public:
WaitableEventKernel(bool manual_reset, bool initially_signaled);
virtual ~WaitableEventKernel();
bool Dequeue(Waiter* waiter, void* tag);
base::Lock lock_;
const bool manual_reset_;
bool signaled_;
std::list<Waiter*> waiters_;
};
typedef std::pair<WaitableEvent*, size_t> WaiterAndIndex;
// When dealing with arrays of WaitableEvent*, we want to sort by the address
// of the WaitableEvent in order to have a globally consistent locking order.
// In that case we keep them, in sorted order, in an array of pairs where the
// second element is the index of the WaitableEvent in the original,
// unsorted, array.
static size_t EnqueueMany(WaiterAndIndex* waitables,
size_t count, Waiter* waiter);
bool SignalAll();
bool SignalOne();
void Enqueue(Waiter* waiter);
scoped_refptr<WaitableEventKernel> kernel_;
#endif
DISALLOW_COPY_AND_ASSIGN(WaitableEvent);
};
} // namespace base
#endif // BASE_SYNCHRONIZATION_WAITABLE_EVENT_H_
|
