1
0
Fork 0
mirror of https://github.com/rtic-rs/rtic.git synced 2024-12-24 19:09:33 +01:00
rtic/book/en/archive/by_example/monotonic.md
Franz Dietrich 53ed7bf7ed
fix included examples and markdown(book) ()
* fix included examples and markdown(book)

fixes: 

* fix footnote pre_init

* more example link updates

* Restore pool example name

* Example: pool: Upgrade to heapless v0.8

* Example: pool: thumbv6 unsupported: wild cfg-if

Experiment with multi-backend example contained in the example

* Example: lm3s6965: Updated cargo.lock

* Book: Use cargo xtask for by-example

* Docs: Contributing: cargo xtask

---------

Co-authored-by: Henrik Tjäder <henrik@tjaders.com>
2024-04-03 22:01:46 +00:00

64 lines
2.8 KiB
Markdown

# Monotonic & spawn_{at/after}
The understanding of time is an important concept in embedded systems, and to be able to run tasks
based on time is essential. The framework provides the static methods
`task::spawn_after(/* duration */)` and `task::spawn_at(/* specific time instant */)`.
`spawn_after` is more commonly used, but in cases where it's needed to have spawns happen
without drift or to a fixed baseline `spawn_at` is available.
The `#[monotonic]` attribute, applied to a type alias definition, exists to support this.
This type alias must point to a type which implements the [`rtic_monotonic::Monotonic`] trait.
This is generally some timer which handles the timing of the system.
One or more monotonics can coexist in the same system, for example a slow timer that wakes the
system from sleep and another which purpose is for fine grained scheduling while the
system is awake.
[`rtic_monotonic::Monotonic`]: https://docs.rs/rtic-monotonic
The attribute has one required parameter and two optional parameters, `binds`, `default` and
`priority` respectively.
The required parameter, `binds = InterruptName`, associates an interrupt vector to the timer's
interrupt, while `default = true` enables a shorthand API when spawning and accessing
time (`monotonics::now()` vs `monotonics::MyMono::now()`), and `priority` sets the priority
of the interrupt vector.
> The default `priority` is the **maximum priority** of the system.
> If your system has a high priority task with tight scheduling requirements,
> it might be desirable to demote the `monotonic` task to a lower priority
> to reduce scheduling jitter for the high priority task.
> This however might introduce jitter and delays into scheduling via the `monotonic`,
> making it a trade-off.
The monotonics are initialized in `#[init]` and returned within the `init::Monotonic( ... )` tuple.
This activates the monotonics making it possible to use them.
See the following example:
``` rust,noplayground
{{#include ../../../../examples/schedule.rs}}
```
``` console
$ cargo xtask qemu --verbose --example schedule
{{#include ../../../../ci/expected/schedule.run}}
```
A key requirement of a Monotonic is that it must deal gracefully with
hardware timer overruns.
## Canceling or rescheduling a scheduled task
Tasks spawned using `task::spawn_after` and `task::spawn_at` returns a `SpawnHandle`,
which allows canceling or rescheduling of the task scheduled to run in the future.
If `cancel` or `reschedule_at`/`reschedule_after` returns an `Err` it means that the operation was
too late and that the task is already sent for execution. The following example shows this in action:
``` rust,noplayground
{{#include ../../../../examples/cancel-reschedule.rs}}
```
``` console
$ cargo xtask qemu --verbose --example cancel-reschedule
{{#include ../../../../ci/expected/cancel-reschedule.run}}
```