Skip to content

Commit 94e8fa9

Browse files
mockersfItsDoot
authored andcommitted
document the single threaded wasm task pool (bevyengine#4571)
# Objective - The single threaded task pool is not documented - This doesn't warn in CI as it's feature gated for wasm, but I'm tired of seeing the warnings when building in wasm ## Solution - Document it
1 parent 0950aae commit 94e8fa9

File tree

1 file changed

+30
-10
lines changed

1 file changed

+30
-10
lines changed

crates/bevy_tasks/src/single_threaded_task_pool.rs

Lines changed: 30 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -14,18 +14,22 @@ impl TaskPoolBuilder {
1414
Self::default()
1515
}
1616

17+
/// No op on the single threaded task pool
1718
pub fn num_threads(self, _num_threads: usize) -> Self {
1819
self
1920
}
2021

22+
/// No op on the single threaded task pool
2123
pub fn stack_size(self, _stack_size: usize) -> Self {
2224
self
2325
}
2426

27+
/// No op on the single threaded task pool
2528
pub fn thread_name(self, _thread_name: String) -> Self {
2629
self
2730
}
2831

32+
/// Creates a new [`TaskPool`]
2933
pub fn build(self) -> TaskPool {
3034
TaskPool::new_internal()
3135
}
@@ -83,16 +87,15 @@ impl TaskPool {
8387
.collect()
8488
}
8589

86-
// Spawns a static future onto the JS event loop. For now it is returning FakeTask
87-
// instance with no-op detach method. Returning real Task is possible here, but tricky:
88-
// future is running on JS event loop, Task is running on async_executor::LocalExecutor
89-
// so some proxy future is needed. Moreover currently we don't have long-living
90-
// LocalExecutor here (above `spawn` implementation creates temporary one)
91-
// But for typical use cases it seems that current implementation should be sufficient:
92-
// caller can spawn long-running future writing results to some channel / event queue
93-
// and simply call detach on returned Task (like AssetServer does) - spawned future
94-
// can write results to some channel / event queue.
95-
90+
/// Spawns a static future onto the JS event loop. For now it is returning FakeTask
91+
/// instance with no-op detach method. Returning real Task is possible here, but tricky:
92+
/// future is running on JS event loop, Task is running on async_executor::LocalExecutor
93+
/// so some proxy future is needed. Moreover currently we don't have long-living
94+
/// LocalExecutor here (above `spawn` implementation creates temporary one)
95+
/// But for typical use cases it seems that current implementation should be sufficient:
96+
/// caller can spawn long-running future writing results to some channel / event queue
97+
/// and simply call detach on returned Task (like AssetServer does) - spawned future
98+
/// can write results to some channel / event queue.
9699
pub fn spawn<T>(&self, future: impl Future<Output = T> + 'static) -> FakeTask
97100
where
98101
T: 'static,
@@ -103,6 +106,7 @@ impl TaskPool {
103106
FakeTask
104107
}
105108

109+
/// Spawns a static future on the JS event loop. This is exactly the same as [`TaskSpool::spawn`].
106110
pub fn spawn_local<T>(&self, future: impl Future<Output = T> + 'static) -> FakeTask
107111
where
108112
T: 'static,
@@ -115,9 +119,13 @@ impl TaskPool {
115119
pub struct FakeTask;
116120

117121
impl FakeTask {
122+
/// No op on the single threaded task pool
118123
pub fn detach(self) {}
119124
}
120125

126+
/// A `TaskPool` scope for running one or more non-`'static` futures.
127+
///
128+
/// For more information, see [`TaskPool::scope`].
121129
#[derive(Debug)]
122130
pub struct Scope<'scope, T> {
123131
executor: &'scope async_executor::LocalExecutor<'scope>,
@@ -126,10 +134,22 @@ pub struct Scope<'scope, T> {
126134
}
127135

128136
impl<'scope, T: Send + 'scope> Scope<'scope, T> {
137+
/// Spawns a scoped future onto the thread-local executor. The scope *must* outlive
138+
/// the provided future. The results of the future will be returned as a part of
139+
/// [`TaskPool::scope`]'s return value.
140+
///
141+
/// On the single threaded task pool, it just calls [`Scope::spawn_local`].
142+
///
143+
/// For more information, see [`TaskPool::scope`].
129144
pub fn spawn<Fut: Future<Output = T> + 'scope + Send>(&mut self, f: Fut) {
130145
self.spawn_local(f);
131146
}
132147

148+
/// Spawns a scoped future onto the thread-local executor. The scope *must* outlive
149+
/// the provided future. The results of the future will be returned as a part of
150+
/// [`TaskPool::scope`]'s return value.
151+
///
152+
/// For more information, see [`TaskPool::scope`].
133153
pub fn spawn_local<Fut: Future<Output = T> + 'scope>(&mut self, f: Fut) {
134154
let result = Arc::new(Mutex::new(None));
135155
self.results.push(result.clone());

0 commit comments

Comments
 (0)