## Overview

This module provides APIs to schedule a Ballerina job either once or periodically and to manage the execution of those jobs.

### Jobs and scheduling

Every scheduling job in Ballerina needs to be represented by a `Job` object. Therefore, a `job` class with your custom logic needs to be created to execute it when the task is triggered.

The `task` package has the following two scheduling systems to schedule the job:

- One-time job execution
- Frequency-based job execution 

#### One-time job execution

This API provides the functionality to schedule a job at a specified time.

The following code snippet shows how to schedule a one-time job.

```ballerina
class Job {

    *task:Job;
    string msg;

    public function execute() {
        io:println(self.msg);
    }

    isolated function init(string msg) {
        self.msg = msg;
    }
}

time:ZoneOffset zoneOffset = {
    hours: 5,
    minutes: 30,
    seconds: <decimal>0.0
};
time:Civil time = {
    year: 2021,
    month: 4,
    day: 13,
    hour: 4,
    minute: 50,
    second: 50.52,
    timeAbbrev: "Asia/Colombo",
    utcOffset: zoneOffset
};

task:JobId result = check task:scheduleOneTimeJob(new Job("Hi"), time);
```

##### Frequency-based job execution

This API provides the functionality to schedule jobs on a specific interval either once or periodically by configuring the configuration such as start time, end time, and maximum count.

The following code snippet shows how to schedule a recurring job by using this API.

```ballerina
class Job {

    *task:Job;
    string msg;

    public function execute() {
        io:println(self.msg);
    }

    isolated function init(string msg) {
        self.msg = msg;
    }
}

time:ZoneOffset zoneOffset = {
    hours: 5,
    minutes: 30
};
time:Civil time = {
    year: 2021,
    month: 3,
    day: 31,
    hour: 4,
    minute: 50,
    second: 50.52,
    timeAbbrev: "Asia/Colombo",
    utcOffset: zoneOffset
};

task:JobId result = check task:scheduleJobRecurByFrequency(new Job("Hi"), 2.5, maxCount = 10, startTime = time);
```

For information on the operations, which you can perform with the task module, see the below **Functions**.


LOG_AND_TERMINATE

LOG_AND_CONTINUE

TERMINATE

CONTINUE

ErrorPolicy

Possible options for the `WaitingPolicy`.


WAIT

IGNORE

LOG_AND_IGNORE

WaitingPolicy

Represents the error type of the `ballerina/task` module. This error type represents any error that can occur during
the execution of the task APIs.


Error

Configure the scheduler worker pool.
```ballerina
check task:configureWorkerPool(4, 7);
```



configureWorkerPool

Specifies the number of workers that are available for the concurrent execution of jobs.
It should be a positive integer. The recommendation is to set a value less than 10. Default sets to 5.


workerCount

The number of seconds as a decimal the scheduler will tolerate a trigger to pass its next-fire-time
before being considered as `ignored the trigger`


waitingTime

Seconds

A `task:Error` if the process failed due to any reason or else ()


Gets all the running jobs.
```ballerina
task:JobId[] result = task:getRunningJobs();
```



getRunningJobs

Returns the IDs of all the running jobs as an array


JobId

Gets time in milliseconds of the given `time:Civil`.



getTimeInMillies

time

Civil

Time in milliseconds or else `task:Error` if the process failed due to any reason


Pauses all the jobs.
```ballerina
check task:pauseAllJobs();
```



pauseAllJobs

A `task:Error` if an error occurred while pausing or else ()


Pauses the particular job.
```ballerina
check task:pauseJob(jobId);
```



pauseJob

The ID of the job as a `task:JobId`, which needs to be paused


jobId

A `task:Error` if an error occurred while pausing a job or else ()


Resumes all the jobs.
```ballerina
check task:resumeAllJobs();
```



resumeAllJobs

A `task:Error` when an error occurred while resuming or else ()


Resumes the particular job.
```ballerina
check task:resumeJob(jobId);
```



resumeJob

The ID of the job as a `task:JobId`, which needs to be resumed


A `task:Error` when an error occurred while resuming a job or else ()


Schedule the recurring `task:Job` according to the given duration. Once scheduled, it will return the job ID, which
can be used to manage the job.
```ballerina
task:JobId jobId = check task:scheduleJobRecurByFrequency(new Job(), 3);
```



scheduleJobRecurByFrequency

Ballerina job, which is to be executed by the scheduler


The duration of the trigger (in seconds), which is used to run the job frequently


interval

decimal

maxCount

The trigger start time in Ballerina `time:Civil`. If it is not provided, a trigger will
start immediately


startTime

The trigger end time in Ballerina `time:Civil`


endTime

The policy, which is used to handle the error and will be waiting during the trigger time


taskPolicy

TaskPolicy

A `task:JobId` or else a `task:Error` if the process failed due to any reason


Schedule the given `task:Job` for the given time. Once scheduled, it will return a job ID, which can be used to manage
the job.
```ballerina
time:Utc newTime = time:utcAddSeconds(time:utcNow(), 3);
time:Civil time = time:utcToCivil(newTime);
task:JobId jobId = check task:scheduleOneTimeJob(new Job(), time);
```



scheduleOneTimeJob

Ballerina job, which is to be executed during the trigger


The specific time in Ballerina `time:Civil` to trigger only one time


triggerTime

Unschedule the `task:Job`, which is associated with the given job ID. If no job is running in the scheduler,
the scheduler will be shut down automatically.
```ballerina
check task:unscheduleJob(jobId);
```



unscheduleJob

The ID of the job as a `task:JobId`, which needs to be unscheduled


The Ballerina Job object provides the abstraction for a job instance, which schedules to execute periodically.


Executes by the Scheduler when the scheduled trigger fires.


execute

A read-only record consisting of a unique identifier for a created job.


The policy to follow when there is an error in Job execution


errorPolicy

The policy to follow when the next task is triggering while the previous job is still
being processing


waitingPolicy

This module provides APIs to schedule a Ballerina job either once or periodically and to manage the execution of those jobs.


Object type: Job

Methods

execute