eee53ae6f3f613ce57cc166ffb7f9a4a3c4f468d
[WebKit-https.git] / Source / WTF / wtf / Threading.h
1 /*
2  * Copyright (C) 2007-2018 Apple Inc. All rights reserved.
3  * Copyright (C) 2007 Justin Haygood <jhaygood@reaktix.com>
4  * Copyright (C) 2017 Yusuke Suzuki <utatane.tea@gmail.com>
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  *
10  * 1.  Redistributions of source code must retain the above copyright
11  *     notice, this list of conditions and the following disclaimer. 
12  * 2.  Redistributions in binary form must reproduce the above copyright
13  *     notice, this list of conditions and the following disclaimer in the
14  *     documentation and/or other materials provided with the distribution. 
15  * 3.  Neither the name of Apple Inc. ("Apple") nor the names of
16  *     its contributors may be used to endorse or promote products derived
17  *     from this software without specific prior written permission. 
18  *
19  * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY
20  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
21  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22  * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY
23  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
26  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30
31 #pragma once
32
33 #include <mutex>
34 #include <stdint.h>
35 #include <wtf/Atomics.h>
36 #include <wtf/Expected.h>
37 #include <wtf/FastTLS.h>
38 #include <wtf/Function.h>
39 #include <wtf/PlatformRegisters.h>
40 #include <wtf/Ref.h>
41 #include <wtf/RefPtr.h>
42 #include <wtf/StackBounds.h>
43 #include <wtf/StackStats.h>
44 #include <wtf/ThreadSafeRefCounted.h>
45 #include <wtf/ThreadSpecific.h>
46 #include <wtf/Vector.h>
47 #include <wtf/WordLock.h>
48 #include <wtf/text/AtomicStringTable.h>
49
50 #if USE(PTHREADS) && !OS(DARWIN)
51 #include <signal.h>
52 #endif
53
54 namespace WTF {
55
56 class AbstractLocker;
57 class ThreadMessageData;
58
59 enum class ThreadGroupAddResult;
60
61 class ThreadGroup;
62 class PrintStream;
63
64 WTF_EXPORT_PRIVATE bool threadingIsInitialized();
65
66 // This function can be called from any threads.
67 WTF_EXPORT_PRIVATE void initializeThreading();
68
69 #if USE(PTHREADS)
70
71 // We use SIGUSR1 to suspend and resume machine threads in JavaScriptCore.
72 constexpr const int SigThreadSuspendResume = SIGUSR1;
73
74 #endif
75
76 // FIXME: The following functions remain because they are used from WebKit Windows support library,
77 // WebKitQuartzCoreAdditions.dll. When updating the support library, we should use new API instead
78 // and the following workaound should be removed. And new code should not use the following APIs.
79 // Remove this workaround code when <rdar://problem/31793213> is fixed.
80 #if OS(WINDOWS)
81 WTF_EXPORT_PRIVATE ThreadIdentifier createThread(ThreadFunction, void*, const char* threadName);
82 WTF_EXPORT_PRIVATE int waitForThreadCompletion(ThreadIdentifier);
83 #endif
84
85 class Thread : public ThreadSafeRefCounted<Thread> {
86 public:
87     friend class ThreadGroup;
88     friend WTF_EXPORT_PRIVATE void initializeThreading();
89 #if OS(WINDOWS)
90     friend WTF_EXPORT_PRIVATE int waitForThreadCompletion(ThreadIdentifier);
91 #endif
92
93     WTF_EXPORT_PRIVATE ~Thread();
94
95     // Returns nullptr if thread creation failed.
96     // The thread name must be a literal since on some platforms it's passed in to the thread.
97     WTF_EXPORT_PRIVATE static Ref<Thread> create(const char* threadName, Function<void()>&&);
98
99     // Returns Thread object.
100     static Thread& current();
101
102 #if OS(WINDOWS)
103     // Returns ThreadIdentifier directly. It is useful if the user only cares about identity
104     // of threads. At that time, users should know that holding this ThreadIdentifier does not ensure
105     // that the thread information is alive. While Thread::current() is not safe if it is called
106     // from the destructor of the other TLS data, currentID() always returns meaningful thread ID.
107     WTF_EXPORT_PRIVATE static ThreadIdentifier currentID();
108
109     ThreadIdentifier id() const { return m_id; }
110 #endif
111
112     WTF_EXPORT_PRIVATE void changePriority(int);
113     WTF_EXPORT_PRIVATE int waitForCompletion();
114     WTF_EXPORT_PRIVATE void detach();
115
116 #if OS(DARWIN)
117     using PlatformSuspendError = kern_return_t;
118 #elif USE(PTHREADS)
119     using PlatformSuspendError = int;
120 #elif OS(WINDOWS)
121     using PlatformSuspendError = DWORD;
122 #endif
123
124     WTF_EXPORT_PRIVATE Expected<void, PlatformSuspendError> suspend();
125     WTF_EXPORT_PRIVATE void resume();
126     WTF_EXPORT_PRIVATE size_t getRegisters(PlatformRegisters&);
127
128 #if USE(PTHREADS)
129     WTF_EXPORT_PRIVATE bool signal(int signalNumber);
130 #endif
131
132     // Mark the current thread as requiring UI responsiveness.
133     // relativePriority is a value in the range [-15, 0] where a lower value indicates a lower priority.
134     WTF_EXPORT_PRIVATE static void setCurrentThreadIsUserInteractive(int relativePriority = 0);
135     WTF_EXPORT_PRIVATE static void setCurrentThreadIsUserInitiated(int relativePriority = 0);
136
137 #if HAVE(QOS_CLASSES)
138     WTF_EXPORT_PRIVATE static void setGlobalMaxQOSClass(qos_class_t);
139     WTF_EXPORT_PRIVATE static qos_class_t adjustedQOSClass(qos_class_t);
140 #endif
141
142     // Called in the thread during initialization.
143     // Helpful for platforms where the thread name must be set from within the thread.
144     static void initializeCurrentThreadInternal(const char* threadName);
145     static void initializeCurrentThreadEvenIfNonWTFCreated();
146     
147     WTF_EXPORT_PRIVATE static const unsigned lockSpinLimit;
148     WTF_EXPORT_PRIVATE static void yield();
149
150     WTF_EXPORT_PRIVATE void dump(PrintStream& out) const;
151
152     static void initializePlatformThreading();
153
154     const StackBounds& stack() const
155     {
156         return m_stack;
157     }
158
159     AtomicStringTable* atomicStringTable()
160     {
161         return m_currentAtomicStringTable;
162     }
163
164     AtomicStringTable* setCurrentAtomicStringTable(AtomicStringTable* atomicStringTable)
165     {
166         AtomicStringTable* oldAtomicStringTable = m_currentAtomicStringTable;
167         m_currentAtomicStringTable = atomicStringTable;
168         return oldAtomicStringTable;
169     }
170
171 #if ENABLE(STACK_STATS)
172     StackStats::PerThreadStats& stackStats()
173     {
174         return m_stackStats;
175     }
176 #endif
177
178     void* savedStackPointerAtVMEntry()
179     {
180         return m_savedStackPointerAtVMEntry;
181     }
182
183     void setSavedStackPointerAtVMEntry(void* stackPointerAtVMEntry)
184     {
185         m_savedStackPointerAtVMEntry = stackPointerAtVMEntry;
186     }
187
188     void* savedLastStackTop()
189     {
190         return m_savedLastStackTop;
191     }
192
193     void setSavedLastStackTop(void* lastStackTop)
194     {
195         m_savedLastStackTop = lastStackTop;
196     }
197
198 #if OS(DARWIN)
199     mach_port_t machThread() { return m_platformThread; }
200 #endif
201
202     struct NewThreadContext;
203     static void entryPoint(NewThreadContext*);
204 protected:
205     Thread() = default;
206
207     void initializeInThread();
208
209     // Internal platform-specific Thread establishment implementation.
210     bool establishHandle(NewThreadContext*);
211
212 #if USE(PTHREADS)
213     void establishPlatformSpecificHandle(PlatformThreadHandle);
214 #else
215     void establishPlatformSpecificHandle(PlatformThreadHandle, ThreadIdentifier);
216 #endif
217
218 #if USE(PTHREADS) && !OS(DARWIN)
219     static void signalHandlerSuspendResume(int, siginfo_t*, void* ucontext);
220 #endif
221
222     static const char* normalizeThreadName(const char* threadName);
223
224     enum JoinableState : uint8_t {
225         // The default thread state. The thread can be joined on.
226         Joinable,
227
228         // Somebody waited on this thread to exit and this thread finally exited. This state is here because there can be a
229         // period of time between when the thread exits (which causes pthread_join to return and the remainder of waitOnThreadCompletion to run)
230         // and when threadDidExit is called. We need threadDidExit to take charge and delete the thread data since there's
231         // nobody else to pick up the slack in this case (since waitOnThreadCompletion has already returned).
232         Joined,
233
234         // The thread has been detached and can no longer be joined on. At this point, the thread must take care of cleaning up after itself.
235         Detached,
236     };
237
238     JoinableState joinableState() { return m_joinableState; }
239     void didBecomeDetached() { m_joinableState = Detached; }
240     void didExit();
241     void didJoin() { m_joinableState = Joined; }
242     bool hasExited() { return m_didExit; }
243
244     // These functions are only called from ThreadGroup.
245     ThreadGroupAddResult addToThreadGroup(const AbstractLocker& threadGroupLocker, ThreadGroup&);
246     void removeFromThreadGroup(const AbstractLocker& threadGroupLocker, ThreadGroup&);
247
248     // The Thread instance is ref'ed and held in thread-specific storage. It will be deref'ed by destructTLS at thread destruction time.
249     // For pthread, it employs pthreads-specific 2-pass destruction to reliably remove Thread.
250     // For Windows, we use thread_local to defer thread TLS destruction. It assumes regular ThreadSpecific
251     // types don't use multiple-pass destruction.
252
253 #if !HAVE(FAST_TLS)
254     static WTF_EXPORT_PRIVATE ThreadSpecificKey s_key;
255     // One time initialization for this class as a whole.
256     // This method must be called before initializeTLS() and it is not thread-safe.
257     static void initializeTLSKey();
258 #endif
259
260     // Creates and puts an instance of Thread into thread-specific storage.
261     static Thread& initializeTLS(Ref<Thread>&&);
262     WTF_EXPORT_PRIVATE static Thread& initializeCurrentTLS();
263
264     // Returns nullptr if thread-specific storage was not initialized.
265     static Thread* currentMayBeNull();
266
267 #if OS(WINDOWS)
268     WTF_EXPORT_PRIVATE static Thread* currentDying();
269     static RefPtr<Thread> get(ThreadIdentifier);
270 #endif
271
272     // This thread-specific destructor is called 2 times when thread terminates:
273     // - first, when all the other thread-specific destructors are called, it simply remembers it was 'destroyed once'
274     // and (1) re-sets itself into the thread-specific slot or (2) constructs thread local value to call it again later.
275     // - second, after all thread-specific destructors were invoked, it gets called again - this time, we remove the
276     // Thread from the threadMap, completing the cleanup.
277     static void THREAD_SPECIFIC_CALL destructTLS(void* data);
278
279     JoinableState m_joinableState { Joinable };
280     bool m_isShuttingDown { false };
281     bool m_didExit { false };
282     bool m_isDestroyedOnce { false };
283
284     // Lock & ParkingLot rely on ThreadSpecific. But Thread object can be destroyed even after ThreadSpecific things are destroyed.
285     // Use WordLock since WordLock does not depend on ThreadSpecific and this "Thread".
286     WordLock m_mutex;
287     StackBounds m_stack { StackBounds::emptyBounds() };
288     Vector<std::weak_ptr<ThreadGroup>> m_threadGroups;
289     PlatformThreadHandle m_handle;
290 #if OS(WINDOWS)
291     ThreadIdentifier m_id { 0 };
292 #elif OS(DARWIN)
293     mach_port_t m_platformThread { MACH_PORT_NULL };
294 #elif USE(PTHREADS)
295     PlatformRegisters* m_platformRegisters { nullptr };
296     unsigned m_suspendCount { 0 };
297 #endif
298
299     AtomicStringTable* m_currentAtomicStringTable { nullptr };
300     AtomicStringTable m_defaultAtomicStringTable;
301
302 #if ENABLE(STACK_STATS)
303     StackStats::PerThreadStats m_stackStats;
304 #endif
305     void* m_savedStackPointerAtVMEntry { nullptr };
306     void* m_savedLastStackTop;
307 public:
308     void* m_apiData { nullptr };
309 };
310
311 inline Thread* Thread::currentMayBeNull()
312 {
313 #if !HAVE(FAST_TLS)
314     ASSERT(s_key != InvalidThreadSpecificKey);
315     return static_cast<Thread*>(threadSpecificGet(s_key));
316 #else
317     return static_cast<Thread*>(_pthread_getspecific_direct(WTF_THREAD_DATA_KEY));
318 #endif
319 }
320
321 inline Thread& Thread::current()
322 {
323     // WRT WebCore:
324     //    Thread::current() is used on main thread before it could possibly be used
325     //    on secondary ones, so there is no need for synchronization here.
326     // WRT JavaScriptCore:
327     //    Thread::initializeTLSKey() is initially called from initializeThreading(), ensuring
328     //    this is initially called in a std::call_once locked context.
329 #if !HAVE(FAST_TLS)
330     if (UNLIKELY(Thread::s_key == InvalidThreadSpecificKey))
331         WTF::initializeThreading();
332 #endif
333     if (auto* thread = currentMayBeNull())
334         return *thread;
335 #if OS(WINDOWS)
336     if (auto* thread = currentDying())
337         return *thread;
338 #endif
339     return initializeCurrentTLS();
340 }
341
342 } // namespace WTF
343
344 using WTF::Thread;
345
346 #if OS(WINDOWS)
347 using WTF::ThreadIdentifier;
348 using WTF::createThread;
349 using WTF::waitForThreadCompletion;
350 #endif