Struct Task

Source

pub struct Task { /* private fields */ }

Expand description

Task represents a single job with its schedule, attributes, and state.

Implementations§

Source §

impl Task

Source

pub fn new<T>(schedule: TaskSchedule, job: T) -> Self
where T: 'static + FnMut(JobId) -> Pin<Box<dyn Future<Output = ()> + Send>> + Send + Sync,

Creates new Task with specified schedule, job function and default TaskId.

§Examples

use sacs::task::{CronOpts, Task, TaskSchedule};
use std::time::Duration;

let schedule = TaskSchedule::Cron("*/5 * * * * *".try_into().unwrap(), CronOpts::default());
let task = Task::new(schedule, |id| {
    Box::pin(async move {
        // Actual async workload here
        tokio::time::sleep(Duration::from_secs(1)).await;
        // ...
        println!("Job {id} finished.");
        })
    });

Source

pub fn with_id(self, id: impl Into<TaskId>) -> Self

Set explicit TaskId to the existing Task.

This method is useful if you need to know TaskId before the task was scheduled.

§Note:

If you provide explicit TaskId value, your responsibility is to ensure the uniqueness of the TaskId within instance of Scheduler.

This method consumes Task instance and returns the same instance with specified Id. Since Task is cloneable, this method can be used to create several identical tasks with different TaskIds.

§Examples:

use sacs::task::{CronOpts, Task, TaskId, TaskSchedule};
use std::time::Duration;
use uuid::Uuid;

let schedule = TaskSchedule::Cron("*/5 * * * * *".try_into().unwrap(), CronOpts::default());
let task1_id = Uuid::new_v4();
let task_id = task1_id.clone();

let task1 = Task::new(schedule.clone(), move |id| {
    let task_id = task_id.clone();
    Box::pin(async move {
        println!("TaskId={task_id}.");
        // Actual async workload here
        tokio::time::sleep(Duration::from_secs(1)).await;
        // ...
        println!("Job {id} finished.");
        })
    }).with_id(task1_id);

let task2 = task1.clone().with_id(Uuid::new_v4());

let task3 = Task::new(schedule, |id| {
    Box::pin(async move {
        // Actual async workload here
        tokio::time::sleep(Duration::from_secs(1)).await;
        // ...
        println!("Job {id} finished.");
        })
    }).with_id("This is abstract unique task id");

Source

pub fn with_schedule(self, schedule: impl Into<TaskSchedule>) -> Self

Set specific TaskSchedule to the existing Task.

Method is useful if you need to create a new task based on existing (not scheduled yet) Task.

Method consumes Task instance and returns the same instance with specified TaskSchedule. Since Task is cloneable, this method can be used to create several identical tasks with different schedules.

Be careful: Task::clone() doesn’t change TaskId, so it’s your responsibility to ensure the uniqueness of task’s Id before posting it to Scheduler. Anyway, Scheduler::add() method rejects new Task if the same (with the same TaskId) is already present, even if it’s finished but not removed by getting its status or by garbage collector.

§Examples:

use sacs::task::{Task, TaskSchedule};
use std::time::Duration;

let task1 = Task::new(TaskSchedule::Once, move |id| {
    Box::pin(async move {
        println!("Starting job {id}.");
        // Actual async workload here
        tokio::time::sleep(Duration::from_secs(1)).await;
        // ...
        println!("Job {id} finished.");
        })
    });

let task2 = task1.clone()
        .with_schedule(TaskSchedule::OnceDelayed(Duration::from_secs(5)))
        .with_id("Execute once with 5s delay");

let task3 = task1.clone()
        .with_schedule(TaskSchedule::IntervalDelayed(
            Duration::from_secs(2),
            Duration::from_secs(1),
        ))
        .with_id("Repeats every 2s");

Source

pub fn with_timeout(self, timeout: impl Into<Duration>) -> Self

Add execution time limit to the existing Task.

Method is useful to constrain execution time when long-running time is evidence of the potential issue.

Method consumes Task instance and returns the same instance with time constraint added. Since Task is cloneable, this method can be used to create several identical tasks with different limits.

Be careful: Task::clone() doesn’t change TaskId, so it’s your responsibility to ensure the uniqueness of task’s Id before posting it to Scheduler. Anyway, Scheduler::add() method rejects new Task if the same (with the same TaskId) is already present, even if it’s finished but not removed by getting its status or by garbage collector.

§Examples:

use sacs::task::{Task, TaskSchedule};
use std::time::Duration;

let task1 = Task::new(TaskSchedule::Once, move |id| {
    Box::pin(async move {
        println!("Starting job {id}.");
        // Actual async workload here
        tokio::time::sleep(Duration::from_secs(2)).await;
        // ...
        println!("Job {id} finished.");
        })
    })
    .with_timeout(Duration::from_secs(5))
    .with_id("Execute once with 5s timeout, should succeed");

let task2 = task1.clone()
        .with_timeout(Duration::from_secs(1))
        .with_id("Execute once with 1s timeout, should fail");

Source

pub fn new_with_id<T>(schedule: TaskSchedule, job: T, id: TaskId) -> Self
where T: 'static + FnMut(JobId) -> Pin<Box<dyn Future<Output = ()> + Send>> + Send + Sync,

👎Deprecated since 0.4.2: please use with_id method instead.

Create a new Task with a specified schedule, job function and explicit TaskId.

This method is useful if you need to know TaskId before a task is scheduled. Or need to use TaskId within job context: for a particular task it’s TaskId is constant value, but JobId varies for each task run.

§Note:

If you provide explicit TaskId value, your responsibility is to ensure the uniqueness of the TaskId within instance of Scheduler.

§Examples:

use sacs::task::{CronOpts, Task, TaskId, TaskSchedule};
use std::time::Duration;
use uuid::Uuid;

let schedule = TaskSchedule::Cron("*/5 * * * * *".try_into().unwrap(), CronOpts::default());
let task1_id = Uuid::new_v4();
let task_id = task1_id.clone();

let task1 = Task::new_with_id(schedule.clone(), move |id| {
    let task_id = task_id.clone();
    Box::pin(async move {
        println!("TaskId={task_id}.");
        // Actual async workload here
        tokio::time::sleep(Duration::from_secs(1)).await;
        // ...
        println!("Job {id} finished.");
        })
    }, task1_id.into());

let task2 = Task::new_with_id(schedule, |id| {
    Box::pin(async move {
        // Actual async workload here
        tokio::time::sleep(Duration::from_secs(1)).await;
        // ...
        println!("Job {id} finished.");
        })
    }, Uuid::new_v4().into());