diff options
Diffstat (limited to 'book/en/src/by-example')
| -rw-r--r-- | book/en/src/by-example/tasks.md | 6 | ||||
| -rw-r--r-- | book/en/src/by-example/timer-queue.md | 4 | ||||
| -rw-r--r-- | book/en/src/by-example/tips.md | 23 | ||||
| -rw-r--r-- | book/en/src/by-example/types-send-sync.md | 27 |
4 files changed, 12 insertions, 48 deletions
diff --git a/book/en/src/by-example/tasks.md b/book/en/src/by-example/tasks.md index ba16404..8558a54 100644 --- a/book/en/src/by-example/tasks.md +++ b/book/en/src/by-example/tasks.md @@ -6,15 +6,13 @@ application from any execution context. Software tasks can also be assigned priorities and, under the hood, are dispatched from interrupt handlers. RTIC requires that free interrupts are -declared in an `extern` block when using software tasks; some of these free +declared in the `dispatchers` app argument when using software tasks; some of these free interrupts will be used to dispatch the software tasks. An advantage of software tasks over hardware tasks is that many tasks can be mapped to a single interrupt handler. Software tasks are also declared using the `task` attribute but the `binds` -argument must be omitted. To be able to spawn a software task from a context -the name of the task must appear in the `spawn` argument of the context -attribute (`init`, `idle`, `task`, etc.). +argument must be omitted. The example below showcases three software tasks that run at 2 different priorities. The three software tasks are mapped to 2 interrupts handlers. diff --git a/book/en/src/by-example/timer-queue.md b/book/en/src/by-example/timer-queue.md index 482aebc..2964175 100644 --- a/book/en/src/by-example/timer-queue.md +++ b/book/en/src/by-example/timer-queue.md @@ -29,9 +29,7 @@ on the built-in CYCle CouNTer (CYCCNT). Note that this is a 32-bit timer clocked at the frequency of the CPU and as such it is not suitable for tracking time spans in the order of seconds. -To be able to schedule a software task from a context the name of the task must -first appear in the `schedule` argument of the context attribute. When -scheduling a task the (user-defined) `Instant` at which the task should be +When scheduling a task the (user-defined) `Instant` at which the task should be executed must be passed as the first argument of the `schedule` invocation. Additionally, the chosen `monotonic` timer must be configured and initialized diff --git a/book/en/src/by-example/tips.md b/book/en/src/by-example/tips.md index 090b30a..f537173 100644 --- a/book/en/src/by-example/tips.md +++ b/book/en/src/by-example/tips.md @@ -2,15 +2,8 @@ ## Generics -Resources may appear in contexts as resource proxies or as unique references -(`&mut-`) depending on the priority of the task. Because the same resource may -appear as *different* types in different contexts one cannot refactor a common -operation that uses resources into a plain function; however, such refactor is -possible using *generics*. - -All resource proxies implement the `rtic::Mutex` trait. On the other hand, -unique references (`&mut-`) do *not* implement this trait (due to limitations in -the trait system) but one can wrap these references in the [`rtic::Exclusive`] +All resource proxies implement the `rtic::Mutex` trait. +If a resource does not implement this, one can wrap it in the [`rtic::Exclusive`] newtype which does implement the `Mutex` trait. With the help of this newtype one can write a generic function that operates on generic resources and call it from different tasks to perform some operation on the same set of resources. @@ -27,15 +20,13 @@ $ cargo run --example generics {{#include ../../../../ci/expected/generics.run}} ``` -Using generics also lets you change the static priorities of tasks during -development without having to rewrite a bunch code every time. - ## Conditional compilation You can use conditional compilation (`#[cfg]`) on resources (the fields of -`struct Resources`) and tasks (the `fn` items). The effect of using `#[cfg]` -attributes is that the resource / task will *not* be available through the -corresponding `Context` `struct` if the condition doesn't hold. +`#[resources] struct Resources`) and tasks (the `fn` items). +The effect of using `#[cfg]` attributes is that the resource / task +will *not* be available through the corresponding `Context` `struct` +if the condition doesn't hold. The example below logs a message whenever the `foo` task is spawned, but only if the program has been compiled using the `dev` profile. @@ -132,7 +123,7 @@ You can inspect the file `rtic-expansion.rs` inside the `target` directory. This file contains the expansion of the `#[rtic::app]` item (not your whole program!) of the *last built* (via `cargo build` or `cargo check`) RTIC application. The expanded code is not pretty printed by default so you'll want to run `rustfmt` -over it before you read it. +on it before you read it. ``` console $ cargo build --example foo diff --git a/book/en/src/by-example/types-send-sync.md b/book/en/src/by-example/types-send-sync.md index 9cdb889..a45f179 100644 --- a/book/en/src/by-example/types-send-sync.md +++ b/book/en/src/by-example/types-send-sync.md @@ -27,31 +27,8 @@ resources. [`Send`]: https://doc.rust-lang.org/core/marker/trait.Send.html The `app` attribute will enforce that `Send` is implemented where required so -you don't need to worry much about it. It's more important to know where you do -*not* need the `Send` trait: on types that are transferred between tasks that -run at the *same* priority. This occurs in two places: in message passing and in -shared resources. - -The example below shows where a type that doesn't implement `Send` can be used. - -``` rust -{{#include ../../../../examples/not-send.rs}} -``` - -It's important to note that late initialization of resources is effectively a -send operation where the initial value is sent from the background context, -which has the lowest priority of `0`, to a task, which will run at a priority -greater than or equal to `1`. Thus all late resources need to implement the -`Send` trait, except for those exclusively accessed by `idle`, which runs at a -priority of `0`. - -Sharing a resource with `init` can be used to implement late initialization, see -example below. For that reason, resources shared with `init` must also implement -the `Send` trait. - -``` rust -{{#include ../../../../examples/shared-with-init.rs}} -``` +you don't need to worry much about it. Currently all types that are passed need +to be `Send` in RTIC, however this restriction might be relaxed in the future. ## `Sync` |