Tokio integration
Install Tokio as the background executor, await Tokio resources in UI tasks, and connect Tokio channels to reactive state.
zgui runs without Tokio. Install the integration when your application uses tokio::time,
tokio::net, tokio::fs, or a library built on them such as reqwest, sqlx or tonic. These
panic outside a Tokio runtime, and zgui's default thread pool
does not provide one.
When you need Tokio
| You use | Needs install |
|---|---|
background with an ordinary future | no |
blocking | no |
futures channels | no |
tokio::sync channels | no |
tokio::time, tokio::net, tokio::fs | yes |
reqwest, sqlx, tonic or another runtime-dependent library | yes |
Install the runtime
Turn on zgui's tokio feature, and add Tokio itself when your code names Tokio APIs:
[dependencies]
zgui = { version = "0.1", features = ["tokio"] }
tokio = { version = "1", features = ["fs"] }The integration already enables Tokio's rt-multi-thread, time, net and sync features. List
any others you use, such as fs.
Install the runtime at the top of main, on the thread that runs the application:
use zgui::prelude::*;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let _tokio = zgui::tokio::install()?;
app()
.with_title("Tasks")
.run(|| view! { App() })?;
Ok(())
}install builds a multi-threaded runtime with all drivers enabled. Keep the returned Installed
guard alive for the whole run. Dropping it shuts the runtime down without waiting: background work
still in flight is abandoned, and awaiting its result panics.
Install before the first background or blocking call. Once the default pool has received work,
install fails with zgui::tokio::Error::Spawner(SpawnerError::AlreadyRunning).
What install changes
backgroundruns on the Tokio runtime, andblockingon Tokio's blocking pool.- zgui polls UI tasks inside the runtime context.
The second point means a UI task can await Tokio resources directly:
use std::time::Duration;
spawn(async move {
tokio::time::sleep(Duration::from_secs(3)).await;
visible.set(false);
});The task still runs on the UI thread. Tokio provides the timer and I/O drivers and the wake; it
does not move the task to a Tokio worker. Waiting on a timer or socket there is fine, but parsing a
large response still delays the frame, so wrap that kind of call in background:
spawn(async move {
let result = background(async move { client.load_rows().await }).await;
rows.set(result);
});Tokio does not replace zgui's UI executor; it only fills the background executor and the runtime context. Installing Tokio and starting zgui do not conflict, in either order.
Use an existing runtime
If the process already owns a runtime, pass its handle to install_handle:
let runtime = tokio::runtime::Runtime::new()?;
let _tokio = zgui::tokio::install_handle(runtime.handle().clone())?;The guard does not own this runtime and does not shut it down; keep the runtime alive yourself.
The background executor is process-wide, but the runtime context for UI tasks is per thread. A
program with a second, independent UI thread calls enter_here on that thread, after it installs
its reactive runtime and before its first frame:
zgui::tokio::enter_here(runtime.handle().clone());Do not install a second background executor.
Connect Tokio channels to signals
tokio::sync channels (mpsc, watch, broadcast, oneshot) work in UI tasks without calling
install. The helpers in zgui::tokio drive a receiver in a scoped UI task and call your closure
on the UI thread. Each stops when its scope is disposed.
mpsc
let task = zgui::tokio::spawn_receiver(receiver, move |message| {
messages.update(|items| items.push(message));
});The task ends when every sender is dropped.
watch
let status = zgui::tokio::watch_signal(status_receiver);watch_signal returns a ReadSignal that starts at the channel's current value and follows every
change. For a callback instead of a signal, use spawn_watch. It is called first with the current
value, then on every change:
zgui::tokio::spawn_watch(receiver, move |value| {
apply_status(value);
});broadcast
zgui::tokio::spawn_broadcast(receiver, move |event| {
latest.set(Some(event));
});If the receiver lags, Tokio drops old messages. zgui logs how many were missed at warn level and
continues from the oldest message still held. The task ends when the channel closes.
zgui::tokio functions
pub fn install() -> Result<Installed, zgui::tokio::Error>;
pub fn install_handle(handle: tokio::runtime::Handle) -> Result<Installed, zgui::tokio::Error>;
pub fn enter_here(handle: tokio::runtime::Handle);
impl Installed {
pub fn handle(&self) -> tokio::runtime::Handle;
}