js/public/WaitCallbacks.h

   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/. */
   6
   7 #ifndef js_WaitCallbacks_h
   8 #define js_WaitCallbacks_h
   9
  10 #include <stddef.h>
  11 #include <stdint.h>
  12
  13 #include "jstypes.h"
  14
  15 struct JS_PUBLIC_API JSRuntime;
  16
  17 namespace JS {
  18
  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.
  24  *
  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.)
  27  *
  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.
  33  *
  34  * The value returned by the BeforeWaitCallback will be passed to the
  35  * AfterWaitCallback.
  36  *
  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.
  40  */
  41
  42 static constexpr size_t WAIT_CALLBACK_CLIENT_MAXMEM = 32;
  43
  44 using BeforeWaitCallback = void* (*)(uint8_t* memory);
  45 using AfterWaitCallback = void (*)(void* cookie);
  46
  47 extern JS_PUBLIC_API void SetWaitCallback(JSRuntime* rt,
  48                                           BeforeWaitCallback beforeWait,
  49                                           AfterWaitCallback afterWait,
  50                                           size_t requiredMemory);
  51
  52 }  // namespace JS
  53
  54 #endif  // js_WaitCallbacks_h