Correct doxygen blocks
This commit is contained in:
Jackie Kay
parent
3ef83ec292
commit
9f0cda20af
9 changed files with 97 additions and 50 deletions
|
|
@ -36,8 +36,9 @@ namespace rclcpp
|
|||
namespace executor
|
||||
{
|
||||
|
||||
/// Coordinates the order and timing of available communication tasks.
|
||||
/* Executor provides spin functions (including spin_node_once and spin_some).
|
||||
/// Coordinate 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.
|
||||
|
|
@ -79,7 +80,8 @@ public:
|
|||
virtual void spin() = 0;
|
||||
|
||||
/// Add a node to the executor.
|
||||
/* An executor can have zero or more nodes which provide work during `spin` functions.
|
||||
/**
|
||||
* 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
|
||||
|
|
@ -107,7 +109,8 @@ public:
|
|||
}
|
||||
|
||||
/// Remove a node from the executor.
|
||||
/* \param[in] node_ptr Shared pointer to the node to remove.
|
||||
/**
|
||||
* \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.
|
||||
|
|
@ -137,7 +140,8 @@ public:
|
|||
}
|
||||
|
||||
/// Add a node to executor, execute the next available unit of work, and remove the node.
|
||||
/* \param[in] node Shared pointer to the node to add.
|
||||
/**
|
||||
* \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 (the default behavior). A timeout of 0 causes this
|
||||
* function to be non-blocking.
|
||||
|
|
@ -156,7 +160,8 @@ public:
|
|||
}
|
||||
|
||||
/// Add a node, complete all immediately available work, and remove the node.
|
||||
/* \param[in] node Shared pointer to the node to add.
|
||||
/**
|
||||
* \param[in] node Shared pointer to the node to add.
|
||||
*/
|
||||
void spin_node_some(rclcpp::node::Node::SharedPtr & node)
|
||||
{
|
||||
|
|
@ -166,7 +171,8 @@ public:
|
|||
}
|
||||
|
||||
/// Complete all available queued work without blocking.
|
||||
/* This function can be overridden. The default implementation is suitable for a
|
||||
/**
|
||||
* This function can be overridden. The default implementation is suitable for a
|
||||
* single-threaded model of execution.
|
||||
* Adding subscriptions, timers, services, etc. with blocking callbacks will cause this function
|
||||
* to block (which may have unintended consequences).
|
||||
|
|
@ -181,7 +187,8 @@ public:
|
|||
}
|
||||
|
||||
/// Support dynamic switching of the memory strategy.
|
||||
/* Switching the memory strategy while the executor is spinning in another threading could have
|
||||
/**
|
||||
* Switching the memory strategy while the executor is spinning in another threading could have
|
||||
* unintended consequences.
|
||||
* \param[in] memory_strategy Shared pointer to the memory strategy to set.
|
||||
*/
|
||||
|
|
@ -196,8 +203,9 @@ public:
|
|||
|
||||
protected:
|
||||
/// Find the next available executable and do the work associated with it.
|
||||
// \param[in] any_exec Union structure that can hold any executable type (timer, subscription,
|
||||
// service, client).
|
||||
/** \param[in] any_exec Union structure that can hold any executable type (timer, subscription,
|
||||
* service, client).
|
||||
*/
|
||||
void
|
||||
execute_any_executable(AnyExecutable::SharedPtr & any_exec)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -31,7 +31,8 @@ namespace memory_strategy
|
|||
{
|
||||
|
||||
/// Delegate for handling memory allocations while the Executor is executing.
|
||||
/* By default, the memory strategy dynamically allocates memory for structures that come in from
|
||||
/**
|
||||
* By default, the memory strategy dynamically allocates memory for structures that come in from
|
||||
* the rmw implementation after the executor waits for work, based on the number of entities that
|
||||
* come through.
|
||||
*/
|
||||
|
|
@ -44,7 +45,8 @@ public:
|
|||
RCLCPP_SMART_PTR_DEFINITIONS(MemoryStrategy);
|
||||
|
||||
/// Borrow memory for storing data for subscriptions, services, clients, or guard conditions.
|
||||
/* The default implementation ignores the handle type and dynamically allocates the memory.
|
||||
/**
|
||||
* The default implementation ignores the handle type and dynamically allocates the memory.
|
||||
* \param[in] The type of entity that this function is requesting for.
|
||||
* \param[in] The number of handles to borrow.
|
||||
* \return Pointer to the allocated handles.
|
||||
|
|
@ -56,7 +58,8 @@ public:
|
|||
}
|
||||
|
||||
/// Return the memory borrowed in borrow_handles.
|
||||
/* return_handles should always mirror the way memory was borrowed in borrow_handles.
|
||||
/**
|
||||
* return_handles should always mirror the way memory was borrowed in borrow_handles.
|
||||
* \param[in] The type of entity that this function is returning.
|
||||
* \param[in] Pointer to the handles returned.
|
||||
*/
|
||||
|
|
@ -74,7 +77,8 @@ public:
|
|||
}
|
||||
|
||||
/// Implementation of a general-purpose allocation function.
|
||||
/* \param[in] size Number of bytes to allocate.
|
||||
/**
|
||||
* \param[in] size Number of bytes to allocate.
|
||||
* \return Pointer to the allocated chunk of memory.
|
||||
*/
|
||||
virtual void * alloc(size_t size)
|
||||
|
|
@ -86,7 +90,8 @@ public:
|
|||
}
|
||||
|
||||
/// Implementation of a general-purpose free.
|
||||
/* \param[in] Pointer to deallocate.
|
||||
/**
|
||||
* \param[in] Pointer to deallocate.
|
||||
*/
|
||||
virtual void free(void * ptr)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -101,14 +101,16 @@ public:
|
|||
RCLCPP_SMART_PTR_DEFINITIONS(Node);
|
||||
|
||||
/// Create a new node with the specified name.
|
||||
/* \param[in] node_name Name of the node.
|
||||
/**
|
||||
* \param[in] node_name Name of the node.
|
||||
* \param[in] use_intra_process_comms True to use the optimized intra-process communication
|
||||
* pipeline to pass messages between nodes in the same process using shared memory.
|
||||
*/
|
||||
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.
|
||||
/* \param[in] node_name Name of the node.
|
||||
/**
|
||||
* \param[in] node_name Name of the node.
|
||||
* \param[in] context The context for the node (usually represents the state of a process).
|
||||
* \param[in] use_intra_process_comms True to use the optimized intra-process communication
|
||||
* pipeline to pass messages between nodes in the same process using shared memory.
|
||||
|
|
@ -127,7 +129,8 @@ public:
|
|||
create_callback_group(rclcpp::callback_group::CallbackGroupType group_type);
|
||||
|
||||
/// Create and return a Publisher.
|
||||
/* \param[in] topic_name The topic for this publisher to publish on.
|
||||
/**
|
||||
* \param[in] topic_name The topic for this publisher to publish on.
|
||||
* \param[in] qos_profile The quality of service profile to pass on to the rmw implementation.
|
||||
* \return Shared pointer to the created publisher.
|
||||
*/
|
||||
|
|
@ -137,7 +140,8 @@ public:
|
|||
const std::string & topic_name, const rmw_qos_profile_t & qos_profile);
|
||||
|
||||
/// Create and return a Subscription.
|
||||
/* \param[in] topic_name The topic to subscribe on.
|
||||
/**
|
||||
* \param[in] topic_name The topic to subscribe on.
|
||||
* \param[in] qos_profile The quality of service profile to pass on to the rmw implementation.
|
||||
* \param[in] callback The user-defined callback function.
|
||||
* \param[in] group The callback group for this subscription. NULL for no callback group.
|
||||
|
|
@ -161,7 +165,8 @@ public:
|
|||
msg_mem_strat = nullptr);
|
||||
|
||||
/// Create a timer.
|
||||
/* \param[in] period Time interval between triggers of the callback.
|
||||
/**
|
||||
* \param[in] period Time interval between triggers of the callback.
|
||||
* \param[in] callback User-defined callback function.
|
||||
* \param[in] group Callback group to execute this timer's callback in.
|
||||
*/
|
||||
|
|
@ -172,7 +177,8 @@ public:
|
|||
rclcpp::callback_group::CallbackGroup::SharedPtr group = nullptr);
|
||||
|
||||
/// Create a timer with a sub-nanosecond precision update period.
|
||||
/* \param[in] period Time interval between triggers of the callback.
|
||||
/**
|
||||
* \param[in] period Time interval between triggers of the callback.
|
||||
* \param[in] callback User-defined callback function.
|
||||
* \param[in] group Callback group to execute this timer's callback in.
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -48,7 +48,8 @@ public:
|
|||
RCLCPP_SMART_PTR_DEFINITIONS(Publisher);
|
||||
|
||||
/// Default constructor.
|
||||
/* Typically, a publisher is not created through this method, but instead is created through a
|
||||
/**
|
||||
* Typically, a publisher is not created through this method, but instead is created through a
|
||||
* call to `Node::create_publisher`.
|
||||
* \param[in] node_handle The corresponding rmw representation of the owner node.
|
||||
* \param[in] publisher_handle The rmw publisher handle corresponding to this publisher.
|
||||
|
|
@ -96,7 +97,8 @@ public:
|
|||
}
|
||||
|
||||
/// Send a message to the topic for this publisher.
|
||||
/* This function is templated on the input message type, MessageT.
|
||||
/**
|
||||
* This function is templated on the input message type, MessageT.
|
||||
* \param[in] msg A shared pointer to the message to send.
|
||||
*/
|
||||
template<typename MessageT>
|
||||
|
|
@ -159,7 +161,8 @@ public:
|
|||
}
|
||||
|
||||
/// Compare this publisher to a gid.
|
||||
/* Note that this function calls the next function.
|
||||
/**
|
||||
* Note that this function calls the next function.
|
||||
* \param[in] gid Reference to a gid.
|
||||
* \return True if the publisher's gid matches the input.
|
||||
*/
|
||||
|
|
@ -170,7 +173,8 @@ public:
|
|||
}
|
||||
|
||||
/// Compare this publisher to a pointer gid.
|
||||
/* A wrapper for comparing this publisher's gid to the input using rmw_compare_gids_equal.
|
||||
/**
|
||||
* A wrapper for comparing this publisher's gid to the input using rmw_compare_gids_equal.
|
||||
* \param[in] gid A pointer to a gid.
|
||||
* \return True if this publisher's gid matches the input.
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -26,7 +26,8 @@ namespace message_pool_memory_strategy
|
|||
{
|
||||
|
||||
/// Completely static memory allocation strategy for messages.
|
||||
/* Templated on the type of message pooled by this class and the size of the message pool.
|
||||
/**
|
||||
* Templated on the type of message pooled by this class and the size of the message pool.
|
||||
* Templating allows the program to determine the memory required for this object at compile time.
|
||||
* The size of the message pool should be at least the largest number of concurrent accesses to
|
||||
* the subscription (usually the number of threads).
|
||||
|
|
@ -51,7 +52,8 @@ public:
|
|||
}
|
||||
|
||||
/// Borrow a message from the message pool.
|
||||
/* Manage the message pool ring buffer.
|
||||
/**
|
||||
* Manage the message pool ring buffer.
|
||||
* Throw an exception if the next message was not available.
|
||||
* \return Shared pointer to the borrowed message.
|
||||
*/
|
||||
|
|
@ -70,7 +72,8 @@ public:
|
|||
}
|
||||
|
||||
/// Return a message to the message pool.
|
||||
/* Manage metadata in the message pool ring buffer to release the message.
|
||||
/**
|
||||
* Manage metadata in the message pool ring buffer to release the message.
|
||||
* \param[in] msg Shared pointer to the message to return.
|
||||
*/
|
||||
void return_message(std::shared_ptr<MessageT> & msg)
|
||||
|
|
|
|||
|
|
@ -48,7 +48,8 @@ public:
|
|||
// Setters implement named parameter idiom/method chaining
|
||||
|
||||
/// Set the maximum number of subscriptions.
|
||||
/* \param[in] subscriptions Maximum number of subscriptions.
|
||||
/**
|
||||
* \param[in] subscriptions Maximum number of subscriptions.
|
||||
* \return Reference to this object, for method chaining.
|
||||
*/
|
||||
ObjectPoolBounds & set_max_subscriptions(size_t subscriptions)
|
||||
|
|
@ -58,7 +59,8 @@ public:
|
|||
}
|
||||
|
||||
/// Set the maximum number of services.
|
||||
/* \param[in] services Maximum number of services.
|
||||
/**
|
||||
* \param[in] services Maximum number of services.
|
||||
* \return Reference to this object, for method chaining.
|
||||
*/
|
||||
ObjectPoolBounds & set_max_services(size_t services)
|
||||
|
|
@ -68,7 +70,8 @@ public:
|
|||
}
|
||||
|
||||
/// Set the maximum number of clients.
|
||||
/* \param[in] clients Maximum number of clients.
|
||||
/**
|
||||
* \param[in] clients Maximum number of clients.
|
||||
* \return Reference to this object, for method chaining.
|
||||
*/
|
||||
ObjectPoolBounds & set_max_clients(size_t clients)
|
||||
|
|
@ -78,7 +81,8 @@ public:
|
|||
}
|
||||
|
||||
/// Set the maximum number of guard conditions.
|
||||
/* \param[in] guard conditions Maximum number of guard conditions.
|
||||
/**
|
||||
* \param[in] guard conditions Maximum number of guard conditions.
|
||||
* \return Reference to this object, for method chaining.
|
||||
*/
|
||||
ObjectPoolBounds & set_max_guard_conditions(size_t guard_conditions)
|
||||
|
|
@ -88,7 +92,8 @@ public:
|
|||
}
|
||||
|
||||
/// Set the maximum number of executables.
|
||||
/* \param[in] executables Maximum number of executables.
|
||||
/**
|
||||
* \param[in] executables Maximum number of executables.
|
||||
* \return Reference to this object, for method chaining.
|
||||
*/
|
||||
ObjectPoolBounds & set_max_executables(size_t executables)
|
||||
|
|
@ -98,7 +103,8 @@ public:
|
|||
}
|
||||
|
||||
/// Set the maximum memory pool size.
|
||||
/* \param[in] executables Maximum memory pool size.
|
||||
/**
|
||||
* \param[in] executables Maximum memory pool size.
|
||||
* \return Reference to this object, for method chaining.
|
||||
*/
|
||||
ObjectPoolBounds & set_memory_pool_size(size_t pool)
|
||||
|
|
@ -110,7 +116,8 @@ public:
|
|||
|
||||
|
||||
/// Static memory allocation alternative to the default memory strategy.
|
||||
/* The name is a bit of a misnomer. The memory managed by this class is actually allocated
|
||||
/**
|
||||
* The name is a bit of a misnomer. The memory managed by this class is actually allocated
|
||||
* dynamically in the constructor, but no subsequent accesses to the class (besides the destructor)
|
||||
* allocate or free memory.
|
||||
* StaticMemoryStrategy puts a hard limit on the number of subscriptions, etc. that can be executed
|
||||
|
|
@ -190,7 +197,8 @@ public:
|
|||
}
|
||||
|
||||
/// Borrow handles by returning a pointer to the preallocated object pool for the specified type.
|
||||
/* \param[in] The type of entity that this function is requesting for.
|
||||
/**
|
||||
* \param[in] The type of entity that this function is requesting for.
|
||||
* \param[in] The number of handles to borrow.
|
||||
* \return Pointer to the allocated handles.
|
||||
*/
|
||||
|
|
@ -228,7 +236,8 @@ public:
|
|||
}
|
||||
|
||||
/// Return the borrowed handles by clearing the object pool for the correspondign type.
|
||||
/* \param[in] The type of entity that this function is returning.
|
||||
/**
|
||||
* \param[in] The type of entity that this function is returning.
|
||||
* \param[in] Pointer to the handles returned.
|
||||
*/
|
||||
void return_handles(HandleType type, void ** handles)
|
||||
|
|
@ -287,7 +296,8 @@ public:
|
|||
}
|
||||
|
||||
/// General allocate: reserve space in the memory pool reserved by this function.
|
||||
/* \param[in] size Number of bytes to allocate.
|
||||
/**
|
||||
* \param[in] size Number of bytes to allocate.
|
||||
* \return Pointer to the allocated chunk of memory.
|
||||
*/
|
||||
void * alloc(size_t size)
|
||||
|
|
@ -310,7 +320,8 @@ public:
|
|||
}
|
||||
|
||||
/// Release the allocated memory in the memory pool.
|
||||
/* \param[in] Pointer to deallocate.
|
||||
/**
|
||||
* \param[in] Pointer to deallocate.
|
||||
*/
|
||||
void free(void * ptr)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -55,7 +55,8 @@ public:
|
|||
RCLCPP_SMART_PTR_DEFINITIONS_NOT_COPYABLE(SubscriptionBase);
|
||||
|
||||
/// Default constructor.
|
||||
/* \param[in] node_handle The rmw representation of the node that owns this subscription.
|
||||
/**
|
||||
* \param[in] node_handle The rmw representation of the node that owns this subscription.
|
||||
* \param[in] topic_name Name of the topic to subscribe to.
|
||||
* \param[in] ignore_local_publications True to ignore local publications (unused).
|
||||
*/
|
||||
|
|
@ -107,7 +108,8 @@ public:
|
|||
virtual std::shared_ptr<void> create_message() = 0;
|
||||
|
||||
/// Check if we need to handle the message, and execute the callback if we do.
|
||||
/* \param[in] message Shared pointer to the message to handle.
|
||||
/**
|
||||
* \param[in] message Shared pointer to the message to handle.
|
||||
* \param[in] sender_id Global identifier of the entity that sent this message.
|
||||
*/
|
||||
virtual void handle_message(std::shared_ptr<void> & message, const rmw_gid_t * sender_id) = 0;
|
||||
|
|
@ -144,7 +146,8 @@ public:
|
|||
RCLCPP_SMART_PTR_DEFINITIONS(Subscription);
|
||||
|
||||
/// Default constructor.
|
||||
/* The constructor for a subscription is almost never called directly. Instead, subscriptions
|
||||
/**
|
||||
* The constructor for a subscription is almost never called directly. Instead, subscriptions
|
||||
* should be instantiated through Node::create_subscription.
|
||||
* \param[in] node_handle rmw representation of the node that owns this subscription.
|
||||
* \param[in] topic_name Name of the topic to subscribe to.
|
||||
|
|
@ -168,7 +171,8 @@ public:
|
|||
{}
|
||||
|
||||
/// Support dynamically setting the message memory strategy.
|
||||
/* Behavior may be undefined if called while the subscription could be executing.
|
||||
/**
|
||||
* Behavior may be undefined if called while the subscription could be executing.
|
||||
* \param[in] message_memory_strategy Shared pointer to the memory strategy to set.
|
||||
*/
|
||||
void set_message_memory_strategy(
|
||||
|
|
|
|||
|
|
@ -76,7 +76,8 @@ public:
|
|||
virtual bool is_steady() = 0;
|
||||
|
||||
/// Check if the timer needs to trigger the callback.
|
||||
/* This function expects its caller to immediately trigger the callback after this function,
|
||||
/**
|
||||
* This function expects its caller to immediately trigger the callback after this function,
|
||||
* since it maintains the last time the callback was triggered.
|
||||
* \return True if the timer needs to trigger.
|
||||
*/
|
||||
|
|
@ -100,7 +101,8 @@ public:
|
|||
RCLCPP_SMART_PTR_DEFINITIONS(GenericTimer);
|
||||
|
||||
/// Default constructor.
|
||||
/* \param[in] period The interval at which the timer fires.
|
||||
/**
|
||||
* \param[in] period The interval at which the timer fires.
|
||||
* \param[in] callback User-specified callback function.
|
||||
*/
|
||||
GenericTimer(std::chrono::nanoseconds period, CallbackType callback)
|
||||
|
|
|
|||
|
|
@ -54,9 +54,11 @@ struct sigaction old_action;
|
|||
void (* old_signal_handler)(int) = 0;
|
||||
#endif
|
||||
|
||||
/// When the interrupt signal fires, the signal handler notifies the condition variable to wake up
|
||||
/// and triggers the interrupt guard condition, so that all global threads managed by rclcpp
|
||||
/// are interrupted.
|
||||
/// Handle the interrupt signal.
|
||||
/** When the interrupt signal fires, the signal handler notifies the condition variable to wake up
|
||||
* and triggers the interrupt guard condition, so that all global threads managed by rclcpp
|
||||
* are interrupted.
|
||||
*/
|
||||
void
|
||||
#ifdef HAS_SIGACTION
|
||||
signal_handler(int signal_value, siginfo_t * siginfo, void * context)
|
||||
|
|
@ -106,7 +108,8 @@ namespace utilities
|
|||
{
|
||||
|
||||
/// Initialize communications via the rmw implementation and set up a global signal handler.
|
||||
/* \param[in] argc Number of arguments.
|
||||
/**
|
||||
* \param[in] argc Number of arguments.
|
||||
* \param[in] argv Argument vector. Will eventually be used for passing options to rclcpp.
|
||||
*/
|
||||
void
|
||||
|
|
@ -179,7 +182,8 @@ get_global_sigint_guard_condition()
|
|||
}
|
||||
|
||||
/// Use the global condition variable to block for the specified amount of time.
|
||||
/* \param[in] nanoseconds A std::chrono::duration representing how long to sleep for.
|
||||
/**
|
||||
* \param[in] nanoseconds A std::chrono::duration representing how long to sleep for.
|
||||
* \return True if the condition variable did not timeout.
|
||||
*/
|
||||
bool
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue