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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
/*
* Copyright (C) 2016-2020 Apple Inc. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
* OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#pragma once
#include <wtf/Box.h>
#include <wtf/Condition.h>
#include <wtf/Lock.h>
#include <wtf/ThreadSafeRefCounted.h>
#include <wtf/Threading.h>
#include <wtf/Vector.h>
namespace WTF {
// Often, we create threads that have this as their body:
//
// for (;;) {
// {
// Locker locker { m_lock };
// for (;;) {
// [1] stuff that could break, return, or fall through;
// m_condition.wait(m_lock);
// }
// }
//
// [2] do work;
// }
//
// When we do this, we don't always do a good job of managing this thread's lifetime, which may lead
// to this thread sitting around even when it is not needed.
//
// AutomaticThread is here to help you in these situations. It encapsulates a lock, a condition
// variable, and a thread. It will automatically shut the thread down after a timeout of inactivity.
// You use AutomaticThread by subclassing it, and put any state that is needed between [1] and [2]
// in the subclass.
//
// The terminology we use is:
//
// [1] PollResult AutomaticThread::poll()
// [2] WorkResult AutomaticThread::work()
//
// Note that poll() and work() may not be called on the same thread every time, since this will shut
// down the thread as necessary. This is legal since m_condition.wait(m_lock) can drop the lock, and
// so there is no reason to keep the thread around.
class AutomaticThread;
class AutomaticThreadCondition : public ThreadSafeRefCounted<AutomaticThreadCondition> {
public:
static WTF_EXPORT_PRIVATE Ref<AutomaticThreadCondition> create();
WTF_EXPORT_PRIVATE ~AutomaticThreadCondition();
WTF_EXPORT_PRIVATE void notifyOne(const AbstractLocker&);
WTF_EXPORT_PRIVATE void notifyAll(const AbstractLocker&);
// You can reuse this condition for other things, just as you would any other condition.
// However, since conflating conditions could lead to thundering herd, it's best to avoid it.
// One known-good case for one-true-condition is when the communication involves just two
// threads. In such cases, the thread doing the notifyAll() can wake up at most one thread -
// its partner.
WTF_EXPORT_PRIVATE void wait(Lock& lock) WTF_REQUIRES_LOCK(lock);
WTF_EXPORT_PRIVATE bool waitFor(Lock& lock, Seconds) WTF_REQUIRES_LOCK(lock);
private:
friend class AutomaticThread;
WTF_EXPORT_PRIVATE AutomaticThreadCondition();
void add(const AbstractLocker&, AutomaticThread*);
void remove(const AbstractLocker&, AutomaticThread*);
bool contains(const AbstractLocker&, AutomaticThread*);
Condition m_condition;
Vector<AutomaticThread*> m_threads;
};
class WTF_EXPORT_PRIVATE AutomaticThread : public ThreadSafeRefCounted<AutomaticThread> {
public:
// Note that if you drop all of your references to an AutomaticThread then as soon as there is a
// timeout during which it doesn't get woken up, it will simply die on its own. This is a
// permanent kind of death where the AutomaticThread object goes away, rather than the temporary
// kind of death where AutomaticThread lives but its underlying thread dies. All you have to do
// to prevent permanent death is keep a ref to AutomaticThread. At time of writing, every user of
// AutomaticThread keeps a ref to it and does join() as part of the shutdown process, so only the
// temporary kind of automatic death happens in practice. We keep the permanent death feature
// because it leads to an easy-to-understand reference counting discipline (AutomaticThread holds
// strong ref to AutomaticThreadCondition and the underlying thread holds a strong ref to
// AutomaticThread).
virtual ~AutomaticThread();
// Sometimes it's possible to optimize for the case that there is no underlying thread.
bool hasUnderlyingThread(const AbstractLocker&) const { return m_hasUnderlyingThread; }
// This attempts to quickly stop the thread. This will succeed if the thread happens to not be
// running. Returns true if the thread has been stopped. A good idiom for stopping your automatic
// thread is to first try this, and if that doesn't work, to tell the thread using your own
// mechanism (set some flag and then notify the condition).
bool tryStop(const AbstractLocker&);
bool isWaiting(const AbstractLocker&);
bool notify(const AbstractLocker&);
void join();
virtual ASCIILiteral name() const { return "WTF::AutomaticThread"_s; }
protected:
// This logically creates the thread, but in reality the thread won't be created until someone
// calls AutomaticThreadCondition::notifyOne() or notifyAll().
AutomaticThread(const AbstractLocker&, Box<Lock>, Ref<AutomaticThreadCondition>&&, Seconds timeout = 10_s);
AutomaticThread(const AbstractLocker&, Box<Lock>, Ref<AutomaticThreadCondition>&&, ThreadType, Seconds timeout = 10_s);
// To understand PollResult and WorkResult, imagine that poll() and work() are being called like
// so:
//
// void AutomaticThread::runThread()
// {
// for (;;) {
// {
// Locker locker { m_lock };
// for (;;) {
// PollResult result = poll();
// if (result == PollResult::Work)
// break;
// if (result == PollResult::Stop)
// return;
// RELEASE_ASSERT(result == PollResult::Wait);
// m_condition.wait(m_lock);
// }
// }
//
// WorkResult result = work();
// if (result == WorkResult::Stop)
// return;
// RELEASE_ASSERT(result == WorkResult::Continue);
// }
// }
enum class PollResult { Work, Stop, Wait };
virtual PollResult poll(const AbstractLocker&) = 0;
enum class WorkResult { Continue, Stop };
virtual WorkResult work() = 0;
// It's sometimes useful to allocate resources while the thread is running, and to destroy them
// when the thread dies. These methods let you do this. You can override these methods, and you
// can be sure that the default ones don't do anything (so you don't need a super call).
virtual void threadDidStart();
virtual void threadIsStopping(const AbstractLocker&);
// Control whether this automatic thread should sleep when timeout happens.
// By overriding this function, we can customize how automatic threads will sleep.
// For example, when you have thread pool, you can decrease active threads moderately.
virtual bool shouldSleep(const AbstractLocker&) { return true; }
private:
friend class AutomaticThreadCondition;
void start(const AbstractLocker&);
Box<Lock> m_lock;
Ref<AutomaticThreadCondition> m_condition;
Seconds m_timeout;
ThreadType m_threadType { ThreadType::Unknown };
bool m_isRunning { true };
bool m_isWaiting { false };
bool m_hasUnderlyingThread { false };
Condition m_waitCondition;
Condition m_isRunningCondition;
};
} // namespace WTF
using WTF::AutomaticThread;
using WTF::AutomaticThreadCondition;
|
