From: Timo Tijhof Date: Wed, 21 Dec 2016 05:13:48 +0000 (-0800) Subject: mediawiki.requestIdleCallback: Improve documentation X-Git-Tag: 1.31.0-rc.0~4428^2 X-Git-Url: https://git.cyclocoop.org/%28%28?a=commitdiff_plain;h=611a0c8452f51398daa722c5cb6781482c9550ec;p=lhc%2Fweb%2Fwiklou.git mediawiki.requestIdleCallback: Improve documentation * Explain basic logic. * Document the 'options.timeout' parameter of the native interface. The fallback shim ignores this parameter because it always executes callbacks using setTimeout(,1), which is before any timeout would expire. The native requestIdleCallback is smarter about scheduling callbacks at moments in time when no other priority things happen, at which point the timeout helps inform how long to wait at most for an idle period to naturally occur. Change-Id: I45126b875547f64ec8b450a264b250260c41084c --- diff --git a/resources/src/mediawiki/mediawiki.requestIdleCallback.js b/resources/src/mediawiki/mediawiki.requestIdleCallback.js index b58cb69eb2..d414232010 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,8 +16,32 @@ /** * 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: + * + * - + * - + * - + * [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; /*