1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.
//! Keep work on its worker, or move worker-aware values explicitly.
//!
//! A task stays on one worker while it runs. Its
//! [`Builtins`](crate::task::Builtins) provides a scheduler, clock, and telemetry
//! sink associated with that worker.
//!
//! # Keep work on the same worker
//!
//! Cloning a scheduler keeps its worker association. This example uses the
//! clone from a blocking thread to submit work back to the original worker:
//!
//! ```
//! use arty::task::Builtins;
//!
//! # #[arty::main]
//! # async fn main(cx: Builtins) -> Result<(), arty::task::JoinError> {
//! let home = cx.thread().id();
//! let executed_on = cx
//! .scheduler()
//! .spawn_blocking({
//! let scheduler = cx.scheduler().clone();
//! move || scheduler.spawn(async |child| child.thread().id())
//! })
//! .await?
//! .await?;
//! assert_eq!(executed_on, home);
//! # Ok(())
//! # }
//! ```
//!
//! # Let the runtime place new work
//!
//! [`Scheduler::spawn_anywhere`](crate::task::Scheduler::spawn_anywhere)
//! lets the runtime choose a worker for a new task. Pass a
//! [`ThreadAware`](crate::core::ThreadAware) value explicitly; Arty relocates it
//! to the chosen worker before the task uses it:
//!
//! ```
//! use arty::task::{Builtins, JoinError};
//!
//! # #[arty::main]
//! # async fn main(cx: Builtins) -> Result<(), JoinError> {
//! let (worker, scheduler) = cx
//! .scheduler()
//! .spawn_anywhere(cx.clone(), |moved| async move {
//! assert_eq!(moved.thread().id(), std::thread::current().id());
//! (moved.thread().clone(), moved.scheduler().clone())
//! })
//! .await?;
//! let child = scheduler.spawn(async |child| child.thread().id()).await?;
//! assert_eq!(child, worker.id());
//! # Ok(())
//! # }
//! ```
//!
//! The runtime may choose the original worker. If a task only needs its own
//! services, use the `Builtins` passed to its factory instead of moving an
//! existing value.
//!
//! # What stays put
//!
//! `spawn_anywhere` starts a new task; it never moves a running one. Simply
//! moving or cloning `Builtins` does not change its worker association.
//! Scheduler handles and worker coordinates do not keep the runtime alive.
//!
//! Ordinary `spawn` and `block_on` do not relocate captures or returned values.
//! `spawn_anywhere` relocates its explicit payload, but not its result.
//!
//! `ThreadAware` builds on `Send`: values must remain safe to move even without
//! relocation. See the [`ThreadAware` contract](crate::core::ThreadAware) when
//! implementing it for your own types.