Standard Library

task

ballerina/task

Package Overview

This package provides the functionality to schedule a Ballerina job and manages the execution of Ballerina jobs either once or periodically.

Jobs and Scheduling

Every scheduled job in Ballerina is represented by a Job object. You need to create a jobs class with custom logic 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 date.

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

1class Job {
2
3    *task:Job;
4    string msg;
5
6    public function execute() {
7        io:println(self.msg);
8    }
9
10    isolated function init(string msg) {
11        self.msg = msg;
12    }
13}
14
15time:ZoneOffset zoneOffset = {
16    hours: 5,
17    minutes: 30,
18    seconds: <decimal>0.0
19};
20time:Civil time = {
21    year: 2021,
22    month: 4,
23    day: 13,
24    hour: 4,
25    minute: 50,
26    second: 50.52,
27    timeAbbrev: "Asia/Colombo",
28    utcOffset: zoneOffset
29};
30
31task:Error|task:JobId result = task:scheduleOneTimeJob(new Job("Hi"), time);

For an example on the usage of the scheduleOneTimeJob, see the Task One-time Job Execution Example.

Frequency-based Job Execution

This API provides the functionality to schedule jobs on a specific interval either once or periodically with an optional start time, end time, and maximum count.

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

1class Job {
2
3    *task:Job;
4    string msg;
5
6    public function execute() {
7        io:println(self.msg);
8    }
9
10    isolated function init(string msg) {
11        self.msg = msg;
12    }
13}
14
15time:ZoneOffset zoneOffset = {
16    hours: 5,
17    minutes: 30
18};
19time:Civil time = {
20    year: 2021,
21    month: 3,
22    day: 31,
23    hour: 4,
24    minute: 50,
25    second: 50.52,
26    timeAbbrev: "Asia/Colombo",
27    utcOffset: zoneOffset
28};
29
30task:Error|task:JobId result = task:scheduleJobRecurByFrequency(new Job("Hi"), 2.5, maxCount = 10, startTime = time);

For an example on the usage of the scheduleJobRecurByFrequency, see the Task Frequency Job Execution Example.

Functions

[10]

configureWorkerPool

Configure the scheduler worker pool.

getRunningJobs

Gets all the running jobs.

getTimeInMillies

Gets time in milliseconds of the given time:Civil.

pauseAllJobs

Pauses all the jobs.

pauseJob

Pauses the particular job.

resumeAllJobs

Resumes all the jobs.

resumeJob

Resumes the particular job.

scheduleJobRecurByFrequency

Schedule the recurring job according to the given duration.

scheduleOneTimeJob

Schedule the given job for the given time.

unscheduleJob

Unschedule the job, which is associated with the given job ID.

Object Types

[1]

Job

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

Records

[2]

JobId

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

TaskPolicy

Policies related to a trigger.

Enums

[2]

ErrorPolicy

Possible options for the ErrorPolicy.

WaitingPolicy

Possible options for the WaitingPolicy.

Errors

[1]

Error

Represents the error type of the ballerina/task module.