js/public/Prefs.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 #ifndef js_Prefs_h
   7 #define js_Prefs_h
   8
   9 #include "js/PrefsGenerated.h"
  10
  11 // [SMDOC] Prefs
  12 //
  13 // JS::Prefs is used to make JS preferences defined in StaticPrefList.yaml
  14 // available to SpiderMonkey code.
  15 //
  16 // Adding a Pref
  17 // =============
  18 // Adding a new pref is easy. For example, if you're adding a new JS feature,
  19 // you could add the following to StaticPrefList.yaml:
  20 //
  21 //   - name: javascript.options.experimental.my_new_feature
  22 //     type: bool
  23 //     value: false
  24 //     mirror: always
  25 //     set_spidermonkey_pref: startup
  26 //
  27 // The value of this pref can then be accessed in SpiderMonkey code with
  28 // |JS::Prefs::experimental_my_new_feature()|.
  29 //
  30 // The default pref value in the YAML file applies to all SpiderMonkey builds
  31 // (browser, JS shell, jsapi-tests, etc), so by default this feature will be
  32 // disabled everywhere.
  33 //
  34 // To enable your feature, use the |--setpref experimental.my_new_feature=true|
  35 // JS shell command line argument, or set the browser pref in about:config.
  36 // Because this is a 'startup' pref, a browser restart is required for this to
  37 // take effect.
  38 //
  39 // The rest of this comment describes more advanced use cases.
  40 //
  41 // Non-startup prefs
  42 // =================
  43 // Setting |set_spidermonkey_pref = startup| is recommended for most prefs.
  44 // In this case the pref is only set during startup so we don't have to worry
  45 // about the pref value changing at runtime.
  46 //
  47 // However, for some prefs this doesn't work. For instance, the WPT test harness
  48 // can set test-specific prefs after startup. To properly update the JS pref in
  49 // this case, |set_spidermonkey_pref = always| must be used. This means the
  50 // SpiderMonkey pref will be updated whenever it's changed in the browser.
  51 //
  52 // Setting Prefs
  53 // =============
  54 // Embedders can override pref values. For startup prefs, this should only be
  55 // done during startup (before calling JS_Init*) to avoid races with worker
  56 // threads and to avoid confusing code with unexpected pref changes:
  57 //
  58 //   JS::Prefs::setAtStartup_experimental_my_new_feature(true);
  59 //
  60 // Non-startup prefs can also be changed after startup:
  61 //
  62 //   JS::Prefs::set_experimental_my_new_feature(true);
  63 //
  64 // JS Shell Prefs
  65 // ==============
  66 // The JS shell |--list-prefs| command line flag will print a list of all of the
  67 // available JS prefs and their current values.
  68 //
  69 // To change a pref, use |--setpref name=value|, for example
  70 // |--setpref experimental.my_new_feature=true|.
  71 //
  72 // It's also possible to add a custom shell flag. In this case you have to
  73 // override the pref value yourself based on this flag.
  74 //
  75 // Testing Functions
  76 // =================
  77 // The |getAllPrefNames()| function will return an array with all JS pref names.
  78 //
  79 // The |getPrefValue(name)| function can be used to look up the value of the
  80 // given pref. For example, use |getPrefValue("experimental.my_new_feature")|
  81 // for the pref defined above.
  82
  83 namespace JS {
  84
  85 class Prefs {
  86   // For each pref, define a static |pref_| member.
  87   JS_PREF_CLASS_FIELDS;
  88
  89 #ifdef DEBUG
  90   static void assertCanSetStartupPref();
  91 #else
  92   static void assertCanSetStartupPref() {}
  93 #endif
  94
  95  public:
  96   // For each pref, define static getter/setter accessors.
  97 #define DEF_GETSET(NAME, CPP_NAME, TYPE, SETTER, IS_STARTUP_PREF) \
  98   static TYPE CPP_NAME() { return CPP_NAME##_; }                  \
  99   static void SETTER(TYPE value) {                                \
 100     if (IS_STARTUP_PREF) {                                        \
 101       assertCanSetStartupPref();                                  \
 102     }                                                             \
 103     CPP_NAME##_ = value;                                          \
 104   }
 105   FOR_EACH_JS_PREF(DEF_GETSET)
 106 #undef DEF_GETSET
 107 };
 108
 109 /**
 110  * Specification for whether weak refs should be enabled and if so whether the
 111  * FinalizationRegistry.cleanupSome method should be present.
 112  */
 113 enum class WeakRefSpecifier {
 114   Disabled,
 115   EnabledWithCleanupSome,
 116   EnabledWithoutCleanupSome
 117 };
 118
 119 inline WeakRefSpecifier GetWeakRefsEnabled() {
 120   if (!Prefs::weakrefs()) {
 121     return WeakRefSpecifier::Disabled;
 122   }
 123   if (Prefs::experimental_weakrefs_expose_cleanupSome()) {
 124     return WeakRefSpecifier::EnabledWithCleanupSome;
 125   }
 126   return WeakRefSpecifier::EnabledWithoutCleanupSome;
 127 }
 128
 129 };  // namespace JS
 130
 131 #endif /* js_Prefs_h */