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(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 = 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(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 = 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.