diff --git a/crates/tokio-nursery/src/lib.rs b/crates/tokio-nursery/src/lib.rs index d2516ba..ba17fc7 100644 --- a/crates/tokio-nursery/src/lib.rs +++ b/crates/tokio-nursery/src/lib.rs @@ -4,19 +4,31 @@ use std::pin::Pin; use std::task::{ready, Context, Poll}; use tokio::sync::mpsc::{unbounded_channel, UnboundedReceiver, UnboundedSender}; +/// Type returned by [`FutureExt::catch_unwind()`]. If the inner task ran to +/// completion, this is `Ok`; otherwise, if the taks panicked, this is `Err`. type UnwindResult = Result>; +/// A handle for spawning new tasks in a task group/nursery. +/// +/// `Nursery` is cloneable and sendable, and so it can be used to spawn tasks +/// from inside other tasks in the nursery. The nursery returned by +/// [`Nursery::new()`] and all clones thereof must be dropped before the +/// corresponding [`NurseryStream`] can yield `None`. #[derive(Debug)] pub struct Nursery { sender: UnboundedSender>, } impl Nursery { + /// Create a new nursery and return a handle for spawning tasks and a + /// [`Stream`] of task return values. `T` is the `Output` type of the + /// futures that will be spawned in the nursery. pub fn new() -> (Nursery, NurseryStream) { let (sender, receiver) = unbounded_channel(); (Nursery { sender }, NurseryStream { receiver }) } + /// Spawn a future that returns `T` in the nursery. pub fn spawn(&self, fut: Fut) where Fut: Future + Send + 'static, @@ -39,6 +51,10 @@ impl Clone for Nursery { } } +/// A [`Stream`] of the values returned by the tasks spawned in a nursery. +/// +/// The corresponding [`Nursery`] and all clones thereof must be dropped before +/// the stream can yield `None`. #[derive(Debug)] pub struct NurseryStream { receiver: UnboundedReceiver>,