js/public/BuildId.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /**
   7  * Embedding-provided build ID information, used by SpiderMonkey to tag cached
   8  * compilation data so that cached data can be reused when possible, or
   9  * discarded and regenerated if necessary.
  10  */
  11
  12 #ifndef js_BuildId_h
  13 #define js_BuildId_h
  14
  15 #include "jstypes.h"  // JS_PUBLIC_API
  16
  17 #include "js/Vector.h"  // js::Vector
  18
  19 namespace js {
  20
  21 class SystemAllocPolicy;
  22
  23 }  // namespace js
  24
  25 namespace JS {
  26
  27 /** Vector of characters used for holding build ids. */
  28 using BuildIdCharVector = js::Vector<char, 0, js::SystemAllocPolicy>;
  29
  30 /**
  31  * Return the buildId (represented as a sequence of characters) associated with
  32  * the currently-executing build. If the JS engine is embedded such that a
  33  * single cache entry can be observed by different compiled versions of the JS
  34  * engine, it is critical that the buildId shall change for each new build of
  35  * the JS engine.
  36  */
  37 using BuildIdOp = bool (*)(BuildIdCharVector* buildId);
  38
  39 /**
  40  * Embedder hook to set the buildId-generating function.
  41  */
  42 extern JS_PUBLIC_API void SetProcessBuildIdOp(BuildIdOp buildIdOp);
  43
  44 /**
  45  * Some cached data is, in addition to being build-specific, CPU-specific: the
  46  * cached data depends on CPU features like a particular level of SSE support.
  47  *
  48  * This function produces a buildId that includes:
  49  *
  50  *   * the buildId defined by the embedder-provided BuildIdOp set by
  51  *     JS::SetProcessBuildIdOp, and
  52  *   * CPU feature information for the current CPU.
  53  *
  54  * Embedders may use this function to tag cached data whose validity depends
  55  * on having consistent buildId *and* on the CPU supporting features identical
  56  * to those in play when the cached data was computed.
  57  */
  58 [[nodiscard]] extern JS_PUBLIC_API bool GetOptimizedEncodingBuildId(
  59     BuildIdCharVector* buildId);
  60
  61 /**
  62  * Script bytecode is dependent on the buildId and a few other things.
  63  *
  64  * This function produces a buildId that includes:
  65  *
  66  *   * The buildId defined by the embedder-provided BuildIdOp set by
  67  *     JS::SetProcessBuildIdOp.
  68  *   * Additional bytes describing things like endianness, pointer size and
  69  *     other state XDR buffers depend on.
  70  *
  71  * Note: this value may depend on runtime preferences so isn't guaranteed to be
  72  * stable across restarts.
  73  *
  74  * Embedders should use this function to tag transcoded bytecode.
  75  * See Transcoding.h.
  76  */
  77 [[nodiscard]] extern JS_PUBLIC_API bool GetScriptTranscodingBuildId(
  78     BuildIdCharVector* buildId);
  79
  80 }  // namespace JS
  81
  82 #endif /* js_BuildId_h */