From 611a0c8452f51398daa722c5cb6781482c9550ec Mon Sep 17 00:00:00 2001 From: Timo Tijhof Date: Tue, 20 Dec 2016 21:13:48 -0800 Subject: [PATCH] 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 --- .../mediawiki.requestIdleCallback.js | 29 +++++++++++++++---- 1 file changed, 24 insertions(+), 5 deletions(-) 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; /* -- 2.20.1