transient-task-dev-guide.md

Transient Task Development

When to Use

By default, an application can run for 6 to 12 seconds after it switches to the background but before being suspended. If an application requires more time to execute an important task, it can call the requestSuspendDelay API to delay the suspension.

It is recommended that an application calls the requestSuspendDelay API before executing any time-consuming task, rather than when it is already running in the background. The calling of the requestSuspendDelay API when the application is running in the foreground does not affect the transient task quota of the application.

Each application has a daily time quota for transient tasks. Therefore, after the time-consuming task finishes execution, the application should cancel the transient task in a timely manner.

Typical time-consuming tasks include saving status data to the local database, opening and processing a large file, and synchronizing data to the cloud server.

Available APIs

Table 1 Main APIs for transient tasks

API	Description
requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo	Requests delayed suspension after the application switches to the background. The default duration value of delayed suspension is 3 minutes when the battery level is normal and 1 minute when the battery level is low.
getRemainingDelayTime(requestId: number): Promise<number>	Obtains the remaining duration before the application is suspended. This API uses a promise to return the result.
cancelSuspendDelay(requestId: number): void	Cancels the suspension delay.

How to Develop

1. When an application needs to execute a time-consuming task, call the API to request a transient task. After the time-consuming task finishes execution, call the API to cancel the transient task.

import backgroundTaskManager from '@ohos.backgroundTaskManager';

let delayInfo;
let id;

// Request a suspension delay.
function requestSuspendDelay() {
    let myReason = 'test requestSuspendDelay';
    delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
        console.info("Request suspension delay will time out.");
        // The callback in invoked to notify the application that the suspension delay request is about to time out. The application needs to perform some cleanup and annotation operations.
    });

    id = delayInfo.requestId;
    console.info("requestId is: " + id);
}

// Obtain the remaining duration before the application is suspended.
function getRemainingDelayTime() {
    let delayTime = 0;
    backgroundTaskManager.getRemainingDelayTime(id).then((res) => {
        console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
        delayTime = res;
    }).catch((err) => {
        console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code);
    });
    return delayTime;
}

// Cancel the suspension delay.
function cancelSuspendDelay() {
    backgroundTaskManager.cancelSuspendDelay(id);
}

function performingLongRunningTask() {
    // Before executing the time-consuming task, call the API to request a transient task to delay the suspension.
    requestSuspendDelay();

    // Obtain the available time quota through the getRemainingDelayTime() API.
    let delayTime = getRemainingDelayTime();

    if (delayTime < 0) {// If the time is less than a certain value, cancel the time-consuming operation.
        // Handle the scenario where the time quota is insufficient.

        cancelSuspendDelay();
        return;
    }

    // Execute the time-consuming task.

    // After the time-consuming task is executed, call the API to cancel the transient task.
    cancelSuspendDelay();
}