Prefs.h (4041B)
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 }; // namespace JS 110 111 #endif /* js_Prefs_h */