X-Git-Url: https://git.cyclocoop.org/?a=blobdiff_plain;f=resources%2Fsrc%2Fmediawiki%2Fmediawiki.requestIdleCallback.js;h=6a6aa155cee0cabc7a48e95d799b8cdc69e9528c;hb=3287201b673c6e52c04e9f8771c0e71d1a617910;hp=b58cb69eb27efe8e1f21d844a115e4ff6362bac3;hpb=61898ad28ed69c5b391eb43e0db9386279b9612c;p=lhc%2Fweb%2Fwiklou.git

diff --git a/resources/src/mediawiki/mediawiki.requestIdleCallback.js b/resources/src/mediawiki/mediawiki.requestIdleCallback.js
index b58cb69eb2..6a6aa155ce 100644
--- a/resources/src/mediawiki/mediawiki.requestIdleCallback.js
+++ b/resources/src/mediawiki/mediawiki.requestIdleCallback.js
@@ -1,8 +1,3 @@
-/*!
- * An interface for scheduling background tasks.
- *
- * Loosely based on https://w3c.github.io/requestidlecallback/
- */
 ( function ( mw ) {
 	var maxBusy = 50;
 
@@ -21,15 +16,38 @@
 	/**
 	 * Schedule a deferred task to run in the background.
 	 *
+	 * This allows code to perform tasks in the main thread without impacting
+	 * time-critical operations such as animations and response to input events.
+	 *
+	 * Basic logic is as follows:
+	 *
+	 * - User input event should be acknowledged within 100ms per [RAIL].
+	 * - Idle work should be grouped in blocks of upto 50ms so that enough time
+	 *   remains for the event handler to execute and any rendering to take place.
+	 * - Whenever a native event happens (e.g. user input), the deadline for any
+	 *   running idle callback drops to 0.
+	 * - As long as the deadline is non-zero, other callbacks pending may be
+	 *   executed in the same idle period.
+	 *
+	 * See also:
+	 *
+	 * - <https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback>
+	 * - <https://w3c.github.io/requestidlecallback/>
+	 * - <https://developers.google.com/web/updates/2015/08/using-requestidlecallback>
+	 * [RAIL]: https://developers.google.com/web/fundamentals/performance/rail
+	 *
 	 * @member mw
 	 * @param {Function} callback
+	 * @param {Object} [options]
+	 * @param {number} [options.timeout] If set, the callback will be scheduled for
+	 *  immediate execution after this amount of time (in milliseconds) if it didn't run
+	 *  by that time.
 	 */
-	mw.requestIdleCallback = mw.requestIdleCallbackInternal;
-	/*
-	// XXX: Polyfill disabled due to https://bugs.chromium.org/p/chromium/issues/detail?id=647870
-	mw.requestIdleCallback = window.requestIdleCallback
+	mw.requestIdleCallback = window.requestIdleCallback ?
 		// Bind because it throws TypeError if context is not window
-		? window.requestIdleCallback.bind( window )
-		: mw.requestIdleCallbackInternal;
-	*/
+		window.requestIdleCallback.bind( window ) :
+		mw.requestIdleCallbackInternal;
+	// Note: Polyfill was previously disabled due to
+	// https://bugs.chromium.org/p/chromium/issues/detail?id=647870
+	// See also <http://codepen.io/Krinkle/full/XNGEvv>
 }( mediaWiki ) );