race and short circuit on first completion (#51)

Thanks for your work on this crate, I've been loving using it for
robotics recently!

I recently was trying to make a timeout behavior and realized that:
- WhenAny - races children in parallel but short-circuits on first
Success (ignores failures until all fail)
- WhenAll - races children in parallel but short-circuits on first
Failure
- No node short-circuits on first completion regardless of
success/failure

I think it would be helpful to have a node that runs things in parallel
and take the result of whichever finishes first so you can do stuff like
this:

```rust
/// fails if the behavior doesnt finish before the timer is up.
fn with_timeout<A: Clone>(behavior: Behavior<A>, timeout: f64) -> Behavior<A> {
    Race(vec![
        behavior,
        Invert(Box::new(Wait(timeout))),
    ])
}
```

You can achieve a similar thing with a while loop but the caveat is that
if the inner behavior suceeds before the timer is up itll restart.

Of course ways to use the blackboard to do timeouts without adding a new
node but I think this one might be helpful.

Author: matthewashton-k

.github/workflows/rust-pr.yml

@@ -13,9 +13,9 @@ jobs:
     steps:
       - name: Install libudev
         run: sudo apt-get update && sudo apt-get install libudev-dev pkg-config librust-alsa-sys-dev
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
-      - uses: pre-commit/action@v2.0.3
+      - uses: actions/checkout@v6.0.2
+      - uses: actions/setup-python@v6.2.0
+      - uses: pre-commit/action@v3.0.1
   build:
     runs-on: ubuntu-latest
     steps:

README.md

@@ -55,6 +55,7 @@ For example, if you have a state `A` and a state `B`:
 - Do `A`, `B` repeatedly while `LoopCondition` runs: `WhileAll(LoopCondition, [A, B])`. After *All* nodes `A`, `B` are completed successfully, check the condition node.
 - Run `A` and `B` in parallell and wait for both to succeed: `WhenAll([A, B])`
 - Run `A` and `B` in parallell and wait for any to succeed: `WhenAny([A, B])`
+- Run `A` and `B` in parallell and wait for any to complete regardless of success or failure: `Race([A, B])`
 - Run `A` and `B` in parallell, but `A` has to succeed before `B`: `After([A, B])`
 
 See the `Behavior` enum for more information.

bonsai/Cargo.toml

@@ -12,7 +12,7 @@ name = "bonsai-bt"
 readme = "../README.md"
 repository = "https://github.com/sollimann/bonsai.git"
 rust-version = "1.80.0"
-version = "0.10.0"
+version = "0.11.0"
 
 [lib]
 name = "bonsai_bt"

bonsai/src/behavior.rs

@@ -128,6 +128,12 @@ pub enum Behavior<A> {
     /// Succeeds if all behaviors succeed, but only if succeeding in sequence.
     /// Fails if one behavior fails.
     After(Vec<Behavior<A>>),
+    /// Runs all behaviors in parallel until one completes (succeeds or fails).
+    ///
+    /// Returns the status of the first behavior to complete,
+    /// whether that is `Success` or `Failure`.
+    /// If all behaviors remain `Running`, returns `Running`.
+    Race(Vec<Behavior<A>>),
 }
 
 #[cfg(test)]

bonsai/src/lib.rs

@@ -24,6 +24,7 @@
 //! - Do `A`, `B` forever: `While(WaitForever, [A, B])`
 //! - Run `A` and `B` in parallell and wait for both to succeed: `WhenAll([A, B])`
 //! - Run `A` and `B` in parallell and wait for any to succeed: `WhenAny([A, B])`
+//! - Run `A` and `B` in parallell and wait for any to complete regardless of success or failure: `Race([A, B])`
 //! - Run `A` and `B` in parallell, but `A` has to succeed before `B`: `After([A, B])`
 //!
 //! See the `Behavior` enum for more information.
@@ -118,7 +119,7 @@
 //! ```
 
 pub use behavior::Behavior::{
-    self, Action, After, AlwaysSucceed, If, Invert, Select, Sequence, Wait, WaitForever, WhenAll, WhenAny, While,
+    self, Action, After, AlwaysSucceed, If, Invert, Race, Select, Sequence, Wait, WaitForever, WhenAll, WhenAny, While,
     WhileAll,
 };
 

bonsai/src/state.rs

@@ -102,6 +102,8 @@ pub(crate) enum State<A> {
     /// Keeps track of a `WhenAny` behavior. As the states finish, they are set
     /// to [`None`].
     WhenAny(Vec<Option<State<A>>>),
+    /// Keeps track of a `Race` behavior.
+    Race(Vec<Option<State<A>>>),
     /// Keeps track of an `After` behavior.
     After {
         /// The index of the next state that must succeed.
@@ -166,6 +168,7 @@ impl<A: Clone> State<A> {
             }
             Behavior::WhenAll(all) => State::WhenAll(all.into_iter().map(|ev| Some(State::new(ev))).collect()),
             Behavior::WhenAny(any) => State::WhenAny(any.into_iter().map(|ev| Some(State::new(ev))).collect()),
+            Behavior::Race(behaviors) => State::Race(behaviors.into_iter().map(|ev| Some(State::new(ev))).collect()),
             Behavior::After(after_all) => State::After {
                 next_success_index: 0,
                 states: after_all.into_iter().map(State::new).collect(),
@@ -404,6 +407,20 @@ impl<A: Clone> State<A> {
                 let any = true;
                 when_all(any, upd, cursors, e, f, blackboard)
             }
+            (_, &mut Race(ref mut cursors)) => {
+                // return the result of the first child to complete,
+                // regardless of whether it succeeds or fails.
+                for cur in cursors.iter_mut() {
+                    match *cur {
+                        None => {}
+                        Some(ref mut state) => match state.tick(e, blackboard, f) {
+                            (Running, _) => continue,
+                            (status, dt) => return (status, dt),
+                        },
+                    }
+                }
+                RUNNING
+            }
             (
                 _,
                 &mut After {

bonsai/src/visualizer.rs

@@ -19,6 +19,7 @@ pub(crate) enum NodeType<A> {
     WhenAll,
     WhenAny,
     After,
+    Race,
 }
 
 impl<A: Clone + Debug, K: Debug> BT<A, K> {
@@ -125,6 +126,13 @@ impl<A: Clone + Debug, K: Debug> BT<A, K> {
                     Self::dfs_recursive(graph, b, node_id)
                 }
             }
+            Behavior::Race(behaviors) => {
+                let node_id = graph.add_node(NodeType::Race);
+                graph.add_edge(parent_node, node_id, 1);
+                for b in behaviors {
+                    Self::dfs_recursive(graph, b, node_id)
+                }
+            }
         }
     }
 }

bonsai/src/when_all.rs

@@ -55,6 +55,7 @@ where
         terminated += 1;
         *cur = None;
     }
+    #[allow(clippy::manual_unwrap_or)]
     match terminated {
         // If there are no events, there is a whole 'dt' left.
         0 if cursors.is_empty() => (

bonsai/tests/behavior_tests.rs

@@ -1,7 +1,7 @@
 use crate::behavior_tests::TestActions::{Dec, Inc, LessThan, LessThanRunningSuccess};
 use bonsai_bt::{
-    Action, ActionArgs, After, AlwaysSucceed, Event, Failure, Float, If, Invert, Select, Sequence, Status::Running,
-    Success, UpdateArgs, Wait, WaitForever, WhenAll, While, WhileAll, BT,
+    Action, ActionArgs, After, AlwaysSucceed, Event, Failure, Float, If, Invert, Race, Select, Sequence,
+    Status::Running, Success, UpdateArgs, Wait, WaitForever, WhenAll, WhenAny, While, WhileAll, BT,
 };
 
 /// Some test actions.
@@ -610,3 +610,95 @@ fn test_repeat_sequence_empty() {
     // panics because no behaviors...
     let _state = BT::new(after, ());
 }
+
+#[test]
+fn race_returns_first_success() {
+    let a: i32 = 0;
+    // Inc succeeds immediately, Wait is still running
+    let behavior = Race(vec![Action(Inc), Wait(10.0)]);
+    let mut state = BT::new(behavior, ());
+    let (a, s, _) = tick(a, 0.1, &mut state);
+    assert_eq!(a, 1);
+    assert_eq!(s, Success);
+}
+
+#[test]
+fn race_returns_first_failure() {
+    let a: i32 = 5;
+    // LessThan(1) fails immediately since 5 >= 1, Wait is still running
+    let behavior = Race(vec![Action(LessThan(1)), Wait(10.0)]);
+    let mut state = BT::new(behavior, ());
+    let (a, s, _) = tick(a, 0.1, &mut state);
+    assert_eq!(a, 5);
+    assert_eq!(s, Failure);
+}
+
+#[test]
+fn race_running_until_first_completes() {
+    let a: i32 = 0;
+    // Both children are time-based, neither completes on first tick
+    let behavior = Race(vec![Wait(1.0), Wait(2.0)]);
+    let mut state = BT::new(behavior, ());
+
+    // After 0.5s, both still running
+    let (_a, s, _) = tick(a, 0.5, &mut state);
+    assert_eq!(s, Running);
+
+    // After another 0.5s (total 1.0s), first Wait completes with Success
+    let (_a, s, _) = tick(_a, 0.5, &mut state);
+    assert_eq!(s, Success);
+}
+
+#[test]
+fn race_second_child_wins_if_first_is_running() {
+    let a: i32 = 0;
+    let behavior = Race(vec![WaitForever, Action(Inc)]);
+    let mut state = BT::new(behavior, ());
+    let (a, s, _) = tick(a, 0.1, &mut state);
+    assert_eq!(a, 1);
+    assert_eq!(s, Success);
+}
+
+#[test]
+fn race_failure_short_circuits_unlike_when_any() {
+    // the main difference from WhenAny:
+    // WhenAny would swallow the failure and keep running.
+    // Race returns the failure immediately.
+    let a: i32 = 5;
+    // LessThan(1) fails immediately (5 >= 1), Wait(10.0) is still running
+    let behavior = Race(vec![Action(LessThan(1)), Wait(10.0)]);
+    let mut state = BT::new(behavior, ());
+    let (a, s, _) = tick(a, 0.1, &mut state);
+    assert_eq!(s, Failure);
+
+    // for WhenAny: same children, but failure is swallowed
+    let behavior_any = WhenAny(vec![Action(LessThan(1)), Wait(10.0)]);
+    let mut state_any = BT::new(behavior_any, ());
+    let (_, s_any, _) = tick(a, 0.1, &mut state_any);
+    assert_eq!(s_any, Running);
+}
+
+#[test]
+fn race_timeout_pattern() {
+    let a: i32 = 0;
+    // Simulate a "slow action" using WaitForever with a 1-second timeout.
+    // The timeout (Wait) fires first.
+    let behavior = Race(vec![WaitForever, Wait(1.0)]);
+    let mut state = BT::new(behavior, ());
+
+    let (_, s, _) = tick(a, 0.5, &mut state);
+    assert_eq!(s, Running);
+
+    let (_, s, _) = tick(a, 0.5, &mut state);
+    assert_eq!(s, Success);
+}
+
+#[test]
+fn race_empty() {
+    let a: i32 = 0;
+    let behavior = Race(vec![]);
+    let mut state = BT::new(behavior, ());
+    let (_, s, _) = tick(a, 0.1, &mut state);
+    // No children means nothing can complete, stays Running
+    assert_eq!(s, Running);
+}

docs/concepts/README.md

@@ -56,6 +56,7 @@ For example, if you have a state `A` and a state `B`:
 - Do `A`, `B` forever: `While(WaitForever, [A, B])`
 - Run `A` and `B` in parallel and wait for both to succeed: `WhenAll([A, B])`
 - Run `A` and `B` in parallel and wait for any to succeed: `WhenAny([A, B])`
+- Run `A` and `B` in parallell and wait for any to complete regardless of success or failure: `Race([A, B])`
 - Run `A` and `B` in parallel, but `A` has to succeed before `B`: `After([A, B])`
 
 See the `Behavior` enum for more information.