Ember.run Namespace

Runs the passed target and method inside of a RunLoop, ensuring any deferred actions including bindings and views updates are flushed at the end.

Normally you should not need to invoke this method yourself. However if you are implementing raw event handlers when interfacing with other libraries or plugins, you should probably wrap all of your code inside this call.

Returns:

Allows you to specify which context to call the specified function in while adding the execution of that function to the Ember run loop. This ability makes this method a great way to asynchronously integrate third-party libraries into your Ember application.

run.bind takes two main arguments, the desired context and the function to invoke in that context. Any additional arguments will be supplied as arguments to the function that is passed in.

Let's use the creation of a TinyMCE component as an example. Currently, TinyMCE provides a setup configuration option we can use to do some processing after the TinyMCE instance is initialized but before it is actually rendered. We can use that setup option to do some additional setup for our component. The component itself could look something like the following:

In this example, we use Ember.run.bind to bind the setupEditor method to the context of the App.RichTextEditorComponent and to have the invocation of that method be safely handled and executed by the Ember run loop.

Parameters:

target[Object]

target of method to call

methodFunction|String

Method to invoke. May be a function or a string. If you pass a string then it will be looked up on the passed target.

Returns:

debounce (target, method, args*, wait, immediate) Arraypublic

Delay calling the target method until the debounce period has elapsed with no additional debounce calls. If debounce is called again before the specified time has elapsed, the timer is reset and the entire period must pass again before the target method is called.

This method should be used when an event may be called multiple times but the action should only be called once when the event is done firing. A common example is for scroll events where you only want updates to happen once scrolling has ceased.

Immediate allows you to run the function immediately, but debounce other calls for this function until the wait time has elapsed. If debounce is called again before the specified time has elapsed, the timer is reset and the entire period must pass again before the method can be called again.

later (target, method, args*, wait) *public

Invokes the passed target/method and optional arguments after a specified period of time. The last parameter of this method must always be a number of milliseconds.

You should use this method whenever you need to run some action after a period of time instead of using setTimeout(). This method will ensure that items that expire during the same script execution cycle all execute together, which is often more efficient than using a real setTimeout.

run.later(myContext, function() {
// code here will execute within a RunLoop in about 500ms with this == myContext
}, 500);

Parameters:

target[Object]

target of method to invoke

methodFunction|String

The method to invoke. If you pass a string it will be resolved on the target at the time the method is invoked.

Returns:

next (target, method, args*) Objectpublic

Schedules an item to run from within a separate run loop, after control has been returned to the system. This is equivalent to calling run.later with a wait time of 1ms.

run.next(myContext, function() {
// code to be executed in the next run loop,
// which will be scheduled after the current one
});

Multiple operations scheduled with run.next will coalesce into the same later run loop, along with any other operations scheduled by run.later that expire right around the same time that run.next operations will fire.

Note that there are often alternatives to using run.next. For instance, if you'd like to schedule an operation to happen after all DOM element operations have completed within the current run loop, you can make use of the afterRender run loop queue (added by the ember-views package, along with the preceding render queue where all the DOM element operations happen).

One benefit of the above approach compared to using run.next is that you will be able to perform DOM/CSS operations before unprocessed elements are rendered to the screen, which may prevent flickering or other artifacts caused by delaying processing until after rendering.

The other major benefit to the above approach is that run.next introduces an element of non-determinism, which can make things much harder to test, due to its reliance on setTimeout; it's much harder to guarantee the order of scheduled operations when they are scheduled outside of the current run loop, i.e. with run.next.

Parameters:

target[Object]

target of method to invoke

methodFunction|String

The method to invoke. If you pass a string it will be resolved on the target at the time the method is invoked.

Returns:

schedule (queue, target, method, arguments*) *public

Adds the passed target/method and any optional arguments to the named queue to be executed at the end of the RunLoop. If you have not already started a RunLoop when calling this method one will be started for you automatically.

At the end of a RunLoop, any methods scheduled in this way will be invoked. Methods will be invoked in an order matching the named queues defined in the run.queues property.

run.schedule('sync', this, function() {
// this will be executed in the first RunLoop queue, when bindings are synced
console.log('scheduled on sync queue');
});
run.schedule('actions', this, function() {
// this will be executed in the 'actions' queue, after bindings have synced.
console.log('scheduled on actions queue');
});
// Note the functions will be run in order based on the run queues order.
// Output would be:
// scheduled on sync queue
// scheduled on actions queue

Returns:

syncVoidprivate

Immediately flushes any events scheduled in the 'sync' queue. Bindings use this queue so this method is a useful way to immediately force all bindings in the application to sync.

You should call this method anytime you need any changed state to propagate throughout the app immediately without repainting the UI (which happens in the later 'render' queue added by the ember-views package).

Returns:

queuesArrayprivate

Array of named queues. This array determines the order in which queues are flushed at the end of the RunLoop. You can define your own queues by simply adding the queue name to this array. Normally you should not need to inspect or modify this property.