Merge branch 'master' into feature/remove-lexy

Author: facontidavide

.github/workflows/cmake_ubuntu.yml

@@ -99,18 +99,18 @@ jobs:
              --ignore-errors unused
         lcov --list coverage.info
 
-    - name: Upload coverage reports to Codecov
-      uses: codecov/codecov-action@v5
-      continue-on-error: true
-      with:
-        files: coverage.info
-        flags: unittests
-        disable_search: true
-        disable_file_fixes: false
-        plugins: noop
-        network_filter: >-
-          include/behaviortree_cpp/,src/
-        token: ${{ secrets.CODECOV_TOKEN }}
+    # - name: Upload coverage reports to Codecov
+    #   uses: codecov/codecov-action@v5
+    #   continue-on-error: true
+    #   with:
+    #     files: coverage.info
+    #     flags: unittests
+    #     disable_search: true
+    #     disable_file_fixes: false
+    #     plugins: noop
+    #     network_filter: >-
+    #       include/behaviortree_cpp/,src/
+    #     token: ${{ secrets.CODECOV_TOKEN }}
 
     # --- Coveralls ---
     - name: Upload to Coveralls
@@ -121,14 +121,6 @@ jobs:
         format: lcov
         github-token: ${{ secrets.GITHUB_TOKEN }}
 
-    # --- Codacy ---
-    - name: Upload to Codacy
-      uses: codacy/codacy-coverage-reporter-action@v1
-      continue-on-error: true
-      with:
-        project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
-        coverage-reports: coverage.info
-
     # --- SonarCloud ---
     - name: Run SonarCloud analysis
       uses: SonarSource/sonarcloud-github-action@v5

.gitignore

@@ -25,4 +25,9 @@ tags
 /llvm.sh
 t11_groot_howto.btlog
 minitrace.json
+
 TODO.md
+/.worktrees/*
+/docs/plans/*
+/coverage_report/*
+

README.md

@@ -3,7 +3,7 @@
 [![conan Windows](https://github.com/BehaviorTree/BehaviorTree.CPP/actions/workflows/cmake_windows.yml/badge.svg)](https://github.com/BehaviorTree/BehaviorTree.CPP/actions/workflows/cmake_windows.yml)
 [![ros2](https://github.com/BehaviorTree/BehaviorTree.CPP/actions/workflows/ros2.yaml/badge.svg)](https://github.com/BehaviorTree/BehaviorTree.CPP/actions/workflows/ros2.yaml)
 [![pixi (Conda)](https://github.com/BehaviorTree/BehaviorTree.CPP/actions/workflows/pixi.yaml/badge.svg)](https://github.com/BehaviorTree/BehaviorTree.CPP/actions/workflows/pixi.yaml)
-[![codecov](https://codecov.io/github/BehaviorTree/BehaviorTree.CPP/graph/badge.svg)](https://app.codecov.io/github/BehaviorTree/BehaviorTree.CPP)
+[![Coverage Status](https://coveralls.io/repos/github/BehaviorTree/BehaviorTree.CPP/badge.svg?branch=master)](https://coveralls.io/github/BehaviorTree/BehaviorTree.CPP?branch=master)
 
 # BehaviorTree.CPP 4.8
 

docs/pre_postconditions.md

@@ -0,0 +1,127 @@
+# Pre-conditions and Post-conditions
+
+This document describes the pre-condition and post-condition attributes that can be attached to any node in XML.
+
+## Pre-conditions
+
+Pre-conditions are evaluated **before** a node's `tick()` method is called. They can short-circuit the node execution by returning a status immediately.
+
+### Available Pre-conditions
+
+| Attribute | When Evaluated | Behavior |
+|-----------|----------------|----------|
+| `_failureIf` | IDLE only | If true, return FAILURE without calling tick() |
+| `_successIf` | IDLE only | If true, return SUCCESS without calling tick() |
+| `_skipIf` | IDLE only | If true, return SKIPPED without calling tick() |
+| `_while` | IDLE and RUNNING | If false when IDLE, return SKIPPED. If false when RUNNING, halt node and return SKIPPED |
+
+### Evaluation Order
+
+When a node has multiple pre-conditions, they are evaluated in this order:
+1. `_failureIf`
+2. `_successIf`
+3. `_skipIf`
+4. `_while`
+
+The first condition that triggers will determine the result.
+
+### Important: One-time Evaluation
+
+**`_failureIf`, `_successIf`, and `_skipIf` are evaluated only once** when the node transitions from IDLE (or SKIPPED) to another state. They are **NOT re-evaluated** while the node is RUNNING.
+
+This means if you have:
+```xml
+<MyAction _successIf="condition"/>
+```
+
+The `condition` is checked only when `MyAction` starts. If `MyAction` returns RUNNING, subsequent ticks will continue executing `MyAction` without re-checking the condition.
+
+### The `_while` Exception
+
+`_while` is the only pre-condition that is re-evaluated on every tick, even while the node is RUNNING. If the condition becomes false while the node is running, the node is halted and returns SKIPPED.
+
+```xml
+<MyAction _while="battery_ok"/>
+```
+
+If `battery_ok` becomes false while `MyAction` is running, the action is interrupted.
+
+### When to Use Each Pre-condition
+
+- **`_skipIf`**: Skip a node without failing the parent (useful in Sequences)
+- **`_failureIf`**: Fail early based on a condition (useful in Fallbacks)
+- **`_successIf`**: Succeed early based on a condition
+- **`_while`**: Guard that must remain true for the entire execution
+
+### Re-evaluating Conditions Every Tick
+
+If you need a condition to be checked on every tick (not just when transitioning from IDLE), use the `<Precondition>` decorator node instead of inline attributes:
+
+```xml
+<!-- This checks the condition on every tick while child is RUNNING -->
+<Precondition if="my_condition" else="RUNNING">
+  <MyAction/>
+</Precondition>
+```
+
+With `else="RUNNING"`, if the condition is false, the decorator returns RUNNING (keeping the tree alive) rather than SUCCESS/FAILURE/SKIPPED.
+
+## Post-conditions
+
+Post-conditions are scripts executed **after** a node completes (or is halted).
+
+### Available Post-conditions
+
+| Attribute | When Executed |
+|-----------|---------------|
+| `_onSuccess` | After node returns SUCCESS |
+| `_onFailure` | After node returns FAILURE |
+| `_onHalted` | After node is halted (including by `_while`) |
+| `_post` | After any completion (SUCCESS, FAILURE, or HALTED) |
+
+### Example
+
+```xml
+<MyAction
+    _onSuccess="result := 'ok'"
+    _onFailure="result := 'failed'"
+    _onHalted="result := 'interrupted'"/>
+```
+
+## Common Patterns
+
+### Conditional Execution in Sequence
+
+```xml
+<Sequence>
+  <CheckBattery/>
+  <MoveToGoal _skipIf="already_at_goal"/>
+  <PickObject/>
+</Sequence>
+```
+
+If `already_at_goal` is true, `MoveToGoal` is skipped and the sequence continues with `PickObject`.
+
+### Early Exit in Fallback
+
+```xml
+<Fallback>
+  <CachedResult _successIf="cache_valid"/>
+  <ComputeResult/>
+</Fallback>
+```
+
+If `cache_valid` is true, `CachedResult` succeeds immediately without executing.
+
+### Guarded Action
+
+```xml
+<MoveToGoal _while="battery_level > 20"/>
+```
+
+The movement continues only while battery is sufficient. If battery drops, the action is halted.
+
+## Related
+
+- [Port Connection Rules](PORT_CONNECTION_RULES.md) - How ports connect between nodes
+- [Name Validation Rules](name_validation_rules.md) - Valid names for ports and nodes

include/behaviortree_cpp/loggers/abstract_logger.h

@@ -15,14 +15,16 @@ enum class TimestampType
 class StatusChangeLogger
 {
 public:
+  /// Construct and immediately subscribe to status changes.
   StatusChangeLogger(TreeNode* root_node);
+
   virtual ~StatusChangeLogger() = default;
 
   StatusChangeLogger(const StatusChangeLogger& other) = delete;
   StatusChangeLogger& operator=(const StatusChangeLogger& other) = delete;
 
-  StatusChangeLogger(StatusChangeLogger&& other) = default;
-  StatusChangeLogger& operator=(StatusChangeLogger&& other) = default;
+  StatusChangeLogger(StatusChangeLogger&& other) = delete;
+  StatusChangeLogger& operator=(StatusChangeLogger&& other) = delete;
 
   virtual void callback(BT::Duration timestamp, const TreeNode& node,
                         NodeStatus prev_status, NodeStatus status) = 0;
@@ -55,6 +57,13 @@ class StatusChangeLogger
     show_transition_to_idle_ = enable;
   }
 
+protected:
+  /// Default constructor for deferred subscription. Call subscribeToTreeChanges() when ready.
+  StatusChangeLogger() = default;
+
+  /// Subscribe to status changes. Call at end of constructor for deferred subscription.
+  void subscribeToTreeChanges(TreeNode* root_node);
+
 private:
   bool enabled_ = true;
   bool show_transition_to_idle_ = true;
@@ -67,23 +76,34 @@ class StatusChangeLogger
 //--------------------------------------------
 
 inline StatusChangeLogger::StatusChangeLogger(TreeNode* root_node)
+{
+  subscribeToTreeChanges(root_node);
+}
+
+inline void StatusChangeLogger::subscribeToTreeChanges(TreeNode* root_node)
 {
   first_timestamp_ = std::chrono::high_resolution_clock::now();
 
   auto subscribeCallback = [this](TimePoint timestamp, const TreeNode& node,
                                   NodeStatus prev, NodeStatus status) {
-    std::unique_lock lk(callback_mutex_);
-    if(enabled_ && (status != NodeStatus::IDLE || show_transition_to_idle_))
+    // Copy state under lock, then release before calling user code
+    // This prevents recursive mutex locking when multiple nodes change status
+    bool should_callback = false;
+    Duration adjusted_timestamp;
     {
-      if(type_ == TimestampType::absolute)
-      {
-        this->callback(timestamp.time_since_epoch(), node, prev, status);
-      }
-      else
+      std::unique_lock lk(callback_mutex_);
+      if(enabled_ && (status != NodeStatus::IDLE || show_transition_to_idle_))
       {
-        this->callback(timestamp - first_timestamp_, node, prev, status);
+        should_callback = true;
+        adjusted_timestamp = (type_ == TimestampType::absolute) ?
+                                 timestamp.time_since_epoch() :
+                                 (timestamp - first_timestamp_);
       }
     }
+    if(should_callback)
+    {
+      this->callback(adjusted_timestamp, node, prev, status);
+    }
   };
 
   auto visitor = [this, subscribeCallback](TreeNode* node) {

include/behaviortree_cpp/loggers/bt_file_logger_v2.h

@@ -1,13 +1,12 @@
 #pragma once
 #include "behaviortree_cpp/loggers/abstract_logger.h"
 
-#include <array>
-#include <deque>
 #include <filesystem>
-#include <fstream>
+#include <memory>
 
 namespace BT
 {
+
 /**
  * @brief The FileLogger2 is a logger that saves the tree as
  * XML and all the transitions.
@@ -36,8 +35,8 @@ class FileLogger2 : public StatusChangeLogger
   FileLogger2(const FileLogger2& other) = delete;
   FileLogger2& operator=(const FileLogger2& other) = delete;
 
-  FileLogger2(FileLogger2&& other) = default;
-  FileLogger2& operator=(FileLogger2&& other) = default;
+  FileLogger2(FileLogger2&& other) = delete;
+  FileLogger2& operator=(FileLogger2&& other) = delete;
 
   virtual ~FileLogger2() override;
 
@@ -58,8 +57,8 @@ class FileLogger2 : public StatusChangeLogger
   void flush() override;
 
 private:
-  struct PImpl;
-  std::unique_ptr<PImpl> _p;
+  struct Pimpl;
+  std::unique_ptr<Pimpl> _p;
 
   void writerLoop();
 };

include/behaviortree_cpp/loggers/bt_sqlite_logger.h

@@ -100,6 +100,7 @@ class SqliteLogger : public StatusChangeLogger
 
   std::thread writer_thread_;
   std::atomic_bool loop_ = true;
+  std::atomic_bool writer_ready_ = false;
 
   ExtraCallback extra_func_;
 

include/behaviortree_cpp/tree_node.h

@@ -44,9 +44,30 @@ struct TreeNodeManifest
 using PortsRemapping = std::unordered_map<std::string, std::string>;
 using NonPortAttributes = std::unordered_map<std::string, std::string>;
 
+/**
+ * @brief Pre-conditions that can be attached to any node via XML attributes.
+ *
+ * Pre-conditions are evaluated in the order defined by this enum (FAILURE_IF first,
+ * then SUCCESS_IF, then SKIP_IF, then WHILE_TRUE).
+ *
+ * **Important**: FAILURE_IF, SUCCESS_IF, and SKIP_IF are evaluated **only once**
+ * when the node transitions from IDLE (or SKIPPED) to another state.
+ * They are NOT re-evaluated while the node is RUNNING.
+ *
+ * - `_failureIf="<script>"`: If true when node is IDLE, return FAILURE immediately (node's tick() is not called).
+ * - `_successIf="<script>"`: If true when node is IDLE, return SUCCESS immediately (node's tick() is not called).
+ * - `_skipIf="<script>"`: If true when node is IDLE, return SKIPPED immediately (node's tick() is not called).
+ * - `_while="<script>"`: Checked both on IDLE and RUNNING states.
+ *
+ *   If false when IDLE, return SKIPPED. If false when RUNNING, halt the node
+ *   and return SKIPPED. This is the only pre-condition that can interrupt
+ *   a running node.
+ *
+ * If you need a condition to be re-evaluated on every tick, use the
+ * `<Precondition>` decorator node with `else="RUNNING"` instead of these attributes.
+ */
 enum class PreCond
 {
-  // order of the enums also tell us the execution order
   FAILURE_IF = 0,
   SUCCESS_IF,
   SKIP_IF,

src/basic_types.cpp

@@ -122,7 +122,7 @@ std::string convertFromString<std::string>(StringView str)
 template <>
 int64_t convertFromString<int64_t>(StringView str)
 {
-  long result = 0;
+  int64_t result = 0;
   const auto [ptr, ec] = std::from_chars(str.data(), str.data() + str.size(), result);
   std::ignore = ptr;
   if(ec != std::errc())
@@ -135,7 +135,7 @@ int64_t convertFromString<int64_t>(StringView str)
 template <>
 uint64_t convertFromString<uint64_t>(StringView str)
 {
-  unsigned long result = 0;
+  uint64_t result = 0;
   const auto [ptr, ec] = std::from_chars(str.data(), str.data() + str.size(), result);
   std::ignore = ptr;
   if(ec != std::errc())