Renamed module from soon to timers.

yui · Jan 4, 2013 · da43756 · da43756
1 parent 72d6d67
commit da43756
Show file tree

Hide file tree

Showing 9 changed files with 106 additions and 10 deletions.
diff --git a/src/soon/HISTORY.md → src/timers/HISTORY.md b/src/soon/HISTORY.md → src/timers/HISTORY.md
@@ -1,3 +1,3 @@
-soon
+timers
 ========
 * Initial release.
diff --git a/src/soon/README.md → src/timers/README.md b/src/soon/README.md → src/timers/README.md
@@ -1,4 +1,4 @@
-soon
+timers
 ========
 Similar to `Y.later`, but sooner.  `Y.soon` standardizes the way to make
 something happen asynchronously but without a timed delay.  Under the covers,

diff --git a/src/soon/build.json → src/timers/build.json b/src/soon/build.json → src/timers/build.json
@@ -1,10 +1,10 @@
 {
     "builds": {
-        "soon": {
+        "timers": {
             "jsfiles": [
-                "js/soon.js"
+                "js/timers.js"
             ]
         }
     },
-    "name": "soon"
+    "name": "timers"
 }
diff --git a/src/soon/js/soon.js → src/timers/js/soon.js b/src/soon/js/soon.js → src/timers/js/soon.js
diff --git a/src/timers/js/timers.js b/src/timers/js/timers.js
@@ -0,0 +1,89 @@
+/**
+ * Provides utilities for timed asynchronous callback execution.
+ * Y.soon is a setImmediate/process.nextTick/setTimeout wrapper.
+ * @module timers
+ * @author Steven Olmsted
+ */
+
+var global = Y.config.global,
+
+    /**
+     * Y.soon accepts a callback function.  The callback function will be called
+     * once in a future turn of the JavaScript event loop.  If the function
+     * requires a specific execution context or arguments, wrap it with Y.bind.
+     * Y.soon returns an object with a cancel method.  If the cancel method is
+     * called before the callback function, the callback function won't be
+     * called.
+     * @method soon
+     * @for YUI
+     * @param {Function} callbackFunction
+     * @return {Object} An object with a cancel method.  If the cancel method is
+     * called before the callback function, the callback function won't be
+     * called.
+    */
+    soon = function (callbackFunction) {
+        var canceled;
+
+        soon._asynchronizer(function () {
+            // Some asynchronizers may provide their own cancellation
+            // methods such as clearImmediate or clearTimeout but some
+            // asynchronizers do not.  For simplicity, cancellation is
+            // entirely handled here rather than wrapping the other methods.
+            // All asynchronizers are expected to always call this anonymous
+            // function.
+            if (!canceled) {
+                callbackFunction();
+            }
+        });
+
+        return {
+            cancel: function () {
+                canceled = 1;
+            }
+        };
+    };
+
+/**
+ * The asynchronizer is the internal mechanism which will call a function
+ * asynchronously.  This property is exposed as a convenient way to define a
+ * different asynchronizer implementation without having to rewrite the
+ * entire Y.soon interface.
+ * @method _asynchronizer
+ * @for soon
+ * @param {Function} callbackFunction The function to call asynchronously.
+ * @protected
+ */
+
+/**
+ * Since Y.soon is likely to have many differing asynchronizer
+ * implementations, this property should be set to identify which
+ * implementation is in use.
+ * @property _impl
+ * @protected
+ * @type String
+ */
+
+// Check for a native or already polyfilled implementation of setImmediate.
+if ('setImmediate' in global) {
+    soon._asynchronizer = function (callbackFunction) {
+        setImmediate(callbackFunction);
+    };
+    soon._impl = 'setImmediate';
+}
+
+// Check for process and process.nextTick
+else if (('process' in global) && ('nextTick' in process)) {
+    soon._asynchronizer = process.nextTick;
+    soon._impl = 'nextTick';
+}
+
+// The most widely supported asynchronizer is setTimeout so we use that as
+// the fallback.
+else {
+    soon._asynchronizer = function (callbackFunction) {
+        setTimeout(callbackFunction, 0);
+    };
+    soon._impl = 'setTimeout';
+}
+
+Y.soon = soon;
diff --git a/src/soon/meta/soon.json → src/timers/meta/soon.json b/src/soon/meta/soon.json → src/timers/meta/soon.json
diff --git a/src/timers/meta/timers.json b/src/timers/meta/timers.json
@@ -0,0 +1,7 @@
+{
+    "timers": {
+        "requires": [
+            "yui-base"
+        ]
+    }
+}
diff --git a/src/soon/tests/unit/index.html → src/timers/tests/unit/index.html b/src/soon/tests/unit/index.html → src/timers/tests/unit/index.html
@@ -3,7 +3,7 @@
     <head>
         <meta charset="utf-8" />
         <title>
-            soon
+            timers
         </title>
         <script src="/build/yui/yui.js">
         </script>
@@ -16,12 +16,12 @@
         <script>
             YUI({
                 coverage: [
-                    'soon'
+                    'timers'
                 ],
                 filter: (window.location.search.match(/[?&]filter=([^&]+)/) || [])[1] || 'raw'
             }).use('test-console', 'test', 'module-tests', function (Y) {
                 (new Y.Test.Console()).render('#logger');
-                Y.Test.Runner.setName('soon');
+                Y.Test.Runner.setName('timers');
                 Y.Test.Runner.run();
             });
         </script>

diff --git a/src/soon/tests/unit/js/tests.js → src/timers/tests/unit/js/tests.js b/src/soon/tests/unit/js/tests.js → src/timers/tests/unit/js/tests.js
@@ -54,7 +54,7 @@ YUI.add('module-tests', function (Y) {
     Y.Test.Runner.add(suite);
 }, '', {
     requires: [
-        'soon',
-        'test'
+        'test',
+        'timers'
     ]
 });