Add service discovery and spruce up documentation

Signed-off-by: Michael X. Grey <grey@openrobotics.org>

Author: mxgrey

src/chain.rs

@@ -36,23 +36,12 @@ pub use fork_clone_builder::*;
 pub mod unzip;
 pub use unzip::*;
 
-/// After submitting a service request, use [`Chain`] to describe how
-/// the response should be handled. At a minimum, for the response to be
-/// delivered, you must choose one of:
-/// - `.detach()`: Let the service run to completion and then discard the
-///   response data.
-/// - `.take()`: As long as the [`Promise`] or one of its clones is alive,
-///   the service will continue running to completion and you will be able to
-///   view the response (or take the response, but only once). If all clones of
-///   the [`Promise`] are dropped before the service is delivered, it will
-///   be cancelled.
-/// - `.detach_and_take()`: As long as the [`Promise`] or one of its clones is
-///   alive, you will be able to view the response (or take the response, but
-///   only once). The service will run to completion even if every clone of the
-///   [`Promise`] is dropped.
+/// Chain operations onto the output of a workflow node.
 ///
-/// If you do not select one of the above then the service request will be
-/// cancelled without ever attempting to run.
+/// Make sure to use [`Self::connect`] when you're done chaining so that the
+/// final output of the chain gets connected into another node. If the final
+/// output of the chain is meant to be the final output of your workflow then
+/// you should connect it to [`Scope::terminate`].
 #[must_use]
 pub struct Chain<'w, 's, 'a, 'b, T> {
     target: Entity,
@@ -65,10 +54,8 @@ impl<'w, 's, 'a, 'b, T: 'static + Send + Sync> Chain<'w, 's, 'a, 'b, T> {
     /// use this to resume building this chain later.
     ///
     /// Note that if you do not connect some path of your workflow into the
-    /// `terminate` slot of your [`Scope`][1] then the workflow will not be able
+    /// `terminate` slot of your [`Scope`] then the workflow will not be able
     /// to run.
-    ///
-    /// [1]: crate::Scope
     #[must_use]
     pub fn output(self) -> Output<T> {
         Output::new(self.scope(), self.target)
@@ -410,7 +397,7 @@ impl<'w, 's, 'a, 'b, T: 'static + Send + Sync> Chain<'w, 's, 'a, 'b, T> {
     ///
     /// As the name suggests, a no-op will not actually do anything, but it adds
     /// a new link (entity) into the chain.
-    /// [1]: https://en.wikipedia.org/wiki/NOP_(code)
+    /// [1]: `<https://en.wikipedia.org/wiki/NOP_(code)>`
     #[must_use]
     pub fn noop(self) -> Chain<'w, 's, 'a, 'b, T> {
         let source = self.target;
@@ -746,7 +733,7 @@ mod tests {
         );
 
         context.run_with_conditions(&mut promise, Duration::from_secs(2));
-        assert!(promise.peek().available().is_some_and(|value| *value == 6.0));
+        assert!(promise.take().available().is_some_and(|value| value == 6.0));
         assert!(context.no_unhandled_errors());
     }
 
@@ -806,7 +793,7 @@ mod tests {
             .with_update_count(100),
         );
 
-        assert_eq!(promise.peek().available().copied(), Some(16.0));
+        assert_eq!(promise.take().available(), Some(16.0));
         assert!(context.no_unhandled_errors());
     }
 
@@ -850,7 +837,7 @@ mod tests {
         });
 
         context.run_while_pending(&mut promise);
-        assert_eq!(promise.peek().available().copied(), Some(15.0));
+        assert_eq!(promise.take().available(), Some(15.0));
         assert!(context.no_unhandled_errors());
     }
 
@@ -943,7 +930,7 @@ mod tests {
         });
 
         context.run_with_conditions(&mut promise, Duration::from_secs(2));
-        assert!(promise.peek().available().is_some_and(|v| *v == 1.0));
+        assert!(promise.take().available().is_some_and(|v| v == 1.0));
         assert!(context.no_unhandled_errors());
 
         let mut promise = context.command(|commands| {
@@ -953,7 +940,7 @@ mod tests {
         });
 
         context.run_with_conditions(&mut promise, Duration::from_secs(2));
-        assert!(promise.peek().available().is_some_and(|v| *v == 5.0));
+        assert!(promise.take().available().is_some_and(|v| v == 5.0));
         assert!(context.no_unhandled_errors());
 
         let mut promise = context.command(|commands| {

src/discovery.rs

@@ -66,18 +66,19 @@ where
     Response: 'static + Send + Sync,
     Streams: StreamPack,
 {
-    /// Keep executing out the impulse chain up to here even if a downstream
+    /// Keep executing the impulse chain up to here even if a downstream
     /// dependent was dropped. If you continue building the chain from this
-    /// point then the later impulses will not be affected by this use of
-    /// detached.
+    /// point, then the later impulses will not be affected by this use of
+    /// `.detach()` and may be dropped.
     ///
     /// Downstream dependencies get dropped in the following situations:
-    /// - [`Self::take`] or [`Self::take_response`]: The promise containing the response is dropped.
-    /// - [`Self::store`], [`Self::push`], or [`Self::insert`]: The target entity of the operation is despawned.
-    /// - [`Self::send_event`]: This will never be dropped, effectively making it detached automatically.
-    /// - Not using any of the above: The dependency will immediately be dropped during a flush.
-    ///   If you do not use detach in this scenario, then the chain will be immediately dropped
-    ///   without being run at all. This will also push an error into [`UnhandledErrors`](crate::UnhandledErrors).
+    ///
+    /// | Operation                                                 | Drop condition                                        |
+    /// |-----------------------------------------------------------|-------------------------------------------------------|
+    /// | [`Self::take`] <br> [`Self::take_response`]               | The promise containing the final response is dropped. |
+    /// | [`Self::store`] <br> [`Self::push`] <br> [`Self::insert`] | The target entity of the operation is despawned.      |
+    /// | [`Self::detach`] <br> [`Self::send_event`]                | This will never be dropped                            |
+    /// | Using none of the above                                   | The impulse will immediately be dropped during a flush, so it will never be run at all. <br> This will also push an error into [`UnhandledErrors`](crate::UnhandledErrors). |
     pub fn detach(self) -> Impulse<'w, 's, 'a, Response, Streams> {
         self.commands.add(Detach { target: self.target });
         self
@@ -341,7 +342,7 @@ mod tests {
         });
 
         context.run_while_pending(&mut promise);
-        assert!(promise.peek().available().is_some_and(|v| v == "HELLO"));
+        assert!(promise.take().available().is_some_and(|v| v == "HELLO"));
         assert!(context.no_unhandled_errors());
 
         let mut promise = context.command(|commands| {
@@ -351,7 +352,7 @@ mod tests {
         });
 
         context.run_while_pending(&mut promise);
-        assert!(promise.peek().available().is_some_and(|v| v == "HELLO"));
+        assert!(promise.take().available().is_some_and(|v| v == "HELLO"));
         assert!(context.no_unhandled_errors());
 
         let mut promise = context.command(|commands| {
@@ -362,7 +363,7 @@ mod tests {
         });
 
         context.run_while_pending(&mut promise);
-        assert!(promise.peek().available().is_some_and(|v| v == "HELLO"));
+        assert!(promise.take().available().is_some_and(|v| v == "HELLO"));
         assert!(context.no_unhandled_errors());
 
         let mut promise = context.command(|commands| {
@@ -373,7 +374,7 @@ mod tests {
         });
 
         context.run_while_pending(&mut promise);
-        assert!(promise.peek().available().is_some_and(|v| v == "HELLO"));
+        assert!(promise.take().available().is_some_and(|v| v == "HELLO"));
         assert!(context.no_unhandled_errors());
     }
 
@@ -396,7 +397,7 @@ mod tests {
         });
 
         assert!(context.run_with_conditions(&mut promise, conditions.clone()));
-        assert!(promise.peek().available().is_some_and(|v| v == "hello"));
+        assert!(promise.take().available().is_some_and(|v| v == "hello"));
         assert!(context.no_unhandled_errors());
 
         let mut promise = context.command(|commands| {
@@ -406,7 +407,7 @@ mod tests {
         });
 
         assert!(context.run_with_conditions(&mut promise, conditions.clone()));
-        assert!(promise.peek().available().is_some_and(|v| v == "hello"));
+        assert!(promise.take().available().is_some_and(|v| v == "hello"));
         assert!(context.no_unhandled_errors());
 
         let mut promise = context.command(|commands| {
@@ -417,7 +418,7 @@ mod tests {
         });
 
         assert!(context.run_with_conditions(&mut promise, conditions.clone()));
-        assert!(promise.peek().available().is_some_and(|v| v == "hello"));
+        assert!(promise.take().available().is_some_and(|v| v == "hello"));
         assert!(context.no_unhandled_errors());
 
         let mut promise = context.command(|commands| {
@@ -436,7 +437,7 @@ mod tests {
         });
 
         assert!(context.run_with_conditions(&mut promise, conditions.clone()));
-        assert!(promise.peek().available().is_some_and(|v| v == "hello"));
+        assert!(promise.take().available().is_some_and(|v| v == "hello"));
         assert!(context.no_unhandled_errors());
     }
 }

src/impulse.rs

@@ -15,6 +15,49 @@
  *
 */
 
+//! `bevy_impulse` is an extension to the [Bevy](https://bevyengine.org) game
+//! engine that allows you to transform [bevy systems](https://bevyengine.org/learn/quick-start/getting-started/ecs/)
+//! into services and workflows that can be used for reactive service-oriented
+//! programming.
+//!
+//! ## Services
+//!
+//! One primitive of reactive programming is a [service](https://en.wikipedia.org/wiki/Service_(systems_architecture)).
+//! In `bevy_impulse`, a service is a bevy system that is associated with an
+//! entity and can be created using [`Commands::spawn_service`](SpawnServicesExt::spawn_service)
+//! or [`App::add_service`](AddServicesExt::add_service).
+//!
+//! When you [spawn](SpawnServicesExt::spawn_service) a service you will
+//! immediately receive a [`Service`] object which can be used to refer to it.
+//! If you do not want to hang onto the service object, you can find previously
+//! spawned services later using the [`ServiceDiscovery`] system parameter.
+//!
+//! ## Workflows
+//!
+//! For complex async workflows, a single bevy system may not be sufficient.
+//! You can instead build workflows using [`Command::spawn_workflow`](SpawnWorkflow::spawn_workflow).
+//! A workflow lets you create a graph of [nodes](Node) where each node is a
+//! service with an input, an output, and possibly streams.
+//!
+//! There are various operations that can be performed between nodes, such as
+//! forking and joining. These operations are built using [`Chain`].
+//!
+//! When you spawn your workflow, you will receive a [`Service`] object that
+//! lets you use the workflow as if it's an ordinary service.
+//!
+//! ## Impulses
+//!
+//! Services and workflows are reusable building blocks for creating a reactive
+//! application. In order to actually run them, call [`Commands::request`](RequestExt::request)
+//! which will provide you with an [`Impulse`]. An impulse is a one-time-use
+//! reaction to a request which you can chain to subsequent reactions using
+//! [`Impulse::then`]. Any impulse chain that you create will only run exactly
+//! once.
+//!
+//! Once you've finished creating your chain, use [`Impulse::detach`] to let it
+//! run freely, or use [`Impulse::take`] to receive a [`Promise`] of the final
+//! result.
+
 pub mod buffer;
 pub use buffer::*;
 
@@ -33,9 +76,6 @@ pub use chain::*;
 pub mod channel;
 pub use channel::*;
 
-pub mod discovery;
-pub use discovery::*;
-
 pub mod disposal;
 pub use disposal::*;