Event based trigger introduced

Added a new mechanism to emit "state changed" events that can "wake up" a tree.
In short, it just provide an interruptible "sleep" function.

Author: facontidavide

docs/index.md

@@ -23,7 +23,7 @@ to visualize, record, replay and analyze state transitions.
 ## Community
 
 If this documentation doesn't answer your questions or if you simply want to
-connect with the community of BT.CPP users, visit https://discourse.behaviortree.dev/
+connect with the community of BT.CPP users, visit [discourse.behaviortree.dev](https://discourse.behaviortree.dev/).
 
 ## What is a Behavior Tree?
 

docs/tutorial_04_sequence.md

@@ -63,11 +63,11 @@ NodeStatus MoveBaseAction::tick()
     int count = 0;
 
     // Pretend that "computing" takes 250 milliseconds.
-    // It is up to you to check periodicall _halt_requested and interrupt
+    // It is up to you to check periodically _halt_requested and interrupt
     // this tick() if it is true.
     while (!_halt_requested && count++ < 25)
     {
-        SleepMS(10);
+        std::this_thread::sleep_for( std::chrono::milliseconds(10) );
     }
 
     std::cout << "[ MoveBase: FINISHED ]" << std::endl;
@@ -105,6 +105,7 @@ The following example should use a simple `SequenceNode`.
 int main()
 {
     using namespace DummyNodes;
+    using std::chrono::milliseconds;
 
     BehaviorTreeFactory factory;
     factory.registerSimpleCondition("BatteryOK", std::bind(CheckBattery));
@@ -118,11 +119,11 @@ int main()
     std::cout << "\n--- 1st executeTick() ---" << std::endl;
     status = tree.tickRoot();
 
-    SleepMS(150);
+    tree.sleep( milliseconds(150) );
     std::cout << "\n--- 2nd executeTick() ---" << std::endl;
     status = tree.tickRoot();
 
-    SleepMS(150);
+    tree.sleep( milliseconds(150) );
     std::cout << "\n--- 3rd executeTick() ---" << std::endl;
     status = tree.tickRoot();
 
@@ -191,5 +192,15 @@ Expected output:
     Robot says: "mission completed!"
 ```
 
+## Event Driven trees?
+
+!!! important 
+    We used the command `tree.sleep()` instead of `std::this_thread::sleep_for()` for a reason.
+    
+The method `Tree::sleep()` should be preferred, because it can be interrupted by a Node in the tree when
+"something changed".
+Tree::sleep() will be interrupted when an `AsyncActionNode::tick()` is completed or, more generally,
+when the method `TreeNode::emitStateChanged()` is invoked.
+
 
 

docs/tutorial_05_subtrees.md

@@ -110,9 +110,16 @@ int main()
         while( status == NodeStatus::RUNNING)
         {
             status = tree.tickRoot();
-            CrossDoor::SleepMS(1);   // optional sleep to avoid "busy loops"
+            // IMPORTANT: you must always add some sleep if you call tickRoot()
+            // in a loop, to avoid using 100% of your CPU (busy loop).
+            // The method Tree::sleep() is recommended, because it can be
+            // interrupted by an internal event inside the tree.
+            tree.sleep( milliseconds(10) );
+        }
+        if( LOOP )
+        {
+            std::this_thread::sleep_for( milliseconds(1000) );
         }
-        CrossDoor::SleepMS(2000);
     }
     return 0;
 }

docs/tutorial_06_subtree_ports.md

@@ -78,7 +78,9 @@ int main()
     while( status == NodeStatus::RUNNING)
     {
         status = tree.tickRoot();
-        SleepMS(1);   // optional sleep to avoid "busy loops"
+        // IMPORTANT: add sleep to avoid busy loops.
+        // You should use Tree::sleep(). Don't be afraid to run this at 1 KHz.
+        tree.sleep( std::chrono::milliseconds(1) );
     }
 
     // let's visualize some information about the current state of the blackboards.

docs/tutorial_09_coroutines.md

@@ -147,10 +147,10 @@ int main()
     auto tree = factory.createTreeFromText(xml_text);
 
     //---------------------------------------
-    // keep executin tick until it returns etiher SUCCESS or FAILURE
+    // keep executing tick until it returns either SUCCESS or FAILURE
     while( tree.tickRoot() == NodeStatus::RUNNING)
     {
-        std::this_thread::sleep_for( Milliseconds(10) );
+        tree.sleep( std::chrono::milliseconds(10) );
     }
     return 0;
 }

examples/t04_reactive_sequence.cpp

@@ -57,9 +57,11 @@ void Assert(bool condition)
         throw RuntimeError("this is not what I expected");
 }
 
+
 int main()
 {
     using namespace DummyNodes;
+    using std::chrono::milliseconds;
 
     BehaviorTreeFactory factory;
     factory.registerSimpleCondition("BatteryOK", std::bind(CheckBattery));
@@ -85,12 +87,12 @@ int main()
         status = tree.tickRoot();
         Assert(status == NodeStatus::RUNNING);
 
-        SleepMS(150);
+        tree.sleep( milliseconds(150) );
         std::cout << "\n--- 2nd executeTick() ---" << std::endl;
         status = tree.tickRoot();
         Assert(status == NodeStatus::RUNNING);
 
-        SleepMS(150);
+        tree.sleep( milliseconds(150) );
         std::cout << "\n--- 3rd executeTick() ---" << std::endl;
         status = tree.tickRoot();
         Assert(status == NodeStatus::SUCCESS);

examples/t05_crossdoor.cpp

@@ -85,16 +85,24 @@ int main(int argc, char** argv)
 
     const bool LOOP = ( argc == 2 && strcmp( argv[1], "loop") == 0);
 
+    using std::chrono::milliseconds;
     do
     {
         NodeStatus status = NodeStatus::RUNNING;
         // Keep on ticking until you get either a SUCCESS or FAILURE state
         while( status == NodeStatus::RUNNING)
         {
             status = tree.tickRoot();
-            CrossDoor::SleepMS(1);   // optional sleep to avoid "busy loops"
+            // IMPORTANT: you must always add some sleep if you call tickRoot()
+            // in a loop, to avoid using 100% of your CPU (busy loop).
+            // The method Tree::sleep() is recommended, because it can be
+            // interrupted by an internal event inside the tree.
+            tree.sleep( milliseconds(10) );
+        }
+        if( LOOP )
+        {
+            std::this_thread::sleep_for( milliseconds(1000) );
         }
-        CrossDoor::SleepMS(1000);
     }
     while(LOOP);
 

examples/t06_subtree_port_remapping.cpp

@@ -68,7 +68,9 @@ int main()
     while( status == NodeStatus::RUNNING)
     {
         status = tree.tickRoot();
-        SleepMS(1);   // optional sleep to avoid "busy loops"
+        // IMPORTANT: add sleep to avoid busy loops.
+        // You should use Tree::sleep(). Don't be afraid to run this at 1 KHz.
+        tree.sleep( std::chrono::milliseconds(1) );
     }
 
     // let's visualize some information about the current state of the blackboards.

examples/t09_async_actions_coroutines.cpp

@@ -115,10 +115,10 @@ int main()
     auto tree = factory.createTreeFromText(xml_text);
 
     //---------------------------------------
-    // keep executin tick until it returns etiher SUCCESS or FAILURE
+    // keep executing tick until it returns either SUCCESS or FAILURE
     while( tree.tickRoot() == NodeStatus::RUNNING)
     {
-        std::this_thread::sleep_for( std::chrono::milliseconds(10) );
+        tree.sleep( std::chrono::milliseconds(10) );
     }
     return 0;
 }

include/behaviortree_cpp_v3/action_node.h

@@ -113,6 +113,9 @@ class SimpleActionNode : public SyncActionNode
  * - remember, with few exceptions, a halted AsyncAction must return NodeStatus::IDLE.
  *
  * For a complete example, look at __AsyncActionTest__ in action_test_node.h in the folder test.
+ *
+ * NOTE: when the thread is completed, i.e. the tick() returns its status,
+ * a TreeNode::emitStateChanged() will be called.
  */
 class AsyncActionNode : public ActionNodeBase
 {
@@ -136,7 +139,7 @@ class AsyncActionNode : public ActionNodeBase
 
     std::exception_ptr exptr_;
     std::atomic_bool halt_requested_;
-    std::future<NodeStatus> thread_handle_;
+    std::future<void> thread_handle_;
     std::mutex m_;
 };