From 163f0700d0df30b58c95a300d255f834a3805b8c Mon Sep 17 00:00:00 2001 From: Michel Hidalgo Date: Tue, 28 Jul 2020 19:03:10 -0300 Subject: [PATCH] Update publisher creation/destruction API documentation. (#252) Signed-off-by: Michel Hidalgo --- rmw/include/rmw/rmw.h | 62 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 56 insertions(+), 6 deletions(-) diff --git a/rmw/include/rmw/rmw.h b/rmw/include/rmw/rmw.h index 49a209b0..6fa1f6e9 100644 --- a/rmw/include/rmw/rmw.h +++ b/rmw/include/rmw/rmw.h @@ -276,14 +276,38 @@ RMW_WARN_UNUSED rmw_publisher_options_t rmw_get_default_publisher_options(void); -/// Create and return an rmw publisher. +/// Create a publisher and return a handle to that publisher. /** - * \TODO(wjwwood): add detailed documentation, adding a not about one of the - * arguments for now. + * This function can fail, and therefore return `NULL`, if: + * - node is not a valid non-null handle for this rmw implementation, + * as returned by `rmw_create_node()` + * - type_support is a not valid non-null message type support, as returned by + * `ROSIDL_GET_MSG_TYPE_SUPPORT()` + * - topic_name is not a valid non-null topic name, according to + * `rmw_validate_full_topic_name()` + * - qos_profile is not a fully specified non-null profile i.e. no UNKNOWN policies + * - publisher_options is not a valid non-null option set, as returned by + * `rmw_get_default_publisher_options()` + * - memory allocation fails during publisher creation + * - an unspecified error occurs * - * The argument `publisher_options` must not be nullptr. + *
+ * Attribute | Adherence + * ------------------ | ------------- + * Allocates Memory | Yes + * Thread-Safe | No + * Uses Atomics | Maybe [1] + * Lock-Free | Maybe [1] + * [1] rmw implementation defined, check the implementation documentation * - * \param[in] publisher_options options for configuring the publisher + * \param[in] node Handle to node with which to register this publisher + * \param[in] type_support Type support for the messages to be published + * \param[in] topic_name Name of the topic to publish to, often a fully qualified + * topic name unless `qos_profile` is configured to avoid ROS namespace conventions + * i.e. to create a native topic publisher + * \param[in] qos_profile QoS policies for this publisher + * \param[in] publisher_options Options to configure this publisher + * \return rmw publisher handle, or `NULL` if there was an error */ RMW_PUBLIC RMW_WARN_UNUSED @@ -292,9 +316,35 @@ rmw_create_publisher( const rmw_node_t * node, const rosidl_message_type_support_t * type_support, const char * topic_name, - const rmw_qos_profile_t * qos_policies, + const rmw_qos_profile_t * qos_profile, const rmw_publisher_options_t * publisher_options); +/// Finalize a given publisher handle, reclaim the resources, and deallocate the publisher handle. +/** + * This function will return early if a logical error, such as `RMW_RET_INVALID_ARGUMENT` + * or `RMW_RET_INCORRECT_RMW_IMPLEMENTATION`, ensues, leaving the given publisher handle unchanged. + * Otherwise, it will proceed despite errors, freeing as many resources as it can, including + * the publisher handle. Usage of a deallocated publisher handle is undefined behavior. + * + * \pre Given node must be the one the publisher was registered with. + * + *
+ * Attribute | Adherence + * ------------------ | ------------- + * Allocates Memory | No + * Thread-Safe | No + * Uses Atomics | Maybe [1] + * Lock-Free | Maybe [1] + * [1] rmw implementation defined, check the implementation documentation + * + * \param[in] node Handle to node with which the given publisher is registered + * \param[in] publisher Handle to publisher to be finalized + * \return `RMW_RET_OK` if successful, or + * \return `RMW_RET_INVALID_ARGUMENT` if node or publisher is `NULL`, or + * \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if node or publisher + * implementation identifier does not match, or + * \return `RMW_RET_ERROR` if an unexpected error occurs. + */ RMW_PUBLIC RMW_WARN_UNUSED rmw_ret_t