Support flexible task definitions (#39)

Co-authored-by: Michael X. Grey <[email protected]>
Signed-off-by: Michael X. Grey <[email protected]>
Co-authored-by: Charayaphan Nakorn Boon Han <[email protected]>
Signed-off-by: Charayaphan Nakorn Boon Han <[email protected]>
Co-authored-by: youliang <[email protected]>
Signed-off-by: youliang <[email protected]>
Co-authored-by: Yadu <[email protected]>
Signed-off-by: Yadu <[email protected]>
Co-authored-by: Xiyu <[email protected]>
Signed-off-by: Xiyu <[email protected]>

.github/workflows/build.yaml

@@ -1,5 +1,5 @@
 name: build
-on: 
+on:
   push:
   pull_request:
   schedule:
@@ -22,7 +22,7 @@ jobs:
           package-name: |
             rmf_task
           vcs-repo-file-url: |
-            https://raw.githubusercontent.com/open-rmf/rmf/main/rmf.repos
+            https://raw.githubusercontent.com/open-rmf/rmf/redesign_v2/rmf.repos
           colcon-defaults: |
             {
               "build": {

.github/workflows/tsan.yaml

@@ -1,5 +1,5 @@
 name: tsan
-on: 
+on:
   pull_request:
   schedule:
     - cron: '31 0 * * *'
@@ -23,9 +23,9 @@ jobs:
           target-ros2-distro: foxy
           # build all packages listed in the meta package
           package-name: |
-            rmf_task 
+            rmf_task
           vcs-repo-file-url: |
-            https://raw.githubusercontent.com/open-rmf/rmf/main/rmf.repos
+            https://raw.githubusercontent.com/open-rmf/rmf/redesign_v2/rmf.repos
           colcon-defaults: |
             {
               "build": {

rmf_task/CMakeLists.txt

@@ -29,10 +29,7 @@ find_package(ament_cmake_catch2 QUIET)
 find_package(ament_cmake_uncrustify QUIET)
 
 # ===== RMF Tasks library
-file(GLOB lib_srcs
-  "src/rmf_task/agv/*.cpp"
-  "src/rmf_task/requests/*.cpp"
-  "src/rmf_task/requests/factory/*.cpp"
+file(GLOB_RECURSE lib_srcs
   "src/rmf_task/*.cpp"
 )
 

rmf_task/include/rmf_task/Activator.hpp

@@ -0,0 +1,183 @@
+/*
+ * Copyright (C) 2021 Open Source Robotics Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+*/
+
+#ifndef RMF_TASK__ACTIVATOR_HPP
+#define RMF_TASK__ACTIVATOR_HPP
+
+#include <rmf_task/Request.hpp>
+
+namespace rmf_task {
+
+//==============================================================================
+/// A factory for generating Task::Active instances from requests.
+class Activator
+{
+public:
+
+  /// Construct an empty TaskFactory
+  Activator();
+
+  /// Signature for activating a task
+  ///
+  /// \tparam Description
+  ///   A class that implements the Task::Description interface
+  ///
+  /// \param[in] get_state
+  ///   A callback for retrieving the current state of the robot
+  ///
+  /// \param[in] parameters
+  ///   A reference to the parameters for the robot
+  ///
+  /// \param[in] booking
+  ///   An immutable reference to the booking information for the task
+  ///
+  /// \param[in] description
+  ///   The down-casted description of the task
+  ///
+  /// \param[in] backup_state
+  ///   The serialized backup state of the Task, if the Task is being restored
+  ///   from a crash or disconnection. If the Task is not being restored, a
+  ///   std::nullopt will be passed in here.
+  ///
+  /// \param[in] update
+  ///   A callback that will be triggered when the task has a significant
+  ///   update in its status.
+  ///
+  /// \param[in] checkpoint
+  ///   A callback that will be triggered when the task has reached a task
+  ///   checkpoint whose state is worth backing up.
+  ///
+  /// \param[in] finished
+  ///   A callback that will be triggered when the task has finished.
+  ///
+  /// \return an active, running instance of the requested task.
+  template<typename Description>
+  using Activate =
+    std::function<
+    Task::ActivePtr(
+      const std::function<State()>& get_state,
+      const ConstParametersPtr& parameters,
+      const Task::ConstBookingPtr& booking,
+      const Description& description,
+      std::optional<std::string> backup_state,
+      std::function<void(Phase::ConstSnapshotPtr)> update,
+      std::function<void(Task::Active::Backup)> checkpoint,
+      std::function<void(Phase::ConstCompletedPtr)> phase_finished,
+      std::function<void()> task_finished)
+    >;
+
+  /// Add a callback to convert from a Description into an active Task.
+  ///
+  /// \tparam Description
+  ///   A class that implements the Request::Description interface
+  ///
+  /// \param[in] activator
+  ///   A callback that activates a Task matching the Description
+  template<typename Description>
+  void add_activator(Activate<Description> activator);
+
+  /// Activate a Task object based on a Request.
+  ///
+  /// \param[in] get_state
+  ///   A callback for retrieving the current state of the robot
+  ///
+  /// \param[in] parameters
+  ///   A reference to the parameters for the robot
+  ///
+  /// \param[in] request
+  ///   The task request
+  ///
+  /// \param[in] update
+  ///   A callback that will be triggered when the task has a significant update
+  ///
+  /// \param[in] checkpoint
+  ///   A callback that will be triggered when the task has reached a task
+  ///   checkpoint whose state is worth backing up.
+  ///
+  /// \param[in] phase_finished
+  ///   A callback that will be triggered whenever a task phase is finished
+  ///
+  /// \param[in] task_finished
+  ///   A callback that will be triggered when the task has finished
+  ///
+  /// \return an active, running instance of the requested task.
+  Task::ActivePtr activate(
+    const std::function<State()>& get_state,
+    const ConstParametersPtr& parameters,
+    const Request& request,
+    std::function<void(Phase::ConstSnapshotPtr)> update,
+    std::function<void(Task::Active::Backup)> checkpoint,
+    std::function<void(Phase::ConstCompletedPtr)> phase_finished,
+    std::function<void()> task_finished) const;
+
+  /// Restore a Task that crashed or disconnected.
+  ///
+  /// \param[in] get_state
+  ///   A callback for retrieving the current state of the robot
+  ///
+  /// \param[in] parameters
+  ///   A reference to the parameters for the robot
+  ///
+  /// \param[in] request
+  ///   The task request
+  ///
+  /// \param[in] backup_state
+  ///   The serialized backup state of the Task
+  ///
+  /// \param[in] update
+  ///   A callback that will be triggered when the task has a significant update
+  ///
+  /// \param[in] checkpoint
+  ///   A callback that will be triggered when the task has reached a task
+  ///   checkpoint whose state is worth backing up.
+  ///
+  /// \param[in] phase_finished
+  ///   A callback that will be triggered whenever a task phase is finished
+  ///
+  /// \param[in] task_finished
+  ///   A callback that will be triggered when the task has finished
+  ///
+  /// \return an active, running instance of the requested task.
+  Task::ActivePtr restore(
+    const std::function<State()>& get_state,
+    const ConstParametersPtr& parameters,
+    const Request& request,
+    std::string backup_state,
+    std::function<void(Phase::ConstSnapshotPtr)> update,
+    std::function<void(Task::Active::Backup)> checkpoint,
+    std::function<void(Phase::ConstCompletedPtr)> phase_finished,
+    std::function<void()> task_finished) const;
+
+  class Implementation;
+private:
+
+  /// \private
+  void _add_activator(
+    std::type_index type,
+    Activate<Task::Description> activator);
+
+  rmf_utils::impl_ptr<Implementation> _pimpl;
+};
+
+using ActivatorPtr = std::shared_ptr<Activator>;
+using ConstActivatorPtr = std::shared_ptr<const Activator>;
+
+} // namespace rmf_task
+
+#include <rmf_task/detail/impl_Activator.hpp>
+
+#endif // RMF_TASK__ACTIVATOR_HPP

rmf_task/include/rmf_task/BackupFileManager.hpp

@@ -0,0 +1,109 @@
+/*
+ * Copyright (C) 2021 Open Source Robotics Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+*/
+
+#ifndef RMF_TASK__BACKUPFILEMANAGER_HPP
+#define RMF_TASK__BACKUPFILEMANAGER_HPP
+
+#include <rmf_task/Task.hpp>
+
+#include <filesystem>
+
+namespace rmf_task {
+
+//==============================================================================
+class BackupFileManager
+{
+public:
+
+  class Group;
+  class Robot;
+
+  /// Construct a BackupFileManager
+  ///
+  /// \param[in] root_directory
+  ///   Specify the root directory that the backup files should live in
+  BackupFileManager(std::filesystem::path root_directory,
+    std::function<void(std::string)> info_logger = nullptr,
+    std::function<void(std::string)> debug_logger = nullptr);
+
+  /// Set whether any previously existing backups should be cleared out on
+  /// startup. By default this behavior is turned OFF.
+  ///
+  /// \param[in] value
+  ///   True if the behavior should be turned on; false if it should be turned
+  ///   off.
+  BackupFileManager& clear_on_startup(bool value = true);
+
+  /// Set whether any currently existing backups should be cleared out on
+  /// shutdown. By default this behavior is turned ON.
+  ///
+  /// \param[in] value
+  ///   True if the behavior should be turned on; false if it should be turned
+  ///   off.
+  BackupFileManager& clear_on_shutdown(bool value = true);
+
+  /// Make a group (a.k.a. fleet) to back up.
+  std::shared_ptr<Group> make_group(std::string name);
+
+  class Implementation;
+private:
+  rmf_utils::unique_impl_ptr<Implementation> _pimpl;
+};
+
+//==============================================================================
+class BackupFileManager::Group
+{
+public:
+
+  /// Make a handle to backup a robot for this group
+  ///
+  /// \param[in] name
+  ///   The unique name of the robot that's being backed up
+  std::shared_ptr<Robot> make_robot(std::string name);
+
+  // TODO(MXG): Add an API for saving the task assignments of the Group. When
+  // the Group is constructed/destructed, it should clear out those task
+  // assignments, according to the RAII settings of its parent BackupFileManager
+  // instance.
+
+  class Implementation;
+private:
+  Group();
+  rmf_utils::unique_impl_ptr<Implementation> _pimpl;
+};
+
+//==============================================================================
+class BackupFileManager::Robot
+{
+public:
+
+  /// Read a backup state from file if a backup file exists for this robot.
+  /// If a backup does not exist, return a nullopt.
+  std::optional<std::string> read() const;
+
+  /// Write a backup to file
+  void write(const Task::Active::Backup& backup);
+
+  class Implementation;
+private:
+  Robot();
+  rmf_utils::unique_impl_ptr<Implementation> _pimpl;
+};
+
+} // namespace rmf_task
+
+#endif // RMF_TASK__BACKUPFILEMANAGER_HPP