niklas/rclcpp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improved rclcpp docblock (#1127)

Browse source 
* Improved rclcpp docblock

Signed-off-by: ahcorde <ahcorde@gmail.com>

* Improved docblock

Signed-off-by: ahcorde <ahcorde@gmail.com>

* Included feedback

Signed-off-by: ahcorde <ahcorde@gmail.com>

* Added feedback

Signed-off-by: ahcorde <ahcorde@gmail.com>
This commit is contained in:
Alejandro Hernández Cordero 2020-05-28 08:34:29 +02:00 • committed by GitHub
parent e3abe8bf7f
commit 1a48a60a75
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
28 changed files with 393 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

25
rclcpp/include/rclcpp/client.hpp
View file

@ -119,6 +119,7 @@ public:
/// Wait for a service to be ready.
/**
* \param timeout maximum time to wait
* \return `true` if the service is ready and the timeout is not over, `false` otherwise
*/
template<typename RepT = int64_t, typename RatioT = std::milli>
bool
@ -194,6 +195,17 @@ public:
RCLCPP_SMART_PTR_DEFINITIONS(Client)
/// Default constructor.
/**
* The constructor for a Client is almost never called directly.
* Instead, clients should be instantiated through the function
* rclcpp::create_client().
*
* \param[in] node_base NodeBaseInterface pointer that is used in part of the setup.
* \param[in] node_graph The node graph interface of the corresponding node.
* \param[in] service_name Name of the topic to publish to.
* \param[in] client_options options for the subscription.
*/
Client(
rclcpp::node_interfaces::NodeBaseInterface * node_base,
rclcpp::node_interfaces::NodeGraphInterface::SharedPtr node_graph,
@ -248,12 +260,20 @@ public:
return this->take_type_erased_response(&response_out, request_header_out);
}
/// Create a shared pointer with the response type
/**
* \return shared pointer with the response type
*/
std::shared_ptr<void>
create_response() override
{
return std::shared_ptr<void>(new typename ServiceT::Response());
}
/// Create a shared pointer with a rmw_request_id_t
/**
* \return shared pointer with a rmw_request_id_t
*/
std::shared_ptr<rmw_request_id_t>
create_request_header() override
{
@ -262,6 +282,11 @@ public:
return std::shared_ptr<rmw_request_id_t>(new rmw_request_id_t);
}
/// Handle a server response
/**
* \param[in] request_header used to check if the secuence number is valid
* \param[in] response message with the server response
*/
void
handle_response(
std::shared_ptr<rmw_request_id_t> request_header,

6
rclcpp/include/rclcpp/context.hpp
View file

@ -103,6 +103,9 @@ public:
* \param[in] argv argument array which may contain arguments intended for ROS
* \param[in] init_options initialization options for rclcpp and underlying layers
* \throw ContextAlreadyInitialized if called if init is called more than once
* \throws anything rclcpp::exceptions::throw_from_rcl_error can throw.
* \throws std::runtime_error if the global logging configure mutex is NULL
* \throws exceptions::UnknownROSArgsError if there are unknown ROS arguments
*/
RCLCPP_PUBLIC
virtual
@ -263,6 +266,7 @@ public:
* \param[in] wait_set Pointer to the rcl_wait_set_t that will be using the
* resulting guard condition.
* \return Pointer to the guard condition.
* \throws anything rclcpp::exceptions::throw_from_rcl_error can throw.
*/
RCLCPP_PUBLIC
rcl_guard_condition_t *
@ -282,6 +286,8 @@ public:
*
* \param[in] wait_set Pointer to the rcl_wait_set_t that was using the
* resulting guard condition.
* \throws anything rclcpp::exceptions::throw_from_rcl_error can throw.
* \throws std::runtime_error if a nonexistent wait set is trying to release sigint guard condition.
*/
RCLCPP_PUBLIC
void

16
rclcpp/include/rclcpp/event.hpp
View file

@ -29,17 +29,33 @@ class Event
public:
RCLCPP_SMART_PTR_DEFINITIONS_NOT_COPYABLE(Event)
/// Default construct
/**
* Set the default value to false
*/
RCLCPP_PUBLIC
Event();
/// Set the Event state value to true
/**
* \return The state value before the call.
*/
RCLCPP_PUBLIC
bool
set();
/// Get the state value of the Event
/**
* \return the Event state value
*/
RCLCPP_PUBLIC
bool
check();
/// Get the state value of the Event and set to false
/**
* \return the Event state value
*/
RCLCPP_PUBLIC
bool
check_and_clear();

19
rclcpp/include/rclcpp/executor.hpp
View file

@ -88,6 +88,9 @@ public:
add_node(rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node_ptr, bool notify = true);
/// Convenience function which takes Node and forwards NodeBaseInterface.
/**
* \see rclcpp::Executor::add_node
*/
RCLCPP_PUBLIC
virtual void
add_node(std::shared_ptr<rclcpp::Node> node_ptr, bool notify = true);
@ -104,6 +107,9 @@ public:
remove_node(rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node_ptr, bool notify = true);
/// Convenience function which takes Node and forwards NodeBaseInterface.
/**
* \see rclcpp::Executor::remove_node
*/
RCLCPP_PUBLIC
virtual void
remove_node(std::shared_ptr<rclcpp::Node> node_ptr, bool notify = true);
@ -232,7 +238,10 @@ public:
}
/// Cancel any running spin* function, causing it to return.
/* This function can be called asynchonously from any thread. */
/**
* This function can be called asynchonously from any thread.
* \throws std::runtime_error if there is an issue triggering the guard condition
*/
RCLCPP_PUBLIC
void
cancel();
@ -242,6 +251,7 @@ public:
* 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.
* \throws std::runtime_error if memory_strategy is null
*/
RCLCPP_PUBLIC
void
@ -255,8 +265,10 @@ protected:
std::chrono::nanoseconds timeout);
/// 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,
/**
* \param[in] any_exec Union structure that can hold any executable type (timer, subscription,
* service, client).
* \throws std::runtime_error if there is an issue triggering the guard condition
*/
RCLCPP_PUBLIC
void
@ -279,6 +291,9 @@ protected:
static void
execute_client(rclcpp::ClientBase::SharedPtr client);
/**
* \throws std::runtime_error if the wait set can be cleared
*/
RCLCPP_PUBLIC
void
wait_for_work(std::chrono::nanoseconds timeout = std::chrono::nanoseconds(-1));

4
rclcpp/include/rclcpp/executors/multi_threaded_executor.hpp
View file

@ -60,6 +60,10 @@ public:
RCLCPP_PUBLIC
virtual ~MultiThreadedExecutor();
/**
* \sa rclcpp::Executor:spin() for more details
* \throws std::runtime_error when spin() called while already spinning
*/
RCLCPP_PUBLIC
void
spin() override;

1
rclcpp/include/rclcpp/executors/single_threaded_executor.hpp
View file

@ -59,6 +59,7 @@ public:
* the process until canceled.
* It may be interrupt by a call to rclcpp::Executor::cancel() or by ctrl-c
* if the associated context is configured to shutdown on SIGINT.
* \throws std::runtime_error when spin() called while already spinning
*/
RCLCPP_PUBLIC
void

72
rclcpp/include/rclcpp/executors/static_executor_entities_collector.hpp
View file

@ -47,6 +47,13 @@ public:
// Destructor
~StaticExecutorEntitiesCollector();
/// Initialize StaticExecutorEntitiesCollector
/**
* \param p_wait_set A reference to the wait set to be used in the executor
* \param memory_strategy Shared pointer to the memory strategy to set.
* \param executor_guard_condition executor's guard condition
* \throws std::runtime_error if memory strategy is null
*/
RCLCPP_PUBLIC
void
init(
@ -67,16 +74,26 @@ public:
fill_executable_list();
/// Function to reallocate space for entities in the wait set.
/**
* \throws std::runtime_error if wait set couldn't be cleared or resized.
*/
RCLCPP_PUBLIC
void
prepare_wait_set();
/// Function to add_handles_to_wait_set and wait for work and
// block until the wait set is ready or until the timeout has been exceeded.
/**
* block until the wait set is ready or until the timeout has been exceeded.
* \throws std::runtime_error if wait set couldn't be cleared or filled.
* \throws any rcl errors from rcl_wait, \sa rclcpp::exceptions::throw_from_rcl_error()
*/
RCLCPP_PUBLIC
void
refresh_wait_set(std::chrono::nanoseconds timeout = std::chrono::nanoseconds(-1));
/**
* \throws std::runtime_error if it couldn't add guard condition to wait set
*/
RCLCPP_PUBLIC
bool
add_to_wait_set(rcl_wait_set_t * wait_set) override;
@ -85,11 +102,19 @@ public:
size_t
get_number_of_ready_guard_conditions() override;
/**
* \sa rclcpp::Executor::add_node()
* \throw std::runtime_error if node was already added
*/
RCLCPP_PUBLIC
void
add_node(
rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node_ptr);
/**
* \sa rclcpp::Executor::remove_node()
* \throw std::runtime_error if no guard condition is associated with node.
*/
RCLCPP_PUBLIC
bool
remove_node(
@ -105,42 +130,87 @@ public:
bool
is_ready(rcl_wait_set_t * wait_set) override;
/// Return number of timers
/**
* \return number of timers
*/
RCLCPP_PUBLIC
size_t
get_number_of_timers() {return exec_list_.number_of_timers;}
/// Return number of subscriptions
/**
* \return number of subscriptions
*/
RCLCPP_PUBLIC
size_t
get_number_of_subscriptions() {return exec_list_.number_of_subscriptions;}
/// Return number of services
/**
* \return number of services
*/
RCLCPP_PUBLIC
size_t
get_number_of_services() {return exec_list_.number_of_services;}
/// Return number of clients
/**
* \return number of clients
*/
RCLCPP_PUBLIC
size_t
get_number_of_clients() {return exec_list_.number_of_clients;}
/// Return number of waitables
/**
* \return number of waitables
*/
RCLCPP_PUBLIC
size_t
get_number_of_waitables() {return exec_list_.number_of_waitables;}
/** Return a SubscritionBase Sharedptr by index.
* \param[in] i The index of the SubscritionBase
* \return a SubscritionBase shared pointer
* \throws std::out_of_range if the argument is higher than the size of the structrue.
*/
RCLCPP_PUBLIC
rclcpp::SubscriptionBase::SharedPtr
get_subscription(size_t i) {return exec_list_.subscription[i];}
/** Return a TimerBase Sharedptr by index.
* \param[in] i The index of the TimerBase
* \return a TimerBase shared pointer
* \throws std::out_of_range if the argument is higher than the size.
*/
RCLCPP_PUBLIC
rclcpp::TimerBase::SharedPtr
get_timer(size_t i) {return exec_list_.timer[i];}
/** Return a ServiceBase Sharedptr by index.
* \param[in] i The index of the ServiceBase
* \return a ServiceBase shared pointer
* \throws std::out_of_range if the argument is higher than the size.
*/
RCLCPP_PUBLIC
rclcpp::ServiceBase::SharedPtr
get_service(size_t i) {return exec_list_.service[i];}
/** Return a ClientBase Sharedptr by index
* \param[in] i The index of the ClientBase
* \return a ClientBase shared pointer
* \throws std::out_of_range if the argument is higher than the size.
*/
RCLCPP_PUBLIC
rclcpp::ClientBase::SharedPtr
get_client(size_t i) {return exec_list_.client[i];}
/** Return a Waitable Sharedptr by index
* \param[in] i The index of the Waitable
* \return a Waitable shared pointer
* \throws std::out_of_range if the argument is higher than the size.
*/
RCLCPP_PUBLIC
rclcpp::Waitable::SharedPtr
get_waitable(size_t i) {return exec_list_.waitable[i];}

17
rclcpp/include/rclcpp/executors/static_single_threaded_executor.hpp
View file

@ -69,8 +69,11 @@ public:
virtual ~StaticSingleThreadedExecutor();
/// Static executor implementation of spin.
// This function will block until work comes in, execute it, and keep blocking.
// It will only be interrupt by a CTRL-C (managed by the global signal handler).
/**
* This function will block until work comes in, execute it, and keep blocking.
* It will only be interrupted by a CTRL-C (managed by the global signal handler).
* \throws std::runtime_error when spin() called while already spinning
*/
RCLCPP_PUBLIC
void
spin() override;
@ -82,6 +85,8 @@ public:
* \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.
* \throw std::runtime_error if node was already added or if rcl_trigger_guard_condition
* return an error
*/
RCLCPP_PUBLIC
void
@ -90,6 +95,10 @@ public:
bool notify = true) override;
/// Convenience function which takes Node and forwards NodeBaseInterface.
/**
* \throw std::runtime_error if node was already added or if rcl_trigger_guard_condition
* returns an error
*/
RCLCPP_PUBLIC
void
add_node(std::shared_ptr<rclcpp::Node> node_ptr, bool notify = true) override;
@ -100,6 +109,7 @@ public:
* \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.
* \throw std::runtime_error if rcl_trigger_guard_condition returns an error
*/
RCLCPP_PUBLIC
void
@ -108,6 +118,9 @@ public:
bool notify = true) override;
/// Convenience function which takes Node and forwards NodeBaseInterface.
/**
* \throw std::runtime_error if rcl_trigger_guard_condition returns an error
*/
RCLCPP_PUBLIC
void
remove_node(std::shared_ptr<rclcpp::Node> node_ptr, bool notify = true) override;

2
rclcpp/include/rclcpp/expand_topic_or_service_name.hpp
View file

@ -49,6 +49,8 @@ namespace rclcpp
* \throws InvalidServiceNameError if name is invalid and is_service is true
* \throws std::bad_alloc if memory cannot be allocated
* \throws RCLError if an unexpect error occurs
* \throws std::runtime_error if the topic name is unexpectedly valid or,
* if the rcl name is invalid or if the rcl namespace is invalid
*/
RCLCPP_PUBLIC
std::string

2
rclcpp/include/rclcpp/graph_listener.hpp
View file

@ -73,6 +73,8 @@ public:
* This function is thread-safe.
*
* \throws GraphListenerShutdownError if the GraphListener is shutdown
* \throws std::runtime if the parent context was destroyed
* \throws anything rclcpp::exceptions::throw_from_rcl_error can throw.
*/
RCLCPP_PUBLIC
virtual

16
rclcpp/include/rclcpp/init_options.hpp
View file

@ -30,11 +30,21 @@ public:
/// If true, the context will be shutdown on SIGINT by the signal handler (if it was installed).
bool shutdown_on_sigint = true;
/// Constructor which allows you to specify the allocator used within the init options.
/// Constructor
/**
* It allows you to specify the allocator used within the init options.
* \param[in] allocator used allocate memory within the init options
* \throws anything rclcpp::exceptions::throw_from_rcl_error can throw.
*/
RCLCPP_PUBLIC
explicit InitOptions(rcl_allocator_t allocator = rcl_get_default_allocator());
/// Constructor which is initialized by an existing init_options.
/**
* Initialized by an existing init_options.
* \param[in] init_options rcl_init_options_t to initialized
* \throws anything rclcpp::exceptions::throw_from_rcl_error can throw.
*/
RCLCPP_PUBLIC
explicit InitOptions(const rcl_init_options_t & init_options);
@ -62,6 +72,10 @@ public:
~InitOptions();
/// Return the rcl init options.
/**
* \return the rcl init options.
* \throws anything rclcpp::exceptions::throw_from_rcl_error can throw.
*/
RCLCPP_PUBLIC
const rcl_init_options_t *
get_rcl_init_options() const;

10
rclcpp/include/rclcpp/loaned_message.hpp
View file

@ -52,8 +52,9 @@ public:
* However, this user code is ought to be usable even when dynamically linked against
* a middleware which doesn't support message loaning in which case the allocator will be used.
*
* \param pub rclcpp::Publisher instance to which the memory belongs
* \param allocator Allocator instance in case middleware can not allocate messages
* \param[in] pub rclcpp::Publisher instance to which the memory belongs
* \param[in] allocator Allocator instance in case middleware can not allocate messages
* \throws anything rclcpp::exceptions::throw_from_rcl_error can throw.
*/
LoanedMessage(
const rclcpp::PublisherBase & pub,
@ -98,8 +99,9 @@ public:
* However, this user code is ought to be usable even when dynamically linked against
* a middleware which doesn't support message loaning in which case the allocator will be used.
*
* \param pub rclcpp::Publisher instance to which the memory belongs
* \param allocator Allocator instance in case middleware can not allocate messages
* \param[in] pub rclcpp::Publisher instance to which the memory belongs
* \param[in] allocator Allocator instance in case middleware can not allocate messages
* \throws anything rclcpp::exceptions::throw_from_rcl_error can throw.
*/
LoanedMessage(
const rclcpp::PublisherBase * pub,

4
rclcpp/include/rclcpp/memory_strategies.hpp
View file

@ -23,6 +23,10 @@ namespace rclcpp
namespace memory_strategies
{
/// Create a MemoryStrategy sharedPtr
/**
* \return a MemoryStrategy sharedPtr
*/
RCLCPP_PUBLIC
memory_strategy::MemoryStrategy::SharedPtr
create_default_strategy();

3
rclcpp/include/rclcpp/message_info.hpp
View file

@ -30,6 +30,9 @@ public:
MessageInfo() = default;
/// Conversion constructor, which is intentionally not marked as explicit.
/**
* \param[in] rmw_message_info message info to initialize the class
*/
// cppcheck-suppress noExplicitConstructor
MessageInfo(const rmw_message_info_t & rmw_message_info); // NOLINT(runtime/explicit)

42
rclcpp/include/rclcpp/node.hpp
View file

@ -78,6 +78,7 @@ public:
/**
* \param[in] node_name Name of the node.
* \param[in] options Additional options to control creation of the node.
* \throws InvalidNamespaceError if the namespace is invalid
*/
RCLCPP_PUBLIC
explicit Node(
@ -89,6 +90,7 @@ public:
* \param[in] node_name Name of the node.
* \param[in] namespace_ Namespace of the node.
* \param[in] options Additional options to control creation of the node.
* \throws InvalidNamespaceError if the namespace is invalid
*/
RCLCPP_PUBLIC
explicit Node(
@ -122,6 +124,7 @@ public:
/// Get the fully-qualified name of the node.
/**
* The fully-qualified name includes the local namespace and name of the node.
* \return fully-qualified name of the node.
*/
RCLCPP_PUBLIC
const char *
@ -685,6 +688,7 @@ public:
* \throws rclcpp::exceptions::ParameterNotDeclaredException if the
* parameter has not been declared and undeclared parameters are not
* allowed.
* \throws std::runtime_error if the number of described parameters is more than one
*/
RCLCPP_PUBLIC
rcl_interfaces::msg::ParameterDescriptor
@ -707,6 +711,7 @@ public:
* \throws rclcpp::exceptions::ParameterNotDeclaredException if any of the
* parameters have not been declared and undeclared parameters are not
* allowed.
* \throws std::runtime_error if the number of described parameters is more than one
*/
RCLCPP_PUBLIC
std::vector<rcl_interfaces::msg::ParameterDescriptor>
@ -866,14 +871,30 @@ public:
std::vector<std::string>
get_node_names() const;
/// Return a map of existing topic names to list of topic types.
/**
* \return a map of existing topic names to list of topic types.
* \throws std::runtime_error anything that rcl_error can throw
*/
RCLCPP_PUBLIC
std::map<std::string, std::vector<std::string>>
get_topic_names_and_types() const;
/// Return a map of existing service names to list of service types.
/**
* \return a map of existing service names to list of service types.
* \throws std::runtime_error anything that rcl_error can throw
*/
RCLCPP_PUBLIC
std::map<std::string, std::vector<std::string>>
get_service_names_and_types() const;
/// Return the number of publishers that are advertised on a given topic.
/**
* \param[in] topic_name the topic_name on which to count the publishers.
* \return number of publishers that are advertised on a given topic.
* \throws std::runtime_error if publishers could not be counted
*/
RCLCPP_PUBLIC
std::map<std::string, std::vector<std::string>>
get_service_names_and_types_by_node(
@ -884,6 +905,12 @@ public:
size_t
count_publishers(const std::string & topic_name) const;
/// Return the number of subscribers who have created a subscription for a given topic.
/**
* \param[in] topic_name the topic_name on which to count the subscribers.
* \return number of subscribers who have created a subscription for a given topic.
* \throws std::runtime_error if publishers could not be counted
*/
RCLCPP_PUBLIC
size_t
count_subscribers(const std::string & topic_name) const;
@ -953,6 +980,9 @@ public:
/**
* The given Event must be acquire through the get_graph_event() method.
*
* \param[in] event pointer to an Event to wait for
* \param[in] timeout nanoseconds to wait for the Event to change the state
*
* \throws InvalidEventError if the given event is nullptr
* \throws EventNotRegisteredError if the given event was not acquired with
* get_graph_event().
@ -963,14 +993,26 @@ public:
rclcpp::Event::SharedPtr event,
std::chrono::nanoseconds timeout);
/// Get a clock as a non-const shared pointer which is managed by the node.
/**
* \sa rclcpp::node_interfaces::NodeClock::get_clock
*/
RCLCPP_PUBLIC
rclcpp::Clock::SharedPtr
get_clock();
/// Get a clock as a const shared pointer which is managed by the node.
/**
* \sa rclcpp::node_interfaces::NodeClock::get_clock
*/
RCLCPP_PUBLIC
rclcpp::Clock::ConstSharedPtr
get_clock() const;
/// Returns current time from the time source specified by clock_type.
/**
* \sa rclcpp::Clock::now
*/
RCLCPP_PUBLIC
Time
now() const;

3
rclcpp/include/rclcpp/node_options.hpp
View file

@ -77,6 +77,9 @@ public:
* This data structure is created lazily, on the first call to this function.
* Repeated calls will not regenerate it unless one of the input settings
* changed, like arguments, use_global_arguments, or the rcl allocator.
*
* \return a const rcl_node_options_t structure used by the node
* \throws exceptions::UnknownROSArgsError if there are unknown ROS arguments
*/
RCLCPP_PUBLIC
const rcl_node_options_t *

40
rclcpp/include/rclcpp/parameter_client.hpp
View file

@ -46,6 +46,16 @@ class AsyncParametersClient
public:
RCLCPP_SMART_PTR_DEFINITIONS(AsyncParametersClient)
/// Create an async parameters client.
/**
* \param node_base_interface[in] The node base interface of the corresponding node.
* \param node_topics_interface[in] Node topic base interface.
* \param node_graph_interface[in] The node graph interface of the corresponding node.
* \param node_services_interface[in] Node service interface.
* \param remote_node_name[in] (optional) name of the remote node
* \param qos_profile[in] (optional) The rmw qos profile to use to subscribe
* \param group[in] (optional) The async parameter client will be added to this callback group.
*/
RCLCPP_PUBLIC
AsyncParametersClient(
const rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node_base_interface,
@ -56,6 +66,13 @@ public:
const rmw_qos_profile_t & qos_profile = rmw_qos_profile_parameters,
rclcpp::CallbackGroup::SharedPtr group = nullptr);
/// Constructor
/**
* \param node[in] The async paramters client will be added to this node.
* \param remote_node_name[in] (optional) name of the remote node
* \param qos_profile[in] (optional) The rmw qos profile to use to subscribe
* \param group[in] (optional) The async parameter client will be added to this callback group.
*/
RCLCPP_PUBLIC
AsyncParametersClient(
const rclcpp::Node::SharedPtr node,
@ -63,6 +80,13 @@ public:
const rmw_qos_profile_t & qos_profile = rmw_qos_profile_parameters,
rclcpp::CallbackGroup::SharedPtr group = nullptr);
/// Constructor
/**
* \param node[in] The async paramters client will be added to this node.
* \param remote_node_name[in] (optional) name of the remote node
* \param qos_profile[in] (optional) The rmw qos profile to use to subscribe
* \param group[in] (optional) The async parameter client will be added to this callback group.
*/
RCLCPP_PUBLIC
AsyncParametersClient(
rclcpp::Node * node,
@ -159,10 +183,26 @@ public:
options);
}
/// Return if the parameter services are ready.
/**
* This method checks the following services:
* - get parameter
* - get parameter
* - set parameters
* - list parameters
* - describe parameters
*
* \return `true` if the service is ready, `false` otherwise
*/
RCLCPP_PUBLIC
bool
service_is_ready() const;
/// Wait for the services to be ready.
/**
* \param timeout maximum time to wait
* \return `true` if the services are ready and the timeout is not over, `false` otherwise
*/
template<typename RepT = int64_t, typename RatioT = std::milli>
bool
wait_for_service(

31
rclcpp/include/rclcpp/service.hpp
View file

@ -156,6 +156,17 @@ public:
std::shared_ptr<typename ServiceT::Response>)>;
RCLCPP_SMART_PTR_DEFINITIONS(Service)
/// Default constructor.
/**
* The constructor for a Service is almost never called directly.
* Instead, services should be instantiated through the function
* rclcpp::create_service().
*
* \param[in] node_handle NodeBaseInterface pointer that is used in part of the setup.
* \param[in] service_name Name of the topic to publish to.
* \param[in] any_callback User defined callback to call when a client request is received.
* \param[in] service_options options for the subscription.
*/
Service(
std::shared_ptr<rcl_node_t> node_handle,
const std::string & service_name,
@ -219,6 +230,16 @@ public:
#endif
}
/// Default constructor.
/**
* The constructor for a Service is almost never called directly.
* Instead, services should be instantiated through the function
* rclcpp::create_service().
*
* \param[in] node_handle NodeBaseInterface pointer that is used in part of the setup.
* \param[in] service_name Name of the topic to publish to.
* \param[in] any_callback User defined callback to call when a client request is received.
*/
Service(
std::shared_ptr<rcl_node_t> node_handle,
std::shared_ptr<rcl_service_t> service_handle,
@ -244,6 +265,16 @@ public:
#endif
}
/// Default constructor.
/**
* The constructor for a Service is almost never called directly.
* Instead, services should be instantiated through the function
* rclcpp::create_service().
*
* \param[in] node_handle NodeBaseInterface pointer that is used in part of the setup.
* \param[in] service_name Name of the topic to publish to.
* \param[in] any_callback User defined callback to call when a client request is received.
*/
Service(
std::shared_ptr<rcl_node_t> node_handle,
rcl_service_t * service_handle,

10
rclcpp/include/rclcpp/subscription.hpp
View file

@ -94,7 +94,7 @@ public:
* \param[in] callback User defined callback to call when a message is received.
* \param[in] options options for the subscription.
* \param[in] message_memory_strategy The memory strategy to be used for managing message memory.
* \param[in] subscription_topic_statistics pointer to a topic statistics subcription.
* \param[in] subscription_topic_statistics Optional pointer to a topic statistics subcription.
* \throws std::invalid_argument if the QoS is uncompatible with intra-process (if one
* of the following conditions are true: qos_profile.history == RMW_QOS_POLICY_HISTORY_KEEP_ALL,
* qos_profile.depth == 0 or qos_profile.durability != RMW_QOS_POLICY_DURABILITY_VOLATILE).
@ -295,7 +295,9 @@ public:
}
/// Return the borrowed message.
/** \param message message to be returned */
/**
* \param[inout] message message to be returned
*/
void
return_message(std::shared_ptr<void> & message) override
{
@ -303,6 +305,10 @@ public:
message_memory_strategy_->return_message(typed_message);
}
/// Return the borrowed serialized message.
/**
* \param[inout] message serialized message to be returned
*/
void
return_serialized_message(std::shared_ptr<rclcpp::SerializedMessage> & message) override
{

11
rclcpp/include/rclcpp/subscription_base.hpp
View file

@ -110,6 +110,7 @@ public:
* May throw runtime_error when an unexpected error occurs.
*
* \return The actual qos settings.
* \throws std::runtime_error if failed to get qos settings
*/
RCLCPP_PUBLIC
rclcpp::QoS
@ -201,6 +202,10 @@ public:
const rosidl_message_type_support_t &
get_message_type_support_handle() const;
/// Return if the subscription is serialized
/**
* \return `true` if the subscription is serialized, `false` otherwise
*/
RCLCPP_PUBLIC
bool
is_serialized() const;
@ -232,7 +237,11 @@ public:
uint64_t intra_process_subscription_id,
IntraProcessManagerWeakPtr weak_ipm);
/// Return the waitable for intra-process, or nullptr if intra-process is not setup.
/// Return the waitable for intra-process
/**
* \return the waitable sharedpointer for intra-process, or nullptr if intra-process is not setup.
* \throws std::runtime_error if the intra process manager is destroyed
*/
RCLCPP_PUBLIC
rclcpp::Waitable::SharedPtr
get_intra_process_waitable() const;

6
rclcpp/include/rclcpp/subscription_factory.hpp
View file

@ -64,6 +64,12 @@ struct SubscriptionFactory
};
/// Return a SubscriptionFactory setup to create a SubscriptionT<MessageT, AllocatorT>.
/**
* \param[in] callback The user-defined callback function to receive a message
* \param[in] options Additional options for the creation of the Subscription.
* \param[in] msg_mem_strat The message memory strategy to use for allocating messages.
* \param[in] subscription_topic_Optinal stats callback for topic_statistics
*/
template<
typename MessageT,
typename CallbackT,

39
rclcpp/include/rclcpp/time.hpp
View file

@ -40,6 +40,7 @@ public:
* \param seconds part of the time in seconds since time epoch
* \param nanoseconds part of the time in nanoseconds since time epoch
* \param clock_type clock type
* \throws std::runtime_error if seconds are negative
*/
RCLCPP_PUBLIC
Time(int32_t seconds, uint32_t nanoseconds, rcl_clock_type_t clock_type = RCL_SYSTEM_TIME);
@ -60,6 +61,7 @@ public:
/**
* \param time_msg builtin_interfaces time message to copy
* \param clock_type clock type
* \throws std::runtime_error if seconds are negative
*/
RCLCPP_PUBLIC
Time(
@ -82,6 +84,9 @@ public:
RCLCPP_PUBLIC
operator builtin_interfaces::msg::Time() const;
/**
* \throws std::runtime_error if seconds are negative
*/
RCLCPP_PUBLIC
Time &
operator=(const Time & rhs);
@ -90,6 +95,9 @@ public:
Time &
operator=(const builtin_interfaces::msg::Time & time_msg);
/**
* \throws std::runtime_error if the time sources are different
*/
RCLCPP_PUBLIC
bool
operator==(const rclcpp::Time & rhs) const;
@ -98,38 +106,66 @@ public:
bool
operator!=(const rclcpp::Time & rhs) const;
/**
* \throws std::runtime_error if the time sources are different
*/
RCLCPP_PUBLIC
bool
operator<(const rclcpp::Time & rhs) const;
/**
* \throws std::runtime_error if the time sources are different
*/
RCLCPP_PUBLIC
bool
operator<=(const rclcpp::Time & rhs) const;
/**
* \throws std::runtime_error if the time sources are different
*/
RCLCPP_PUBLIC
bool
operator>=(const rclcpp::Time & rhs) const;
/**
* \throws std::runtime_error if the time sources are different
*/
RCLCPP_PUBLIC
bool
operator>(const rclcpp::Time & rhs) const;
/**
* \throws std::overflow_error if addition leads to overflow
*/
RCLCPP_PUBLIC
Time
operator+(const rclcpp::Duration & rhs) const;
/**
* \throws std::runtime_error if the time sources are different
* \throws std::overflow_error if addition leads to overflow
*/
RCLCPP_PUBLIC
Duration
operator-(const rclcpp::Time & rhs) const;
/**
* \throws std::overflow_error if addition leads to overflow
*/
RCLCPP_PUBLIC
Time
operator-(const rclcpp::Duration & rhs) const;
/**
* \throws std::overflow_error if addition leads to overflow
*/
RCLCPP_PUBLIC
Time &
operator+=(const rclcpp::Duration & rhs);
/**
* \throws std::overflow_error if addition leads to overflow
*/
RCLCPP_PUBLIC
Time &
operator-=(const rclcpp::Duration & rhs);
@ -174,6 +210,9 @@ private:
friend Clock; // Allow clock to manipulate internal data
};
/**
* \throws std::overflow_error if addition leads to overflow
*/
Time
operator+(const rclcpp::Duration & lhs, const rclcpp::Time & rhs);

1
rclcpp/include/rclcpp/time_source.hpp
View file

@ -87,6 +87,7 @@ public:
/// Attach a clock to the time source to be updated
/**
* \param[in] clock to attach to the time source
* \throws std::invalid_argument the time source must be a RCL_ROS_TIME otherwise throws an exception
*/
RCLCPP_PUBLIC

10
rclcpp/include/rclcpp/timer.hpp
View file

@ -100,7 +100,10 @@ public:
get_timer_handle();
/// Check how long the timer has until its next scheduled callback.
/** \return A std::chrono::duration representing the relative time until the next callback. */
/**
* \return A std::chrono::duration representing the relative time until the next callback.
* \throws std::runtime_error if the rcl_timer_get_time_until_next_call returns a failure
*/
RCLCPP_PUBLIC
std::chrono::nanoseconds
time_until_trigger();
@ -114,6 +117,7 @@ public:
* 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.
* \throws std::runtime_error if it failed to check timer
*/
RCLCPP_PUBLIC
bool is_ready();
@ -185,6 +189,10 @@ public:
cancel();
}
/**
* \sa rclcpp::TimerBase::execute_callback
* \throws std::runtime_error if it failed to notify timer that callback occurred
*/
void
execute_callback() override
{

1
rclcpp/include/rclcpp/topic_statistics/subscription_topic_statistics.hpp
View file

@ -75,6 +75,7 @@ public:
* topic source
* \param publisher instance constructed by the node in order to publish statistics data.
* This class owns the publisher.
* \throws std::invalid_argument if publisher pointer is nullptr
*/
SubscriptionTopicStatistics(
const std::string & node_name,

9
rclcpp/include/rclcpp/utilities.hpp
View file

@ -136,7 +136,7 @@ remove_ros_arguments(int argc, char const * const argv[]);
* If nullptr is given for the context, then the global context is used, i.e.
* the context initialized by rclcpp::init().
*
* \param[in] context Check for shutdown of this Context.
* \param[in] context Optional check for shutdown of this Context.
* \return true if shutdown has been called, false otherwise
*/
RCLCPP_PUBLIC
@ -150,7 +150,7 @@ ok(rclcpp::Context::SharedPtr context = nullptr);
*
* Deprecated, as it is no longer different from rcl_ok().
*
* \param[in] context Check for initialization of this Context.
* \param[in] context Optional check for initialization of this Context.
* \return true if the context is initialized, and false otherwise
*/
[[deprecated("use the function ok() instead, which has the same usage.")]]
@ -168,7 +168,8 @@ is_initialized(rclcpp::Context::SharedPtr context = nullptr);
* This will also cause the "on_shutdown" callbacks to be called.
*
* \sa rclcpp::Context::shutdown()
* \param[in] context to be shutdown
* \param[in] context Optional to be shutdown
* \param[in] reason Optional string passed to the context shutdown method
* \return true if shutdown was successful, false if context was already shutdown
*/
RCLCPP_PUBLIC
@ -206,7 +207,7 @@ on_shutdown(std::function<void()> callback, rclcpp::Context::SharedPtr context =
* the context initialized by rclcpp::init().
*
* \param[in] nanoseconds A std::chrono::duration representing how long to sleep for.
* \param[in] context which may interrupt this sleep
* \param[in] context Optional which may interrupt this sleep
* \return true if the condition variable did not timeout.
*/
RCLCPP_PUBLIC

9
rclcpp/include/rclcpp/wait_result.hpp
View file

@ -58,6 +58,7 @@ public:
/**
* \param[in] wait_set A reference to the wait set, which this class
* will keep for the duration of its lifetime.
* \return a WaitResult from a "ready" result.
*/
static
WaitResult
@ -90,6 +91,10 @@ public:
}
/// Return the rcl wait set.
/**
* \return const rcl wait set.
* \throws std::runtime_error if the class cannot access wait set when the result was not ready
*/
const WaitSetT &
get_wait_set() const
{
@ -102,6 +107,10 @@ public:
}
/// Return the rcl wait set.
/**
* \return rcl wait set.
* \throws std::runtime_error if the class cannot access wait set when the result was not ready
*/
WaitSetT &
get_wait_set()
{

3
rclcpp/include/rclcpp/wait_set_template.hpp
View file

@ -643,7 +643,8 @@ public:
* when time_to_wait is < 0, or
* \returns Empty if the wait set is empty, avoiding the possibility of
* waiting indefinitely on an empty wait set.
* \throws rclcpp::exceptions::RCLError on unhandled rcl errors
* \throws rclcpp::exceptions::RCLError on unhandled rcl errors or,
* \throws std::runtime_error if unknown WaitResultKind
*/
template<class Rep = int64_t, class Period = std::milli>
RCUTILS_WARN_UNUSED