Bug 1555582 - Fix up StaticPrefList.h. r=jya
authorNicholas Nethercote <nnethercote@mozilla.com>
Fri, 31 May 2019 05:32:19 +0000
changeset 476319 fb18d0ab83796cd7496b19dddeb25c4688e89aa2
parent 476318 f2b37969fe0b44b5e811caa4e8f0e1ef347f4371
child 476320 ca8e3e6b3a825ff13012bc6029d767b54cdf573a
push id36092
push userarchaeopteryx@coole-files.de
push dateFri, 31 May 2019 17:03:46 +0000
treeherdermozilla-central@8384972e1f6a [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersjya
bugs1555582
milestone69.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1555582 - Fix up StaticPrefList.h. r=jya - Clarify some of the text. - Make section headings accurate and consistent. - Move sections that aren't in alphabetical order. Differential Revision: https://phabricator.services.mozilla.com/D33129
modules/libpref/init/StaticPrefList.h
--- a/modules/libpref/init/StaticPrefList.h
+++ b/modules/libpref/init/StaticPrefList.h
@@ -9,20 +9,20 @@
 //
 // If a pref is listed here and also in a prefs data file such as all.js, the
 // value from the latter will override the value given here. For vanilla
 // browser builds such overrides are discouraged, but they are necessary for
 // some configurations (e.g. Thunderbird).
 //
 // The file is separated into sections, where the sections are determined by
 // the first segment of the prefnames within (e.g. "network.predictor.enabled"
-// is within the "Network" section). Sections must be kept in alphabetical
-// order, but prefs within sections need not be.
-// Please follow the existing naming convention when considering adding a new
-// pref and whether you need a new section.
+// is within the `Prefs starting with "network."` section). Sections must be
+// kept in alphabetical order, but prefs within sections need not be. Please
+// follow the existing naming convention when considering adding a new pref and
+// whether you need a new section.
 //
 // Normal prefs
 // ------------
 // Definitions of normal prefs in this file have the following form.
 //
 //   PREF(<pref-name-string>, <cpp-type>, <default-value>)
 //
 // - <pref-name-string> is the name of the pref, as it appears in about:config.
@@ -32,21 +32,26 @@
 //   typedef for `const char*` in StaticPrefs.h). Note that float prefs are
 //   stored internally as strings.
 //
 // - <default-value> is the default value. Its type should match <cpp-type>.
 //
 // VarCache prefs
 // --------------
 // A VarCache pref is a special type of pref. It can be accessed via the normal
-// pref hash table lookup functions, but it also has an associated global
-// variable (the VarCache) that mirrors the pref value in the prefs hash table,
-// and a getter function that reads that global variable. Using the getter to
-// read the pref's value has the two following advantages over the normal API
-// functions.
+// pref hash table lookup functions, but it also has:
+//
+// - an associated global variable (the VarCache) that mirrors the pref value
+//   in the prefs hash table (unless the update policy is `Skip` or `Once`, see
+//   below); and
+//
+// - a getter function that reads that global variable.
+//
+// Using the getter to read the pref's value has the two following advantages
+// over the normal API functions.
 //
 // - A direct global variable access is faster than a hash table lookup.
 //
 // - A global variable can be accessed off the main thread. If a pref *is*
 //   accessed off the main thread, it should use an atomic type. (But note that
 //   many VarCaches that should be atomic are not, in particular because
 //   Atomic<float> is not available, alas.)
 //
@@ -54,24 +59,28 @@
 //
 //   VARCACHE_PREF(
 //     <update-policy>,
 //     <pref-name-string>,
 //     <pref-name-id>,
 //     <cpp-type>, <default-value>
 //   )
 //
-// - <update-policy> is one of the following: Skip, Once, Live
-//      Skip: Set the value to <default-value>, skip any Preferences calls.
-//            This policy should be rarely used and its use is discouraged.
-//      Once: Evaluate the pref once, and unchanged during the session once
-//            enterprisepolicies have been loaded.
-//            This is useful for features where you want to ignore any pref
-//            changes until the start of the next browser session.
-//      Live: Evaluate the pref and set callback so it stays current/live.
+// - <update-policy> is one of the following:
+//
+//   * Live: Evaluate the pref and set callback so it stays current/live. This
+//     is the normal policy.
+//
+//   * Skip: Set the value to <default-value>, skip any Preferences calls. This
+//     policy should be rarely used and its use is discouraged.
+//
+//   * Once: Evaluate the pref once, and unchanged during the session once
+//     enterprise policies have been loaded. This is useful for features where
+//     you want to ignore any pref changes until the start of the next browser
+//     session.
 //
 // - <pref-name-string> is the same as for normal prefs.
 //
 // - <pref-name-id> is the name of the static getter function generated within
 //   the StaticPrefs class. For consistency, the identifier for every pref
 //   should be created by starting with <pref-name-string> and converting any
 //   '.' or '-' chars to '_'. For example, "foo.bar_baz" becomes
 //   |foo_bar_baz|. This is arguably ugly, but clear, and you can search for
@@ -915,17 +924,17 @@ VARCACHE_PREF(
 VARCACHE_PREF(
   Live,
   "channelclassifier.allowlist_example",
   channelclassifier_allowlist_example,
   bool, false
 )
 
 //---------------------------------------------------------------------------
-// Prefs starting with "Clipboard."
+// Prefs starting with "clipboard."
 //---------------------------------------------------------------------------
 
 #if !defined(ANDROID) && !defined(XP_MACOSX) && defined(XP_UNIX)
 # define PREF_VALUE true
 #else
 # define PREF_VALUE false
 #endif
 VARCACHE_PREF(
@@ -2230,17 +2239,17 @@ VARCACHE_PREF(
 VARCACHE_PREF(
   Live,
   "extensions.cookiesBehavior.overrideOnTopLevel",
   extensions_cookiesBehavior_overrideOnTopLevel,
   bool, false
 )
 
 //---------------------------------------------------------------------------
-// Full-screen prefs
+// Prefs starting with "full-screen-api."
 //---------------------------------------------------------------------------
 
 VARCACHE_PREF(
   Live,
   "full-screen-api.enabled",
   full_screen_api_enabled,
   bool, false
 )
@@ -2255,19 +2264,19 @@ VARCACHE_PREF(
 VARCACHE_PREF(
   Live,
   "full-screen-api.allow-trusted-requests-only",
   full_screen_api_allow_trusted_requests_only,
   bool, true
 )
 
 //---------------------------------------------------------------------------
-// Prefs starting with "Fuzzing.". It's important that these can only be checked in fuzzing
-// builds (when FUZZING is defined), otherwise you could enable the fuzzing
-// stuff on your regular build which would be bad :)
+// Prefs starting with "fuzzing.". It's important that these can only be
+// checked in fuzzing builds (when FUZZING is defined), otherwise you could
+// enable the fuzzing stuff on your regular build which would be bad :)
 //---------------------------------------------------------------------------
 
 #ifdef FUZZING
 VARCACHE_PREF(
   Live,
   "fuzzing.enabled",
   fuzzing_enabled,
   bool, false
@@ -2443,65 +2452,17 @@ VARCACHE_PREF(
 VARCACHE_PREF(
   Live,
   "general.smoothScroll.msdPhysics.regularSpringConstant",
   SmoothScrollMSDPhysicsRegularSpringConstant,
   RelaxedAtomicInt32, 1000
 )
 
 //---------------------------------------------------------------------------
-// Prefs starting with "gl." (OpenGL)
-//---------------------------------------------------------------------------
-
-VARCACHE_PREF(
-  Live,
-  "gl.allow-high-power",
-  GLAllowHighPower,
-  RelaxedAtomicBool, true
-)
-
-VARCACHE_PREF(
-  Live,
-  "gl.ignore-dx-interop2-blacklist",
-  IgnoreDXInterop2Blacklist,
-  RelaxedAtomicBool, false
-)
-
-VARCACHE_PREF(
-  Live,
-  "gl.msaa-level",
-  MSAALevel,
-  RelaxedAtomicUint32, 2
-)
-
-#if defined(XP_MACOSX)
-VARCACHE_PREF(
-  Live,
-  "gl.multithreaded",
-  GLMultithreaded,
-  RelaxedAtomicBool, false
-)
-
-#endif
-VARCACHE_PREF(
-  Live,
-  "gl.require-hardware",
-  RequireHardwareGL,
-  RelaxedAtomicBool, false
-)
-
-VARCACHE_PREF(
-  Live,
-  "gl.use-tls-is-current",
-  UseTLSIsCurrent,
-  RelaxedAtomicInt32, 0
-)
-
-//---------------------------------------------------------------------------
-// Prefs starting with "Graphics."
+// Prefs starting with "gfx."
 //---------------------------------------------------------------------------
 
 VARCACHE_PREF(
   Once,
   "gfx.allow-texture-direct-mapping",
   AllowTextureDirectMapping,
   bool, true
 )
@@ -3053,17 +3014,65 @@ VARCACHE_PREF(
 VARCACHE_PREF(
   Live,
   "gfx.ycbcr.accurate-conversion",
   YCbCrAccurateConversion,
   RelaxedAtomicBool, false
 )
 
 //---------------------------------------------------------------------------
-// HTML5 parser prefs
+// Prefs starting with "gl." (OpenGL)
+//---------------------------------------------------------------------------
+
+VARCACHE_PREF(
+  Live,
+  "gl.allow-high-power",
+  GLAllowHighPower,
+  RelaxedAtomicBool, true
+)
+
+VARCACHE_PREF(
+  Live,
+  "gl.ignore-dx-interop2-blacklist",
+  IgnoreDXInterop2Blacklist,
+  RelaxedAtomicBool, false
+)
+
+VARCACHE_PREF(
+  Live,
+  "gl.msaa-level",
+  MSAALevel,
+  RelaxedAtomicUint32, 2
+)
+
+#if defined(XP_MACOSX)
+VARCACHE_PREF(
+  Live,
+  "gl.multithreaded",
+  GLMultithreaded,
+  RelaxedAtomicBool, false
+)
+#endif
+
+VARCACHE_PREF(
+  Live,
+  "gl.require-hardware",
+  RequireHardwareGL,
+  RelaxedAtomicBool, false
+)
+
+VARCACHE_PREF(
+  Live,
+  "gl.use-tls-is-current",
+  UseTLSIsCurrent,
+  RelaxedAtomicInt32, 0
+)
+
+//---------------------------------------------------------------------------
+// Prefs starting with "html5."
 //---------------------------------------------------------------------------
 
 // Toggle which thread the HTML5 parser uses for stream parsing.
 VARCACHE_PREF(
   Live,
   "html5.offmainthread",
   html5_offmainthread,
   bool, true
@@ -3084,17 +3093,17 @@ VARCACHE_PREF(
 VARCACHE_PREF(
   Live,
   "html5.flushtimer.subsequentdelay",
   html5_flushtimer_subsequentdelay,
   RelaxedAtomicInt32, 16
 )
 
 //---------------------------------------------------------------------------
-// Prefs starting with "Image."
+// Prefs starting with "image."
 //---------------------------------------------------------------------------
 
 VARCACHE_PREF(
   Live,
   "image.animated.decode-on-demand.threshold-kb",
   ImageAnimatedDecodeOnDemandThresholdKB,
   RelaxedAtomicUint32, 20480
 )
@@ -3270,17 +3279,17 @@ VARCACHE_PREF(
 VARCACHE_PREF(
   Live,
   "image.webp.enabled",
   ImageWebPEnabled,
   RelaxedAtomicBool, false
 )
 
 //---------------------------------------------------------------------------
-// Prefs starting with "JavaScript."
+// Prefs starting with "javascript."
 //---------------------------------------------------------------------------
 
 // BigInt API
 VARCACHE_PREF(
   Live,
   "javascript.options.bigint",
   javascript_options_bigint,
   RelaxedAtomicBool, true
@@ -3360,17 +3369,17 @@ VARCACHE_PREF(
 VARCACHE_PREF(
   Live,
   "javascript.options.streams",
   javascript_options_streams,
   RelaxedAtomicBool, false
 )
 
 //---------------------------------------------------------------------------
-// Graphic Layers prefs
+// Prefs starting with "layers."
 //---------------------------------------------------------------------------
 
 VARCACHE_PREF(
   Once,
   "layers.acceleration.disabled",
   LayersAccelerationDisabledDoNotUseDirectly,
   bool, false
 )
@@ -3844,19 +3853,20 @@ VARCACHE_PREF(
 
 VARCACHE_PREF(
   Live,
   "layers.single-tile.enabled",
   LayersSingleTileEnabled,
   RelaxedAtomicBool, true
 )
 
-// We allow for configurable and rectangular tile size to avoid wasting memory on devices whose
-// screen size does not align nicely to the default tile size. Although layers can be any size,
-// they are often the same size as the screen, especially for width.
+// We allow for configurable and rectangular tile size to avoid wasting memory
+// on devices whose screen size does not align nicely to the default tile size.
+// Although layers can be any size, they are often the same size as the screen,
+// especially for width.
 VARCACHE_PREF(
   Once,
   "layers.tile-width",
   LayersTileWidth,
   int32_t, 256
 )
 
 VARCACHE_PREF(
@@ -3946,17 +3956,17 @@ VARCACHE_PREF(
 VARCACHE_PREF(
   Once,
   "layers.use-image-offscreen-surfaces",
   UseImageOffscreenSurfaces,
   bool, true
 )
 
 //---------------------------------------------------------------------------
-// Prefs starting with "Layout."
+// Prefs starting with "layout."
 //---------------------------------------------------------------------------
 
 // Debug-only pref to force enable the AccessibleCaret. If you want to
 // control AccessibleCaret by mouse, you'll need to set
 // "layout.accessiblecaret.hide_carets_for_mouse_input" to false.
 VARCACHE_PREF(
   Live,
   "layout.accessiblecaret.enabled",
@@ -4700,18 +4710,18 @@ VARCACHE_PREF(
 // File-backed MediaCache size.
 VARCACHE_PREF(
   Live,
   "media.cache_size",
   MediaCacheSize,
   RelaxedAtomicUint32, 512000 // Measured in KiB
 )
 
-// Size of file backed MediaCache while on a connection which is cellular (3G, etc),
-// and thus assumed to be "expensive".
+// Size of file backed MediaCache while on a connection which is cellular (3G,
+// etc), and thus assumed to be "expensive".
 VARCACHE_PREF(
   Live,
   "media.cache_size.cellular",
   MediaCacheCellularSize,
   RelaxedAtomicUint32, 32768 // Measured in KiB
 )
 
 // If a resource is known to be smaller than this size (in kilobytes), a
@@ -6216,16 +6226,27 @@ VARCACHE_PREF(
 VARCACHE_PREF(
   Live,
   "test.mousescroll",
   MouseScrollTestingEnabled,
   RelaxedAtomicBool, false
 )
 
 //---------------------------------------------------------------------------
+// Prefs starting with "thread."
+//---------------------------------------------------------------------------
+
+VARCACHE_PREF(
+  Live,
+  "threads.medium_high_event_queue.enabled",
+  threads_medium_high_event_queue_enabled,
+  RelaxedAtomicBool, true
+)
+
+//---------------------------------------------------------------------------
 // Prefs starting with "toolkit."
 //---------------------------------------------------------------------------
 
 VARCACHE_PREF(
   Live,
   "toolkit.scrollbox.horizontalScrollDistance",
   ToolkitHorizontalScrollDistance,
   RelaxedAtomicInt32, 5
@@ -6234,27 +6255,16 @@ VARCACHE_PREF(
 VARCACHE_PREF(
   Live,
   "toolkit.scrollbox.verticalScrollDistance",
   ToolkitVerticalScrollDistance,
   RelaxedAtomicInt32, 3
 )
 
 //---------------------------------------------------------------------------
-// Prefs starting with "thread."
-//---------------------------------------------------------------------------
-
-VARCACHE_PREF(
-  Live,
-  "threads.medium_high_event_queue.enabled",
-  threads_medium_high_event_queue_enabled,
-  RelaxedAtomicBool, true
-)
-
-//---------------------------------------------------------------------------
 // Prefs starting with "ui."
 //---------------------------------------------------------------------------
 
 // Prevent system colors from being exposed to CSS or canvas.
 VARCACHE_PREF(
   Live,
   "ui.use_standins_for_native_colors",
   ui_use_standins_for_native_colors,
@@ -6272,17 +6282,17 @@ VARCACHE_PREF(
 VARCACHE_PREF(
   Live,
   "ui.click_hold_context_menus.delay",
   UiClickHoldContextMenusDelay,
   RelaxedAtomicInt32, 500
 )
 
 //---------------------------------------------------------------------------
-// View source prefs
+// Prefs starting with "view_source."
 //---------------------------------------------------------------------------
 
 VARCACHE_PREF(
   Live,
   "view_source.editor.external",
   view_source_editor_external,
   bool, false
 )