mirror of
https://github.com/rtic-rs/rtic.git
synced 2024-12-25 11:29:33 +01:00
466 lines
20 KiB
HTML
466 lines
20 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="light sidebar-visible" dir="ltr">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>Delay and Timeout using Monotonics - Real-Time Interrupt-driven Concurrency</title>
|
|
|
|
|
|
<!-- Custom HTML head -->
|
|
|
|
<meta name="description" content="">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="theme-color" content="#ffffff">
|
|
|
|
<link rel="icon" href="../favicon.svg">
|
|
<link rel="shortcut icon" href="../favicon.png">
|
|
<link rel="stylesheet" href="../css/variables.css">
|
|
<link rel="stylesheet" href="../css/general.css">
|
|
<link rel="stylesheet" href="../css/chrome.css">
|
|
<link rel="stylesheet" href="../css/print.css" media="print">
|
|
|
|
<!-- Fonts -->
|
|
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
|
<link rel="stylesheet" href="../fonts/fonts.css">
|
|
|
|
<!-- Highlight.js Stylesheets -->
|
|
<link rel="stylesheet" href="../highlight.css">
|
|
<link rel="stylesheet" href="../tomorrow-night.css">
|
|
<link rel="stylesheet" href="../ayu-highlight.css">
|
|
|
|
<!-- Custom theme stylesheets -->
|
|
|
|
|
|
<!-- Provide site root to javascript -->
|
|
<script>
|
|
var path_to_root = "../";
|
|
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
|
</script>
|
|
<!-- Start loading toc.js asap -->
|
|
<script src="../toc.js"></script>
|
|
</head>
|
|
<body>
|
|
<div id="body-container">
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|
<script>
|
|
try {
|
|
var theme = localStorage.getItem('mdbook-theme');
|
|
var sidebar = localStorage.getItem('mdbook-sidebar');
|
|
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|
}
|
|
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|
}
|
|
} catch (e) { }
|
|
</script>
|
|
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|
<script>
|
|
var theme;
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|
const html = document.documentElement;
|
|
html.classList.remove('light')
|
|
html.classList.add(theme);
|
|
html.classList.add("js");
|
|
</script>
|
|
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
|
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|
<script>
|
|
var sidebar = null;
|
|
var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
|
if (document.body.clientWidth >= 1080) {
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|
sidebar = sidebar || 'visible';
|
|
} else {
|
|
sidebar = 'hidden';
|
|
}
|
|
sidebar_toggle.checked = sidebar === 'visible';
|
|
html.classList.remove('sidebar-visible');
|
|
html.classList.add("sidebar-" + sidebar);
|
|
</script>
|
|
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|
<!-- populated by js -->
|
|
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
|
<noscript>
|
|
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
|
</noscript>
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
|
<div class="sidebar-resize-indicator"></div>
|
|
</div>
|
|
</nav>
|
|
|
|
<div id="page-wrapper" class="page-wrapper">
|
|
|
|
<div class="page">
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|
<div id="menu-bar" class="menu-bar sticky">
|
|
<div class="left-buttons">
|
|
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|
<i class="fa fa-bars"></i>
|
|
</label>
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|
<i class="fa fa-paint-brush"></i>
|
|
</button>
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|
</ul>
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
|
<i class="fa fa-search"></i>
|
|
</button>
|
|
</div>
|
|
|
|
<h1 class="menu-title">Real-Time Interrupt-driven Concurrency</h1>
|
|
|
|
<div class="right-buttons">
|
|
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
|
<i id="print-button" class="fa fa-print"></i>
|
|
</a>
|
|
<a href="https://github.com/rtic-rs/rtic" title="Git repository" aria-label="Git repository">
|
|
<i id="git-repository-button" class="fa fa-github"></i>
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="search-wrapper" class="hidden">
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|
</form>
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|
<ul id="searchresults">
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|
<script>
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|
});
|
|
</script>
|
|
|
|
<div id="content" class="content">
|
|
<main>
|
|
<h1 id="tasks-with-delay"><a class="header" href="#tasks-with-delay">Tasks with delay</a></h1>
|
|
<p>A convenient way to express miniminal timing requirements is by delaying progression.</p>
|
|
<p>This can be achieved by instantiating a monotonic timer (for implementations, see <a href="https://github.com/rtic-rs/rtic/tree/master/rtic-monotonics"><code>rtic-monotonics</code></a>):</p>
|
|
<pre><code class="language-rust noplayground">...
|
|
#[init]
|
|
fn init(cx: init::Context) -> (Shared, Local) {
|
|
hprintln!("init");
|
|
|
|
Mono::start(cx.core.SYST, 12_000_000);
|
|
...</code></pre>
|
|
<p>A <em>software</em> task can <code>await</code> the delay to expire:</p>
|
|
<pre><code class="language-rust noplayground">#[task]
|
|
async fn foo(_cx: foo::Context) {
|
|
...
|
|
Systick::delay(100.millis()).await;
|
|
...
|
|
}
|
|
</code></pre>
|
|
<details>
|
|
<summary>A complete example</summary>
|
|
<pre><code class="language-rust noplayground">//! examples/async-delay.rs
|
|
|
|
#![no_main]
|
|
#![no_std]
|
|
#![deny(warnings)]
|
|
#![deny(unsafe_code)]
|
|
#![deny(missing_docs)]
|
|
|
|
use panic_semihosting as _;
|
|
|
|
#[rtic::app(device = lm3s6965, dispatchers = [SSI0, UART0], peripherals = true)]
|
|
mod app {
|
|
use cortex_m_semihosting::{debug, hprintln};
|
|
use rtic_monotonics::systick::prelude::*;
|
|
|
|
systick_monotonic!(Mono, 100);
|
|
|
|
#[shared]
|
|
struct Shared {}
|
|
|
|
#[local]
|
|
struct Local {}
|
|
|
|
#[init]
|
|
fn init(cx: init::Context) -> (Shared, Local) {
|
|
hprintln!("init");
|
|
|
|
Mono::start(cx.core.SYST, 12_000_000);
|
|
|
|
foo::spawn().ok();
|
|
bar::spawn().ok();
|
|
baz::spawn().ok();
|
|
|
|
(Shared {}, Local {})
|
|
}
|
|
|
|
#[task]
|
|
async fn foo(_cx: foo::Context) {
|
|
hprintln!("hello from foo");
|
|
Mono::delay(100.millis()).await;
|
|
hprintln!("bye from foo");
|
|
}
|
|
|
|
#[task]
|
|
async fn bar(_cx: bar::Context) {
|
|
hprintln!("hello from bar");
|
|
Mono::delay(200.millis()).await;
|
|
hprintln!("bye from bar");
|
|
}
|
|
|
|
#[task]
|
|
async fn baz(_cx: baz::Context) {
|
|
hprintln!("hello from baz");
|
|
Mono::delay(300.millis()).await;
|
|
hprintln!("bye from baz");
|
|
|
|
debug::exit(debug::EXIT_SUCCESS);
|
|
}
|
|
}</code></pre>
|
|
<pre><code class="language-console">$ cargo xtask qemu --verbose --example async-delay --features test-critical-section
|
|
</code></pre>
|
|
<pre><code class="language-console">init
|
|
hello from bar
|
|
hello from baz
|
|
hello from foo
|
|
bye from foo
|
|
bye from bar
|
|
bye from baz
|
|
</code></pre>
|
|
</details>
|
|
<blockquote>
|
|
<p>Interested in contributing new implementations of <a href="https://docs.rs/rtic-time/latest/rtic_time/trait.Monotonic.html"><code>Monotonic</code></a>, or more information about the inner workings of monotonics?
|
|
Check out the <a href="../monotonic_impl.html">Implementing a <code>Monotonic</code></a> chapter!</p>
|
|
</blockquote>
|
|
<h2 id="timeout"><a class="header" href="#timeout">Timeout</a></h2>
|
|
<p>Rust <a href="https://doc.rust-lang.org/std/future/trait.Future.html"><code>Future</code></a>s (underlying Rust <code>async</code>/<code>await</code>) are composable. This makes it possible to <code>select</code> in between <code>Futures</code> that have completed.</p>
|
|
<p>A common use case is transactions with an associated timeout. In the examples shown below, we introduce a fake HAL device that performs some transaction. We have modelled the time it takes based on the input parameter (<code>n</code>) as <code>350ms + n * 100ms</code>.</p>
|
|
<p>Using the <code>select_biased</code> macro from the <code>futures</code> crate it may look like this:</p>
|
|
<pre><code class="language-rust noplayground noplayground"> // Call hal with short relative timeout using `select_biased`
|
|
select_biased! {
|
|
v = hal_get(1).fuse() => hprintln!("hal returned {}", v),
|
|
_ = Mono::delay(200.millis()).fuse() => hprintln!("timeout", ), // this will finish first
|
|
}
|
|
|
|
// Call hal with long relative timeout using `select_biased`
|
|
select_biased! {
|
|
v = hal_get(1).fuse() => hprintln!("hal returned {}", v), // hal finish first
|
|
_ = Mono::delay(1000.millis()).fuse() => hprintln!("timeout", ),
|
|
}</code></pre>
|
|
<p>Assuming the <code>hal_get</code> will take 450ms to finish, a short timeout of 200ms will expire before <code>hal_get</code> can complete.</p>
|
|
<p>Extending the timeout to 1000ms would cause <code>hal_get</code> will to complete first.</p>
|
|
<p>Using <code>select_biased</code> any number of futures can be combined, so its very powerful. However, as the timeout pattern is frequently used, more ergonomic support is baked into RTIC, provided by the <a href="https://github.com/rtic-rs/rtic/tree/master/rtic-monotonics"><code>rtic-monotonics</code></a> and <a href="https://github.com/rtic-rs/rtic/tree/master/rtic-time"><code>rtic-time</code></a> crates.</p>
|
|
<p>Rewriting the second example from above using <code>timeout_after</code> gives:</p>
|
|
<pre><code class="language-rust noplayground"> // get the current time instance
|
|
let mut instant = Mono::now();
|
|
|
|
// do this 3 times
|
|
for n in 0..3 {
|
|
// absolute point in time without drift
|
|
instant += 1000.millis();
|
|
Mono::delay_until(instant).await;
|
|
|
|
// absolute point in time for timeout
|
|
let timeout = instant + 500.millis();
|
|
hprintln!("now is {:?}, timeout at {:?}", Mono::now(), timeout);
|
|
|
|
match Mono::timeout_at(timeout, hal_get(n)).await {
|
|
Ok(v) => hprintln!("hal returned {} at time {:?}", v, Mono::now()),
|
|
_ => hprintln!("timeout"),
|
|
}
|
|
}</code></pre>
|
|
<p>In cases where you want exact control over time without drift we can use exact points in time using <code>Instant</code>, and spans of time using <code>Duration</code>. Operations on the <code>Instant</code> and <code>Duration</code> types come from the [<code>fugit</code>] crate.</p>
|
|
<p><code>let mut instant = Systick::now()</code> sets the starting time of execution.</p>
|
|
<p>We want to call <code>hal_get</code> after 1000ms relative to this starting time. This can be accomplished by using <code>Systick::delay_until(instant).await</code>.</p>
|
|
<p>Then, we define a point in time called <code>timeout</code>, and call <code>Systick::timeout_at(timeout, hal_get(n)).await</code>.</p>
|
|
<p>For the first iteration of the loop, with <code>n == 0</code>, the <code>hal_get</code> will take 350ms (and finishes before the timeout).</p>
|
|
<p>For the second iteration, with <code>n == 1</code>, the <code>hal_get</code> will take 450ms (and again succeeds to finish before the timeout).</p>
|
|
<p>For the third iteration, with <code>n == 2</code>, <code>hal_get</code> will take 550ms to finish, in which case we will run into a timeout.</p>
|
|
<details>
|
|
<summary>A complete example</summary>
|
|
<pre><code class="language-rust noplayground">//! examples/async-timeout.rs
|
|
|
|
#![no_main]
|
|
#![no_std]
|
|
#![deny(warnings)]
|
|
#![deny(unsafe_code)]
|
|
#![deny(missing_docs)]
|
|
|
|
use cortex_m_semihosting::{debug, hprintln};
|
|
use panic_semihosting as _;
|
|
use rtic_monotonics::systick::prelude::*;
|
|
systick_monotonic!(Mono, 100);
|
|
|
|
#[rtic::app(device = lm3s6965, dispatchers = [SSI0, UART0], peripherals = true)]
|
|
mod app {
|
|
use super::*;
|
|
use futures::{future::FutureExt, select_biased};
|
|
|
|
#[shared]
|
|
struct Shared {}
|
|
|
|
#[local]
|
|
struct Local {}
|
|
|
|
// ANCHOR: init
|
|
#[init]
|
|
fn init(cx: init::Context) -> (Shared, Local) {
|
|
hprintln!("init");
|
|
|
|
Mono::start(cx.core.SYST, 12_000_000);
|
|
// ANCHOR_END: init
|
|
|
|
foo::spawn().ok();
|
|
|
|
(Shared {}, Local {})
|
|
}
|
|
|
|
#[task]
|
|
async fn foo(_cx: foo::Context) {
|
|
// ANCHOR: select_biased
|
|
// Call hal with short relative timeout using `select_biased`
|
|
select_biased! {
|
|
v = hal_get(1).fuse() => hprintln!("hal returned {}", v),
|
|
_ = Mono::delay(200.millis()).fuse() => hprintln!("timeout", ), // this will finish first
|
|
}
|
|
|
|
// Call hal with long relative timeout using `select_biased`
|
|
select_biased! {
|
|
v = hal_get(1).fuse() => hprintln!("hal returned {}", v), // hal finish first
|
|
_ = Mono::delay(1000.millis()).fuse() => hprintln!("timeout", ),
|
|
}
|
|
// ANCHOR_END: select_biased
|
|
|
|
// ANCHOR: timeout_after_basic
|
|
// Call hal with long relative timeout using monotonic `timeout_after`
|
|
match Mono::timeout_after(1000.millis(), hal_get(1)).await {
|
|
Ok(v) => hprintln!("hal returned {}", v),
|
|
_ => hprintln!("timeout"),
|
|
}
|
|
// ANCHOR_END: timeout_after_basic
|
|
|
|
// ANCHOR: timeout_at_basic
|
|
// get the current time instance
|
|
let mut instant = Mono::now();
|
|
|
|
// do this 3 times
|
|
for n in 0..3 {
|
|
// absolute point in time without drift
|
|
instant += 1000.millis();
|
|
Mono::delay_until(instant).await;
|
|
|
|
// absolute point in time for timeout
|
|
let timeout = instant + 500.millis();
|
|
hprintln!("now is {:?}, timeout at {:?}", Mono::now(), timeout);
|
|
|
|
match Mono::timeout_at(timeout, hal_get(n)).await {
|
|
Ok(v) => hprintln!("hal returned {} at time {:?}", v, Mono::now()),
|
|
_ => hprintln!("timeout"),
|
|
}
|
|
}
|
|
// ANCHOR_END: timeout_at_basic
|
|
|
|
debug::exit(debug::EXIT_SUCCESS);
|
|
}
|
|
}
|
|
|
|
// Emulate some hal
|
|
async fn hal_get(n: u32) -> u32 {
|
|
// emulate some delay time dependent on n
|
|
let d = 350.millis() + n * 100.millis();
|
|
hprintln!("the hal takes a duration of {:?}", d);
|
|
Mono::delay(d).await;
|
|
// emulate some return value
|
|
5
|
|
}</code></pre>
|
|
<pre><code class="language-console">$ cargo xtask qemu --verbose --example async-timeout --features test-critical-section
|
|
</code></pre>
|
|
<pre><code class="language-console">init
|
|
the hal takes a duration of Duration { ticks: 45 }
|
|
timeout
|
|
the hal takes a duration of Duration { ticks: 45 }
|
|
hal returned 5
|
|
the hal takes a duration of Duration { ticks: 45 }
|
|
hal returned 5
|
|
now is Instant { ticks: 213 }, timeout at Instant { ticks: 263 }
|
|
the hal takes a duration of Duration { ticks: 35 }
|
|
hal returned 5 at time Instant { ticks: 249 }
|
|
now is Instant { ticks: 313 }, timeout at Instant { ticks: 363 }
|
|
the hal takes a duration of Duration { ticks: 45 }
|
|
hal returned 5 at time Instant { ticks: 359 }
|
|
now is Instant { ticks: 413 }, timeout at Instant { ticks: 463 }
|
|
the hal takes a duration of Duration { ticks: 55 }
|
|
timeout
|
|
</code></pre>
|
|
</details>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<a rel="prev" href="../by-example/channel.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="../by-example/app_minimal.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
|
|
<div style="clear: both"></div>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|
<a rel="prev" href="../by-example/channel.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="../by-example/app_minimal.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
</nav>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<script>
|
|
window.playground_copyable = true;
|
|
</script>
|
|
|
|
|
|
<script src="../elasticlunr.min.js"></script>
|
|
<script src="../mark.min.js"></script>
|
|
<script src="../searcher.js"></script>
|
|
|
|
<script src="../clipboard.min.js"></script>
|
|
<script src="../highlight.js"></script>
|
|
<script src="../book.js"></script>
|
|
|
|
<!-- Custom JS scripts -->
|
|
<script src="../mermaid.min.js"></script>
|
|
<script src="../mermaid-init.js"></script>
|
|
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|