Background Actions

The framework supports background actions as well as foreground actions, which are the default. Each background action is sent in its own request and is executed in the order that it’s received. This is different from foreground actions. Multiple queued foreground actions are batched in a single request to minimize network traffic.

When the server-side actions in the queue are executed, the foreground actions are executed first and then the background actions are executed. Background actions run in parallel with foreground actions and may come back in either order.

The framework throttles foreground and background actions separately. This means that the number of long-running background server-side actions running at a time can be controlled. Throttling is done automatically, it is not user controlled, and the number of background actions allowed is three. Even with separate throttling, background actions might affect performance in some conditions, such as if the browser is doing many fetches from servers.

To set an action as a background action, call the setBackground() method on the action object in JavaScript. This example shows how foreground and background actions are executed.

Here is the source for the client-side controller.

1swfobject.registerObject("clippy.codeblock-0", "9");/** Client-Side Controller **/
2({
3    doForeground: function(cmp, event, helper) {
4        helper.echo(cmp, 'Foreground #1');
5        helper.echo(cmp, 'Foreground #2');
6    },
7    doBackground: function(cmp, event, helper) {
8        helper.echo(cmp, 'Background #1', function(action) {
9            action.setBackground();
10        });
11        helper.echo(cmp, 'Background #2', function(action) {
12            action.setBackground();
13        });
14        helper.echo(cmp, 'Background #3', function(action) {
15            action.setBackground();
16        });
17        helper.echo(cmp, 'Background #4', function(action) {
18            action.setBackground();
19        });
20    }
21})    
22   ’

The client-side controller references a helper. Here is the source for the helper.

1swfobject.registerObject("clippy.codeblock-1", "9");/** Helper **/
2({
3    echo: function(cmp, message, callback) {
4        var action = cmp.get("c.echo");
5        action.setParams({
6            message: message
7        });
8
9        action.setCallback(this, function(response) {
10            var state = response.getState();
11            var text = response.getReturnValue();
12            var echoes = cmp.get('v.echoes');
13            echoes.push({
14                text: text,
15                state: state
16            });
17            cmp.set('v.echoes', echoes)
18        });
19
20        if ($A.util.isFunction(callback)) {
21            callback(action);
22        }
23
24        $A.enqueueAction(action);
25    }
26}))

The echo function in the helper calls the echo method in the server-side controller. Here is the source for the server-side controller.

The echo method sleeps for one second and echoes back the message that was passed in.

Note that doForeground in the client-side controller calls the echo function twice, while doBackground calls echo four times. Since each background action is sent in its own request, doForeground will take twice as long to return as one of the background actions in doBackground.

When the doForeground and doBackground controller actions are triggered in that order, the echoes are printed like this.

• Background #3: SUCCESS
• Background #2: SUCCESS
• Background #1: SUCCESS
• Foreground #1: SUCCESS
• Foreground #2: SUCCESS
• Background #4: SUCCESS

Foreground actions run in the order they are queued. Background actions run three at a time, so the first three actions must return before the fourth one is executed.

When the doBackground and doForeground controller actions are triggered in that order, the echoes are printed like this.

Since all enqueued actions are run at the end of the event loop, the trigger order of the foreground and background actions shouldn’t matter.In this second example, the first three background actions are guaranteed to complete before the foreground actions. The fourth background action completes in a race condition with the foreground actions. There is no guarantee which action will return first.

To mark a server-side action as a background action in Java, use the @BackgroundAction annotation at the method level on the controller.