Merge mozilla-central to autoland. a=merge CLOSED TREE
[gecko.git] / js / public / WaitCallbacks.h
blobb79172e6c888398153df8690adb513d0c9573aaa
1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 * vim: set ts=8 sts=2 et sw=2 tw=80:
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #ifndef js_WaitCallbacks_h
8 #define js_WaitCallbacks_h
10 #include <stddef.h>
11 #include <stdint.h>
13 #include "jstypes.h"
15 struct JS_PUBLIC_API JSRuntime;
17 namespace JS {
19 /**
20 * When the JSRuntime is about to block in an Atomics.wait() JS call or in a
21 * `wait` instruction in WebAssembly, it can notify the host by means of a call
22 * to BeforeWaitCallback. After the wait, it can notify the host by means of a
23 * call to AfterWaitCallback. Both callbacks must be null, or neither.
25 * (If you change the callbacks from null to not-null or vice versa while some
26 * thread on the runtime is in a wait, you will be sorry.)
28 * The argument to the BeforeWaitCallback is a pointer to uninitialized
29 * stack-allocated working memory of size WAIT_CALLBACK_CLIENT_MAXMEM bytes.
30 * The caller of SetWaitCallback() must pass the amount of memory it will need,
31 * and this amount will be checked against that limit and the process will crash
32 * reliably if the check fails.
34 * The value returned by the BeforeWaitCallback will be passed to the
35 * AfterWaitCallback.
37 * The AfterWaitCallback will be called even if the wakeup is spurious and the
38 * thread goes right back to waiting again. Of course the thread will call the
39 * BeforeWaitCallback once more before it goes to sleep in this situation.
42 static constexpr size_t WAIT_CALLBACK_CLIENT_MAXMEM = 32;
44 using BeforeWaitCallback = void* (*)(uint8_t* memory);
45 using AfterWaitCallback = void (*)(void* cookie);
47 extern JS_PUBLIC_API void SetWaitCallback(JSRuntime* rt,
48 BeforeWaitCallback beforeWait,
49 AfterWaitCallback afterWait,
50 size_t requiredMemory);
52 } // namespace JS
54 #endif // js_WaitCallbacks_h