task

Functions for execution of asynchronous tasks.

Example
var taskLib = require('/lib/xp/task');

Methods

(static) get(taskId) → {TaskInfo}

Returns the current state and progress details for the specified task.

Parameters:
Name Type Description
taskId string

Id of the task.
Returns:

Detail information for the task. Or null if the task could not be found.

Type
TaskInfo
Examples
// Obtains details for an active task
var taskInfo = taskLib.get('7ca603c1-3b88-4009-8f30-46ddbcc4bb19');

if (taskInfo) {
    log.info('Current task state = %s', taskInfo.state);
} else {
    log.info('Task not found');
}
// Task information returned
var expected = {
    "description": "Long running task",
    "id": "7ca603c1-3b88-4009-8f30-46ddbcc4bb19",
    "state": "RUNNING",
    "progress": {
        "info": "Processing item 33",
        "current": 33,
        "total": 42
    }
};

(static) list() → {Array.<TaskInfo>}

Returns the list of active tasks with their current state and progress details.

Returns:

List with task information for every task.

Type
Array.<TaskInfo>
Examples
// Obtains list of active tasks
var tasks = taskLib.list();
// Tasks returned
var expected = [
    {
        "description": "Long running task",
        "id": "7ca603c1-3b88-4009-8f30-46ddbcc4bb19",
        "state": "RUNNING",
        "progress": {
            "info": "Processing item 33",
            "current": 33,
            "total": 42
        }
    },
    {
        "description": "Update statistics",
        "id": "b6173bcb-bf54-409b-aa6b-96ae6fcec263",
        "state": "FINISHED",
        "progress": {
            "info": "Work completed",
            "current": 0,
            "total": 0
        }
    },
    {
        "description": "Import remote data",
        "id": "e1f57280-d672-4cd8-b674-98e26e5b69ae",
        "state": "FAILED",
        "progress": {
            "info": "Fetching data",
            "current": 33,
            "total": 100
        }
    }
];

(static) progress(params)

Reports progress information from an executing task. This function may only be called within the context of a task function, otherwise it will fail and throw an exception.

Parameters:
Name Type Description
params object

JSON with progress details.

Properties
Name Type Attributes Description
current number <optional>

Integer value representing the number of items that have been processed in the task.
total number <optional>

Integer value representing the total number of items to process in the task.
info string <optional>

Text describing the current progress for the task.
Example
// Execute task and keep taskId for polling status
var taskId = taskLib.submit({
    description: 'Background task',
    task: function () {

        taskLib.progress({info: 'Initializing task'});

        for (var i = 0; i < 10; i++) {
            taskLib.progress({
                info: 'Processing item ' + (i + 1),
                current: i,
                total: 10
            });

            processItem(i);
        }

        taskLib.progress({info: 'Task completed'});
    }
});

(static) sleep(timeMillis)

Causes the current execution thread to sleep (temporarily cease execution) for the specified number of milliseconds.

Parameters:
Name Type Description
timeMillis string

The length of time to sleep in milliseconds.
Example
var retries = 3;
var result = fetchRemoteData();

while (!result && retries > 0) {
    taskLib.sleep(500); // wait half a second before retrying
    retries--;
    result = fetchRemoteData();
}

(static) submit(params) → {string}

Submits a task to be executed in the background and returns an id representing the task. This function returns immediately. The callback function will be executed asynchronously.

Parameters:
Name Type Description
params object

JSON with the parameters.

Properties
Name Type Description
description string

Text describing the task to be executed.
task function

Callback function to be executed asynchronously.
Returns:

Id of the task that will be executed.

Type
string
Example
// Execute task and keep taskId for polling status
var taskId = taskLib.submit({
    description: 'Background task',
    task: function () {
        longRunningTask();
    }
});

Type Definitions

TaskInfo

Type:
  • Object
Properties:
Name Type Description
id string

Task Id.
description string

Task description.
state string

Task state. Possible values: 'WAITING' | 'RUNNING' | 'FINISHED' | 'FAILED'
progress object

Progress information provided by the running task.

Properties
Name Type Description
current number

Latest progress current numeric value.
total number

Latest progress target numeric value.
info string

Latest progress textual information.