use PImpl and more comments

Author: facontidavide

include/behaviortree_cpp/bt_factory.h

@@ -1,5 +1,5 @@
 /* Copyright (C) 2018 Michele Colledanchise -  All Rights Reserved
- * Copyright (C) 2018-2020 Davide Faconti, Eurecat -  All Rights Reserved
+ * Copyright (C) 2018-2023 Davide Faconti - All Rights Reserved
 *
 *   Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),
 *   to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
@@ -14,12 +14,13 @@
 #ifndef BT_FACTORY_H
 #define BT_FACTORY_H
 
+#include <algorithm>
+#include <cstring>
+#include <filesystem>
 #include <functional>
 #include <memory>
 #include <unordered_map>
 #include <unordered_set>
-#include <cstring>
-#include <algorithm>
 #include <set>
 
 #include "behaviortree_cpp/contrib/magic_enum.hpp"
@@ -99,47 +100,19 @@ class Tree
   };
 
   std::vector<Subtree::Ptr> subtrees;
-
   std::unordered_map<std::string, TreeNodeManifest> manifests;
 
-  Tree()
-  {}
+  Tree();
 
-  // non-copyable. Only movable
   Tree(const Tree&) = delete;
   Tree& operator=(const Tree&) = delete;
 
-  Tree(Tree&& other)
-  {
-    (*this) = std::move(other);
-  }
-
-  Tree& operator=(Tree&& other)
-  {
-    subtrees = std::move(other.subtrees);
-    manifests = std::move(other.manifests);
-    wake_up_ = other.wake_up_;
-    return *this;
-  }
+  Tree(Tree&& other);
+  Tree& operator=(Tree&& other);
 
   void initialize();
 
-  void haltTree()
-  {
-    if (!rootNode())
-    {
-      return;
-    }
-    // the halt should propagate to all the node if the nodes
-    // have been implemented correctly
-    rootNode()->haltNode();
-
-    //but, just in case.... this should be no-op
-    auto visitor = [](BT::TreeNode* node) { node->haltNode(); };
-    BT::applyRecursiveVisitor(rootNode(), visitor);
-
-    rootNode()->resetStatus();
-  }
+  void haltTree();
 
   [[nodiscard]] TreeNode* rootNode() const;
 
@@ -226,6 +199,13 @@ class BehaviorTreeFactory
 {
 public:
   BehaviorTreeFactory();
+  ~BehaviorTreeFactory();
+
+  BehaviorTreeFactory(const BehaviorTreeFactory& other) = delete;
+  BehaviorTreeFactory& operator=(const BehaviorTreeFactory& other) = delete;
+
+  BehaviorTreeFactory(BehaviorTreeFactory&& other) = default;
+  BehaviorTreeFactory& operator=(BehaviorTreeFactory&& other)  = default;
 
   /// Remove a registered ID.
   bool unregisterBuilder(const std::string& ID);
@@ -302,14 +282,15 @@ class BehaviorTreeFactory
      * where "tree_id" come from the XML attribute <BehaviorTree ID="tree_id">
      *
      */
-  void registerBehaviorTreeFromFile(const std::string& filename);
+  void registerBehaviorTreeFromFile(const std::filesystem::path& filename);
 
   /// Same of registerBehaviorTreeFromFile, but passing the XML text,
   /// instead of the filename.
   void registerBehaviorTreeFromText(const std::string& xml_text);
 
   /// Returns the ID of the trees registered either with
   /// registerBehaviorTreeFromFile or registerBehaviorTreeFromText.
+  [[nodiscard]]
   std::vector<std::string> registeredBehaviorTrees() const;
 
   /**
@@ -325,6 +306,7 @@ class BehaviorTreeFactory
      * @param config   configuration that is passed to the constructor of the TreeNode.
      * @return         new node.
      */
+  [[nodiscard]]
   std::unique_ptr<TreeNode> instantiateTreeNode(const std::string& name,
                                                 const std::string& ID,
                                                 const NodeConfig& config) const;
@@ -392,20 +374,48 @@ class BehaviorTreeFactory
   }
 
   /// All the builders. Made available mostly for debug purposes.
+  [[nodiscard]]
   const std::unordered_map<std::string, NodeBuilder>& builders() const;
 
   /// Manifests of all the registered TreeNodes.
+  [[nodiscard]]
   const std::unordered_map<std::string, TreeNodeManifest>& manifests() const;
 
   /// List of builtin IDs.
+  [[nodiscard]]
   const std::set<std::string>& builtinNodes() const;
 
+  /**
+   * @brief createTreeFromText will parse the XML directly from string.
+   * The XML needs to contain either a single <BehaviorTree> or specify
+   * the attribute [main_tree_to_execute].
+   *
+   * Consider using instead registerBehaviorTreeFromText() and createTree().
+   *
+   * @param text        string containing the XML
+   * @param blackboard  blackboard of the root tree
+   * @return the newly created tree
+   */
+  [[nodiscard]]
   Tree createTreeFromText(const std::string& text,
                           Blackboard::Ptr blackboard = Blackboard::create());
 
-  Tree createTreeFromFile(const std::string& file_path,
+  /**
+   * @brief createTreeFromFile will parse the XML from a given file.
+   * The XML needs to contain either a single <BehaviorTree> or specify
+   * the attribute [main_tree_to_execute].
+   *
+   * Consider using instead registerBehaviorTreeFromFile() and createTree().
+   *
+   * @param file_path   location of the file to load
+   * @param blackboard  blackboard of the root tree
+   * @return the newly created tree
+   */
+  [[nodiscard]]
+  Tree createTreeFromFile(const std::filesystem::path& file_path,
                           Blackboard::Ptr blackboard = Blackboard::create());
 
+  [[nodiscard]]
   Tree createTree(const std::string& tree_name,
                   Blackboard::Ptr blackboard = Blackboard::create());
 
@@ -476,20 +486,14 @@ class BehaviorTreeFactory
   /**
    * @brief substitutionRules return the current substitution rules.
    */
+  [[nodiscard]]
   const std::unordered_map<std::string, SubstitutionRule>&
   substitutionRules() const;
 
 private:
-  std::unordered_map<std::string, NodeBuilder> builders_;
-  std::unordered_map<std::string, TreeNodeManifest> manifests_;
-  std::set<std::string> builtin_IDs_;
-  std::unordered_map<std::string, Any> behavior_tree_definitions_;
-
-  std::shared_ptr<std::unordered_map<std::string, int>> scripting_enums_;
-
-  std::shared_ptr<BT::Parser> parser_;
 
-  std::unordered_map<std::string, SubstitutionRule> substitution_rules_;
+  struct PImpl;
+  std::unique_ptr<PImpl> _p;
 
 };
 

include/behaviortree_cpp/bt_parser.h

@@ -1,4 +1,4 @@
-/* Copyright (C) 2022 Davide Faconti -  All Rights Reserved
+/* Copyright (C) 2023 Davide Faconti -  All Rights Reserved
 *
 *   Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),
 *   to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
@@ -12,6 +12,7 @@
 
 #pragma once
 
+#include <filesystem>
 #include "behaviortree_cpp/bt_factory.h"
 #include "behaviortree_cpp/blackboard.h"
 
@@ -32,7 +33,10 @@ class Parser
   Parser(const Parser& other) = delete;
   Parser& operator=(const Parser& other) = delete;
 
-  virtual void loadFromFile(const std::string& filename, bool add_includes = true) = 0;
+  Parser(Parser&& other) = default;
+  Parser& operator=(Parser&& other) = default;
+
+  virtual void loadFromFile(const std::filesystem::path& filename, bool add_includes = true) = 0;
 
   virtual void loadFromText(const std::string& xml_text, bool add_includes = true) = 0;
 

include/behaviortree_cpp/loggers/abstract_logger.h

@@ -18,6 +18,12 @@ class StatusChangeLogger
   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;
+
   virtual void callback(BT::Duration timestamp, const TreeNode& node,
                         NodeStatus prev_status, NodeStatus status) = 0;
 

include/behaviortree_cpp/loggers/bt_cout_logger.h

@@ -7,13 +7,8 @@
 namespace BT
 {
 /**
- * @brief AddStdCoutLoggerToTree. Give  the root node of a tree,
- * a simple callback is subscribed to any status change of each node.
- *
- *
- * @param root_node
- * @return Important: the returned shared_ptr must not go out of scope,
- *         otherwise the logger is removed.
+ * @brief StdCoutLogger is a very simple logger that
+ * displays all the transitions on the console.
  */
 
 class StdCoutLogger : public StatusChangeLogger
@@ -24,10 +19,13 @@ class StdCoutLogger : public StatusChangeLogger
   StdCoutLogger(const BT::Tree& tree);
   ~StdCoutLogger() override;
 
-  virtual void callback(Duration timestamp, const TreeNode& node, NodeStatus prev_status,
-                        NodeStatus status) override;
-
   virtual void flush() override;
+
+private:
+
+  virtual void callback(Duration timestamp, const TreeNode& node,
+                        NodeStatus prev_status, NodeStatus status) override;
+
 };
 
 }   // namespace BT

include/behaviortree_cpp/loggers/bt_file_logger_v2.h

@@ -9,15 +9,15 @@ namespace BT
 {
 /**
  * @brief The FileLogger2 is a logger that saves the tree as
- * XML and all the transitions. Data is written to file in
- * a separate thread, to minimize latency.
+ * XML and all the transitions.
+ * Data is written to file in a separate thread, to minimize latency.
  *
  * Format:
  *
  * - first 4 bytes: size of the XML string (N)
  * - next N bytes: string containing the XML representing the tree.
  * - next 8 bytes: first timestamp (microseconds since epoch)
- * - next: each 8 bytes is a FileLogger2::Transition. See definition.
+ * - next: each 9 bytes is a FileLogger2::Transition. See definition.
  *
  */
 class FileLogger2 : public StatusChangeLogger
@@ -32,13 +32,21 @@ class FileLogger2 : public StatusChangeLogger
    */
   FileLogger2(const Tree& tree, std::filesystem::path const& filepath);
 
+  FileLogger2(const FileLogger2& other) = delete;
+  FileLogger2& operator=(const FileLogger2& other) = delete;
+
+  FileLogger2(FileLogger2&& other) = default;
+  FileLogger2& operator=(FileLogger2&& other) = default;
+
   virtual ~FileLogger2() override;
 
   void callback(Duration timestamp, const TreeNode& node, NodeStatus prev_status,
                 NodeStatus status) override;
 
   struct Transition
   {
+    // when serializing, we will remove the initial time and serialize only
+    // 6 bytes, instead of 8
     uint64_t timestamp_usec;
     // if you have more than 64.000 nodes, you are doing something wrong :)
     uint16_t node_uid;
@@ -49,16 +57,8 @@ class FileLogger2 : public StatusChangeLogger
   void flush() override;
 
 private:
-  std::ofstream file_stream_;
-
-  Duration first_timestamp_ = {};
-
-  std::deque<Transition> transitions_queue_;
-  std::condition_variable queue_cv_;
-  std::mutex queue_mutex_;
-
-  std::thread writer_thread_;
-  std::atomic_bool loop_ = true;
+  struct PImpl;
+  std::unique_ptr<PImpl> _p;
 
   void writerLoop();
 };

include/behaviortree_cpp/loggers/bt_observer.h

@@ -7,15 +7,19 @@
 namespace BT
 {
 
+/**
+ * @brief The TreeObserver is used to collect statistics about which nodes
+ * are executed and their returned status.
+ *
+ * It is particularly useful to create unit tests, since if allow to
+ * determine if a certain transition happened as expected, in a non intrusive way.
+ */
 class TreeObserver : public StatusChangeLogger
 {
 public:
   TreeObserver(const BT::Tree& tree);
   ~TreeObserver() override;
 
-  virtual void callback(Duration timestamp, const TreeNode& node, NodeStatus prev_status,
-                        NodeStatus status) override;
-
   virtual void flush() override {}
 
   void resetStatistics();
@@ -57,6 +61,9 @@ class TreeObserver : public StatusChangeLogger
   std::unordered_map<uint16_t, NodeStatistics> _statistics;
   std::unordered_map<std::string, uint16_t> _path_to_uid;
   std::map<uint16_t, std::string> _uid_to_path;
+
+  virtual void callback(Duration timestamp, const TreeNode& node,
+                        NodeStatus prev_status, NodeStatus status) override;
 };
 
 }   // namespace BT