Skip to content

Commit 4b5409e

Browse files
mariusaemeta-codesync[bot]
authored andcommitted
document pytokio (#1712)
Summary: Pull Request resolved: #1712 We keep getting questions about how this works. This is an attempt to document it in simple terms. ghstack-source-id: 319936663 exported-using-ghexport Reviewed By: vidhyav, zdevito Differential Revision: D85870468 fbshipit-source-id: 327d87b087e47a17da0eb07da2e6a412155773f0
1 parent a6d1eb1 commit 4b5409e

File tree

1 file changed

+32
-0
lines changed

1 file changed

+32
-0
lines changed

monarch_hyperactor/src/pytokio.rs

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,38 @@
66
* LICENSE file in the root directory of this source tree.
77
*/
88

9+
/// Pytokio allows Python coroutines to await Rust futures, in specific contexts.
10+
///
11+
/// A PythonTask is constructed in Python from `PythonTask.from_coroutine()`:
12+
///
13+
/// ```ignore
14+
/// async def task():
15+
/// # ... async work, await other python tasks
16+
/// task = PythonTask.from_coroutine(coro=task())
17+
/// ```
18+
///
19+
/// The task may only await *other* PythonTasks; it is an error to await arbitrary
20+
/// Python awaitables. In this way, Pytokio is a way to use Python to compose Tokio futures.
21+
///
22+
/// A task can be spawned in order to produce an awaitable that can be awaited in
23+
/// any async context:
24+
///
25+
/// ```ignore
26+
/// shared = task.spawn()
27+
/// result = await shared
28+
/// ```
29+
///
30+
/// Spawn spawns a tokio task that drives the coroutine to completion, and, using the Python
31+
/// awaitable protocol, allows those coroutines to await other Tokio futures in turn.
32+
///
33+
/// PythonTasks can also be awaited synchronously by `block_on`:
34+
///
35+
/// ```ignore
36+
/// result = task.block_on()
37+
/// ```
38+
///
39+
/// This allows PythonTasks to be used in either async or sync contexts -- the underlying
40+
/// code executes in exactly the same way, driven by an underlying tokio task.
941
use std::error::Error;
1042
use std::future::Future;
1143
use std::pin::Pin;

0 commit comments

Comments
 (0)