[RFC] Add API to re-schedule & cancel tasks

[korken89]

Summary

Add support for re-scheduling and canceling scheduled tasks.

Current behavior

Today there is no way to re-schedule or cancel scheduled tasks as:

#[rtfm::app]
const APP: () = {
    #[task(schedule = [timeout])]
    fn task(cx: task::Context) {
        // ... some work that needs timeout

        cx.schedule.timeout(SOME_TIME).unwrap();
        // ^^^ There is no way to make this re-schedule or cancel today
        // without an external resource and working around RTFM
    }

    #[task]
    fn timeout(cx: timeout::Context) {
        // Does the work if there was a timeout ...
    }
};

Proposal

Add an API to be able to re-schedule and cancel a scheduled task. This is something that also has been requested verbally and officially in rtfm-rs/cortex-m-rtfm#220, and is a sane feature. Creating watchdog & timeout tasks or scheduling on incomplete information is tricky today and needs working around RTFM.

Proposed syntax

For re-scheduling there are 2 options:

#[rtfm::app]
const APP: () = {
    #[task(schedule = [timeout])]
    fn task(cx: task::Context) {
        // ... some work that needs timeout

        // Option 1:
        cx.schedule.timeout(SOME_TIME).unwrap();
        // ^^^ This automatically re-schedules

        // Option 2: Add a specific API 
        cx.reschedule.timeout(SOME_TIME).unwrap();
    }

    #[task]
    fn timeout(cx: timeout::Context) {
        // Does the work if there was a timeout ...
    }
};

Here a Result should be return telling if the task was rescheduled (Ok), or if the task has already been pended for execution (Err).

And for canceling, the straight forward syntax as follows:

#[rtfm::app]
const APP: () = {
    #[task(schedule = [timeout])]
    fn task(cx: task::Context) {
        // ... some work that needs timeout
        cx.schedule.timeout(SOME_TIME).unwrap();

        // decide that we want to cancel the scheduled task
        cx.cancel.timeout().unwrap();
    }

    #[task]
    fn timeout(cx: timeout::Context) {
        // Does the work if there was a timeout ...
    }
};

Also here a Result should be return telling if the task was canceled (Ok), or if the task has already been started/executed (Err).

Not in scope

• This proposal is for tasks with capacity of 1. Rescheduling and canceling task that have capacity would be a future extension if need arises.

Issues to tackle

1. The schedule list probably becomes an O(n) list instead of using the binary heap we have today This can most likely be solved by running sift up/down.
2. Bike-shed the API
3. More concerns?

[korken89]

Another API that Per hinted at, let schedule return a handle that can re-schedule or cancel:

#[rtfm::app]
const APP: () = {
    #[task(schedule = [timeout])]
    fn task(cx: task::Context) {
        // ... some work that needs timeout
        let handle = cx.schedule.timeout(SOME_TIME).unwrap();

        // re-schedule the task
        handle.reschedule(NEW_TIME).unwrap();

        // decide that we want to cancel the scheduled task
        handle.cancel().unwrap();
    }

    #[task]
    fn timeout(cx: timeout::Context) {
        // Does the work if there was a timeout ...
    }
};

There might be issues with having a handle into the list though, not 100% sure about issues here.

[japaric]

My thoughts on the APIs specified in this proposal

For re-scheduling there are 2 options:

How do these interact with multiple instances of a task?

In option 1, how do I schedule a new instance of a task vs how do I reschedule a
task?

#[task]
fn foo(cx: foo::Context) {
    cx.schedule.bar(t1, i1).unwrap();
    // does this reschedule the previous task or
    // does it reschedule the previous invocation
    cx.schedule.bar(t2, i2).unwrap();
}

#[task(capacity = 2)]
fn bar(cx: bar::Context, i: Input) { /*.. */ }

In option 2, does reschedule schedules the last instance of a task? If so, how
do I reschedule previous instances of a task?

#[task]
fn foo(cx: foo::Context) {
    cx.schedule.bar(t1, i1).unwrap(); // A
    cx.schedule.bar(t2, i2).unwrap(); // B
    // does this reschedule B? how do I reschedule A?
    cx.reschedule.bar(t3).unwrap();
}

#[task(capacity = 2)]
fn bar(cx: bar::Context, i: Input) { /*.. */ }

---

And for canceling

Same question regarding multiple instances of a task.

Additionally, this doesn't specify whether an Ok cancel immediately frees up a
slot in the queue. This affects the implementation and we could leave it
unspecified but users of this feature may want or expect the 'immediately frees'
behavior so it should be specified, I think.

#[task(priority = HIGHEST)]
fn foo(cx: foo::Context) {
    cx.schedule.bar(t1, i1).unwrap();
    cx.cancel.bar().unwrap();
    // is this guaranteed to never panic?
    cx.schedule.bar(t2, i2).unwrap();
}

---

The text says

if the task has already been pended for execution

then the task won't be canceled / rescheduled.

I think this needs further elaboration. Software tasks can be multiplexed on a
single interrupt handler so it is possible to cancel / reschedule after that
handler has been pended (see below).

#[task(priority = 2, schedule = [bar, baz])]
fn foo(cx: foo::Context) {
    cx.schedule.bar(t1).unwrap();
    cx.schedule.baz(t1).unwrap();
}

#[task(priority = 1)]
fn bar(cx: bar::Context) {
    // `baz` is next in the ready queue; it is still possible to cancel it
    cx.cancel.baz().unwrap();
}

#[task(priority = 1)]
fn baz(cx: baz::Context) {
    // ..
}

The question whether the semantics will permit this operation or not. I think
the text should either say 'if the task has already started executing' (i.e.
have been removed from the ready queue) OR 'if the scheduled time has expired'
(i.e. the task have been moved from the timer queue into the respective ready
queue); I think the semantics are clearer with either phrasing; also, this
phrasing doesn't mention the detail implementation of 'pending an interrupt',
which I think it's a good thing.

---

Another API that Per hinted at, let schedule return a handle that can
re-schedule or cancel:

This solves the issue of how to select the instance to cancel / reschedule. What
then needs to specified in this alternative is whether the handle can be sent to
a different task (i.e. Send and / or 'static bounds) and then be canceled /
rescheduled from there. This affects the ceiling analysis; in the more general
case of being able to send the handle to any task then the ceiling analysis
needs to be overly pessimistic (e.g. 'may be canceled from the highest priority
task').

---

Talking about ceiling analysis the original proposal doesn't say whether the
user needs to specify whether a task can cancel / reschedule a task or not, or
whether needs to specify the tasks a task can cancel / reschedule (i.e. cancel = [foo] in the list of task arguments). This information may be needed to
extend the ceiling analysis to support these features in a memory-safe way.

[japaric]

during the meeting we were wondering if @korken89 had as main use case in mind the scenario where the task always a capacity of 1. In that case not having the handle (you just do cx.cancel) seems more ergonomic.

We could start with the simpler no-handle API and then see if there's demand for the more general handle API

[adamgreig]

A need for something similar to this API came up in my use case: after an external event, I want to schedule a task to run some constant time later. If the event occurs a second time before the scheduled task has executed, I want to re-schedule that task to run after this second event, discarding the first schedule.

At first glance option 1 or 2 above would work (though I agree with @japaric's thoughts re multiple instances; not a problem in my case though). But I'm not sure about the option 2 API: does it only work if the task is already scheduled? Or can you always call 'reschedule' and it either schedules or reschedules?

For the time being, I'm using a shared resource Instant which the event handler sets to the current moment, and a regular software task that checks the time elapsed since the Instant and triggers if it exceeds my desired delay. This works OK but I have to be pretty careful because Instant::elapsed() has an unavoidable panic after the counter wraps around.

[korken89]

The text has been updated.

[japaric]

But I'm not sure about the option 2 API: does it only work if the task is already scheduled? Or can you always call 'reschedule' and it either schedules or reschedules?

According to the updated text reschedule returns Err if the task was already moved the ready queue (it's scheduled time has already passed). So if you want the 'either schedules or reschedules' semantics then you would need to write:

if cx.reschedule.timeout(some_time).is_err() {
    cx.schedule.timeout(some_time).unwrap()
}

---

Some things that needs to be clarified / specified:

• reschedule also returns an Err if schedule was never called before, i.e. there's nothing to reschedule
• reschedule-ing a task is only possible from tasks that list the task in their schedule list; that is a and b are OK but c is not

#[task(schedule = [z])]
fn a(cx: a::Context) {
    cx.schedule.z(t1);
}

#[task(schedule = [z])]
fn b(cx: b::Context) {
    cx.reschedule.z(t2);
}

#[task]
fn c(cx: c::Context) {
    cx.reschedule.z(t3); //~ ERROR no method `z` on type `c::Reschedule`
}

• Same thing with the cancel API; a and b are OK but c is not

#[task(schedule = [z])]
fn a(cx: a::Context) {
    cx.schedule.z(t1);
}

#[task(schedule = [z])]
fn b(cx: b::Context) {
    cx.cancel.z();
}

#[task]
fn c(cx: c::Context) {
    cx.cancel.z(); //~ ERROR no method `z` on type `c::Cancel`
}

---

Other than that I think a prototype implementation is needed to understand the memory / runtime cost of these features and if they have impact on tasks that won't be reschedule-d / cancel-ed. For example, cancel can be implemented using an AtomicBool (CANCELED) on the side for each task that may be canceled, even if they will never actually be canceled. But there may be other implementation options.

[AfoHT]

A way to cancel spawn_after and spawn_at-ed tasks, allowing one to also reschedule them is available since cortex-m-rtic PR528, part of version v0.6.0-rc.1 and onwards.

Documented in https://rtic.rs/1/book/en/by-example/monotonic.html#canceling-or-rescheduling-a-scheduled-task

Closing this as done 🎉