runtime/system/run_loop: add invokeNext that will invoke a function…

… at the beginning of the next runloop

frameworks/runtime/system/object.js

@@ -774,7 +774,7 @@ SC.Object.prototype = {
   },
 
   /**
-    Invokes the passed method once at the beginning of the next runloop,
+    Invokes the passed method once at the end of the current runloop,
     before any other methods (including events) are processed. This is useful
     for situations where you know you need to update something, but due to
     the way the run loop works, you can't actually do the update until the
@@ -793,7 +793,7 @@ SC.Object.prototype = {
             var obj = MyRecord.newRecord() ;
 
             // update the collection controller's selection
-            MyApp.myRecordCollectionController.invokeNext( function() {
+            MyApp.myRecordCollectionController.invokeLast( function() {
               this.set('selection', [obj]) ;
             });
           }
@@ -821,6 +821,54 @@ SC.Object.prototype = {
     return this;
   },
 
+  /**
+    Invokes the passed method once at the beginning of the next runloop,
+    before any other methods (including events) are processed. This is useful
+    for situations where you know you need to update something, but due to
+    the way the run loop works, you can't actually do the update until the
+    run loop has completed.
+
+    A simple example is setting the selection on a collection controller to a
+    newly created object. Because the collection controller won't have its
+    content collection updated until later in the run loop, setting the
+    selection immediately will have no effect. In this situation, you could do
+    this instead:
+
+          // Creates a new MyRecord object and sets the selection of the
+          // myRecord collection controller to the new object.
+          createObjectAction: function(sender, evt) {
+            // create a new record and add it to the store
+            var obj = MyRecord.newRecord() ;
+
+            // update the collection controller's selection
+            MyApp.myRecordCollectionController.invokeNext( function() {
+              this.set('selection', [obj]) ;
+            });
+          }
+
+    Note that in development mode only, the object and method that call this
+    method will be recorded, for help in debugging scheduled code.
+
+    @param {Function|String} method method or method name
+    @returns {SC.Object} receiver
+   */
+  invokeNext: function(method) {
+    //@if(debug)
+    // If we're logging deferred calls, send along the information that needs to
+    // be recorded.
+    var originatingTarget, originatingMethod, originatingStack;
+    if (SC.LOG_DEFERRED_CALLS) {
+      originatingTarget = this ;
+      originatingStack  = SC._getRecentStack();
+      originatingMethod = originatingStack[0];
+    }
+    SC.RunLoop.currentRunLoop.invokeNext(this, method, originatingTarget, originatingMethod, originatingStack);
+    return this;
+    //@endif
+    SC.RunLoop.currentRunLoop.invokeNext(this, method);
+    return this;
+  },
+
   /**
     The properties named in this array will be concatenated in subclasses
     instead of replaced.  This allows you to name special properties that