From 0a72cd7fcb366d22214c25b929ce40b4cf676767 Mon Sep 17 00:00:00 2001 From: Jackie Kay Date: Wed, 26 Aug 2015 15:22:28 -0700 Subject: [PATCH] mark up all the functions to document --- rclcpp/include/rclcpp/executor.hpp | 37 +++++++++++++++++++ .../executors/single_threaded_executor.hpp | 1 + rclcpp/include/rclcpp/memory_strategy.hpp | 1 + .../rclcpp/message_memory_strategy.hpp | 1 + rclcpp/include/rclcpp/node.hpp | 2 + rclcpp/include/rclcpp/publisher.hpp | 2 + .../message_pool_memory_strategy.hpp | 1 + .../strategies/static_memory_strategy.hpp | 2 + rclcpp/include/rclcpp/subscription.hpp | 3 ++ rclcpp/include/rclcpp/timer.hpp | 1 + rclcpp/include/rclcpp/utilities.hpp | 4 ++ 11 files changed, 55 insertions(+) diff --git a/rclcpp/include/rclcpp/executor.hpp b/rclcpp/include/rclcpp/executor.hpp index 3911d59..2f4c671 100644 --- a/rclcpp/include/rclcpp/executor.hpp +++ b/rclcpp/include/rclcpp/executor.hpp @@ -36,6 +36,15 @@ namespace rclcpp namespace executor { +/// Coordinates the order and timing of available communication tasks. +/* Executor provides spin functions (including spin_node_once and spin_some). + * It coordinates the nodes and callback groups by looking for available work and completing it, + * based on the threading or concurrency scheme provided by the subclass implementation. + * An example of available work is executing a subscription callback, or a timer callback. + * The executor structure allows for a decoupling of the communication graph and the execution + * model. + * See SingleThreadedExecutor and MultiThreadedExecutor for examples of execution paradigms. + */ class Executor { friend class memory_strategy::MemoryStrategy; @@ -43,6 +52,8 @@ class Executor public: RCLCPP_SMART_PTR_DEFINITIONS_NOT_COPYABLE(Executor); + /// Default constructor. + // \param[in] ms The memory strategy to be used with this executor. explicit Executor(memory_strategy::MemoryStrategy::SharedPtr ms = memory_strategy::create_default_strategy()) : interrupt_guard_condition_(rmw_create_guard_condition()), @@ -50,8 +61,10 @@ public: { } + /// Default destructor. virtual ~Executor() { + // Try to deallocate the interrupt guard condition. if (interrupt_guard_condition_ != nullptr) { rmw_ret_t status = rmw_destroy_guard_condition(interrupt_guard_condition_); if (status != RMW_RET_OK) { @@ -61,8 +74,17 @@ public: } } + /// Do work periodically as it becomes available to us. Blocking call, may block indefinitely. + // It is up to the implementation of Executor to implement spin. virtual void spin() = 0; + /// Add a node to the executor. + /* An executor can have zero or more nodes which provide work during `spin` functions. + * \param[in] node_ptr Shared pointer to the node to be added. + * \param[in] notify True to trigger the interrupt guard condition during this function. If + * the executor is blocked at the rmw layer while waiting for work and it is notified that a new + * node was added, it will wake up. + */ virtual void add_node(rclcpp::node::Node::SharedPtr & node_ptr, bool notify = true) { @@ -84,6 +106,12 @@ public: } } + /// Remove a node from the executor. + /* \param[in] node_ptr Shared pointer to the node to remove. + * \param[in] notify True to trigger the interrupt guard condition and wake up the executor. + * This is useful if the last node was removed from the executor while the executor was blocked + * waiting for work in another thread, because otherwise the executor would never be notified. + */ virtual void remove_node(rclcpp::node::Node::SharedPtr & node_ptr, bool notify = true) { @@ -108,6 +136,11 @@ public: } } + /// Add a node to executor, complete the next available unit of work, and remove the node. + /* \param[in] node Shared pointer to the node to add. + * \param[in] timeout How long to wait for work to become available. Negative values cause + * spin_node_once to block indefinitely + */ template void spin_node_once(rclcpp::node::Node::SharedPtr & node, std::chrono::duration timeout = std::chrono::duration(-1)) @@ -121,6 +154,7 @@ public: this->remove_node(node, false); } +// TODO void spin_node_some(rclcpp::node::Node::SharedPtr & node) { this->add_node(node, false); @@ -128,6 +162,7 @@ public: this->remove_node(node, false); } +// TODO virtual void spin_some() { while (AnyExecutable::SharedPtr any_exec = @@ -137,6 +172,7 @@ public: } } +// TODO // Support dynamic switching of memory strategy void set_memory_strategy(memory_strategy::MemoryStrategy::SharedPtr memory_strategy) @@ -149,6 +185,7 @@ public: protected: void +// TODO execute_any_executable(AnyExecutable::SharedPtr & any_exec) { if (!any_exec) { diff --git a/rclcpp/include/rclcpp/executors/single_threaded_executor.hpp b/rclcpp/include/rclcpp/executors/single_threaded_executor.hpp index 96c9fa7..944f2c4 100644 --- a/rclcpp/include/rclcpp/executors/single_threaded_executor.hpp +++ b/rclcpp/include/rclcpp/executors/single_threaded_executor.hpp @@ -36,6 +36,7 @@ namespace executors namespace single_threaded_executor { +// TODO class SingleThreadedExecutor : public executor::Executor { public: diff --git a/rclcpp/include/rclcpp/memory_strategy.hpp b/rclcpp/include/rclcpp/memory_strategy.hpp index a417689..bcc039b 100644 --- a/rclcpp/include/rclcpp/memory_strategy.hpp +++ b/rclcpp/include/rclcpp/memory_strategy.hpp @@ -30,6 +30,7 @@ class Executor; namespace memory_strategy { +// TODO class MemoryStrategy { diff --git a/rclcpp/include/rclcpp/message_memory_strategy.hpp b/rclcpp/include/rclcpp/message_memory_strategy.hpp index bc9a2f9..e071705 100644 --- a/rclcpp/include/rclcpp/message_memory_strategy.hpp +++ b/rclcpp/include/rclcpp/message_memory_strategy.hpp @@ -24,6 +24,7 @@ namespace rclcpp namespace message_memory_strategy { +// TODO template class MessageMemoryStrategy { diff --git a/rclcpp/include/rclcpp/node.hpp b/rclcpp/include/rclcpp/node.hpp index 03ff9de..49edbd3 100644 --- a/rclcpp/include/rclcpp/node.hpp +++ b/rclcpp/include/rclcpp/node.hpp @@ -96,6 +96,7 @@ struct function_traits * * This is the single point of entry for creating publishers and subscribers. */ +// TODO class Node { friend class rclcpp::executor::Executor; @@ -103,6 +104,7 @@ class Node public: RCLCPP_SMART_PTR_DEFINITIONS(Node); +// TODO: ALL public functions /* Create a node based on the node name. */ Node(const std::string & node_name, bool use_intra_process_comms = false); /* Create a node based on the node name and a rclcpp::context::Context. */ diff --git a/rclcpp/include/rclcpp/publisher.hpp b/rclcpp/include/rclcpp/publisher.hpp index 21cf457..5a95876 100644 --- a/rclcpp/include/rclcpp/publisher.hpp +++ b/rclcpp/include/rclcpp/publisher.hpp @@ -39,10 +39,12 @@ class Node; namespace publisher { +// TODO class Publisher { friend rclcpp::node::Node; +// TODO public: RCLCPP_SMART_PTR_DEFINITIONS(Publisher); diff --git a/rclcpp/include/rclcpp/strategies/message_pool_memory_strategy.hpp b/rclcpp/include/rclcpp/strategies/message_pool_memory_strategy.hpp index 098078a..28f2efa 100644 --- a/rclcpp/include/rclcpp/strategies/message_pool_memory_strategy.hpp +++ b/rclcpp/include/rclcpp/strategies/message_pool_memory_strategy.hpp @@ -25,6 +25,7 @@ namespace strategies namespace message_pool_memory_strategy { +// TODO template::value>::type * = nullptr> diff --git a/rclcpp/include/rclcpp/strategies/static_memory_strategy.hpp b/rclcpp/include/rclcpp/strategies/static_memory_strategy.hpp index b92c72d..216f897 100644 --- a/rclcpp/include/rclcpp/strategies/static_memory_strategy.hpp +++ b/rclcpp/include/rclcpp/strategies/static_memory_strategy.hpp @@ -27,6 +27,7 @@ namespace memory_strategies namespace static_memory_strategy { +// TODO struct ObjectPoolBounds { public: @@ -80,6 +81,7 @@ public: }; +// TODO class StaticMemoryStrategy : public memory_strategy::MemoryStrategy { public: diff --git a/rclcpp/include/rclcpp/subscription.hpp b/rclcpp/include/rclcpp/subscription.hpp index 4952087..d74e6bb 100644 --- a/rclcpp/include/rclcpp/subscription.hpp +++ b/rclcpp/include/rclcpp/subscription.hpp @@ -49,6 +49,7 @@ class SubscriptionBase { friend class rclcpp::executor::Executor; +// TODO public: RCLCPP_SMART_PTR_DEFINITIONS_NOT_COPYABLE(SubscriptionBase); @@ -113,11 +114,13 @@ private: }; +// TODO template class Subscription : public SubscriptionBase { friend class rclcpp::node::Node; +// TODO public: using CallbackType = std::function &)>; RCLCPP_SMART_PTR_DEFINITIONS(Subscription); diff --git a/rclcpp/include/rclcpp/timer.hpp b/rclcpp/include/rclcpp/timer.hpp index 2f97740..7c5d2bd 100644 --- a/rclcpp/include/rclcpp/timer.hpp +++ b/rclcpp/include/rclcpp/timer.hpp @@ -82,6 +82,7 @@ protected: }; +// TODO template class GenericTimer : public TimerBase { diff --git a/rclcpp/include/rclcpp/utilities.hpp b/rclcpp/include/rclcpp/utilities.hpp index 9e77976..ab09b58 100644 --- a/rclcpp/include/rclcpp/utilities.hpp +++ b/rclcpp/include/rclcpp/utilities.hpp @@ -98,6 +98,7 @@ RMW_THREAD_LOCAL size_t thread_id = 0; namespace utilities { +// TODO void init(int argc, char * argv[]) { @@ -138,12 +139,14 @@ init(int argc, char * argv[]) } } +// TODO bool ok() { return ::g_signal_status == 0; } +// TODO void shutdown() { @@ -163,6 +166,7 @@ get_global_sigint_guard_condition() return ::g_sigint_guard_cond_handle; } +// TODO bool sleep_for(const std::chrono::nanoseconds & nanoseconds) {