From 9c15c6436f5e1a54a901977bc4db44b5b0ba85e3 Mon Sep 17 00:00:00 2001 From: Mauro Date: Fri, 2 Oct 2020 16:32:53 +0100 Subject: [PATCH] Add RMW listener APIs add constness Use or discard previous events: Guard conditions Move parentheses Rename Event_callback to ExecutorEventCallback update name Add events support void return on set_events_executor_callback Revert "void return on set_events_executor_callback" Rename ExecutorEventCallback -> EventsExecutorCallback Rename set_events_executor_callback->set_listener_callback Use data types when setting callbacks Move rcutils/executor_event_types.h to rmw/ Add executor_event_types.h rename event types Rename executor_context->callback_context Add APIs documentation Modify doc Rename callback_context->user_data Reorder APIs arguments Add more info on set_listener_callback comments rename rmw_listener_cb_t->rmw_listener_callback_t Add missing comments use void * to pass executor ptr Rework executor callback data Use RMW renamed file Define publisher/subscription event types Signed-off-by: Alberto Soragna --- rmw/include/rmw/event.h | 29 ------ rmw/include/rmw/listener_callback_type.h | 29 ++++++ rmw/include/rmw/rmw.h | 124 ++++++++++++++++++++++- rmw/include/rmw/types.h | 37 +++++++ 4 files changed, 189 insertions(+), 30 deletions(-) create mode 100644 rmw/include/rmw/listener_callback_type.h diff --git a/rmw/include/rmw/event.h b/rmw/include/rmw/event.h index 75db9352..b051dde8 100644 --- a/rmw/include/rmw/event.h +++ b/rmw/include/rmw/event.h @@ -29,35 +29,6 @@ extern "C" #include "rmw/ret_types.h" #include "rmw/visibility_control.h" -/// Define publisher/subscription events -typedef enum rmw_event_type_t -{ - // subscription events - RMW_EVENT_LIVELINESS_CHANGED, - RMW_EVENT_REQUESTED_DEADLINE_MISSED, - RMW_EVENT_REQUESTED_QOS_INCOMPATIBLE, - RMW_EVENT_MESSAGE_LOST, - - // publisher events - RMW_EVENT_LIVELINESS_LOST, - RMW_EVENT_OFFERED_DEADLINE_MISSED, - RMW_EVENT_OFFERED_QOS_INCOMPATIBLE, - - // sentinel value - RMW_EVENT_INVALID -} rmw_event_type_t; - -/// Encapsulate the RMW event implementation, data, and type. -typedef struct RMW_PUBLIC_TYPE rmw_event_t -{ - /// Implementation identifier, used to ensure two different implementations are not being mixed. - const char * implementation_identifier; - /// Data specific to this event type from either the publisher or subscriber. - void * data; - /// The event type that occurred. - rmw_event_type_t event_type; -} rmw_event_t; - /// Return a zero initialized event structure. RMW_PUBLIC RMW_WARN_UNUSED diff --git a/rmw/include/rmw/listener_callback_type.h b/rmw/include/rmw/listener_callback_type.h new file mode 100644 index 00000000..3ec65fd3 --- /dev/null +++ b/rmw/include/rmw/listener_callback_type.h @@ -0,0 +1,29 @@ +// Copyright 2020 Open Source Robotics Foundation, Inc. +// +// 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 RMW__LISTENER_CALLBACK_TYPE_H_ +#define RMW__LISTENER_CALLBACK_TYPE_H_ + +#ifdef __cplusplus +extern "C" +{ +#endif + +typedef void (* rmw_listener_callback_t)(const void * user_data); + +#ifdef __cplusplus +} +#endif + +#endif // RMW__LISTENER_CALLBACK_TYPE_H_ diff --git a/rmw/include/rmw/rmw.h b/rmw/include/rmw/rmw.h index d9714eda..acccd7da 100644 --- a/rmw/include/rmw/rmw.h +++ b/rmw/include/rmw/rmw.h @@ -99,10 +99,11 @@ extern "C" #include "rosidl_runtime_c/sequence_bound.h" #include "rmw/init.h" +#include "rmw/listener_callback_type.h" #include "rmw/macros.h" +#include "rmw/message_sequence.h" #include "rmw/qos_profiles.h" #include "rmw/subscription_options.h" -#include "rmw/message_sequence.h" #include "rmw/types.h" #include "rmw/visibility_control.h" @@ -2790,6 +2791,127 @@ RMW_WARN_UNUSED rmw_ret_t rmw_set_log_severity(rmw_log_severity_t severity); +/// Set callback function of the rmw subscription listener. +/** + * This API sets the callback function which will be called whenever the + * subscription listener is notified about a new message for the subscription. + * The callback may be called from a thread that the rmw implementation + * created, rather than a thread owned by the user, i.e. some thread other + * than user owned threads calling rmw functions such as rmw_wait() or + * rmw_publish(). + * + * \param[in] rmw_subscription The rmw subscription to which the listener belongs + * \param[in] listener_callback The callback to be called by the listener + * \param[in] user_data Used as arg for the call of the listener_callback + * \return `RMW_RET_OK` if callback was set to the listener, or + * \return `RMW_RET_UNSUPPORTED` if the API is not implemented in the dds implementation + */ +RMW_PUBLIC +RMW_WARN_UNUSED +rmw_ret_t +rmw_subscription_set_listener_callback( + rmw_subscription_t * rmw_subscription, + rmw_listener_callback_t listener_callback, + const void * user_data); + +/// Set callback function of the rmw service listener. +/** + * This API sets the callback function which will be called whenever the + * service listener is notified about a service ready. + * The callback may be called from a thread that the rmw implementation + * created, rather than a thread owned by the user, i.e. some thread other + * than user owned threads calling rmw functions such as rmw_wait() or + * rmw_publish(). + * + * \param[in] rmw_service The rmw service to which the listener belongs + * \param[in] listener_callback The callback to be called by the listener + * \param[in] user_data Used as arg for the call of the listener_callback + * \return `RMW_RET_OK` if callback was set to the listener, or + * \return `RMW_RET_UNSUPPORTED` if the API is not implemented in the dds implementation + */ +RMW_PUBLIC +RMW_WARN_UNUSED +rmw_ret_t +rmw_service_set_listener_callback( + rmw_service_t * rmw_service, + rmw_listener_callback_t listener_callback, + const void * user_data); + +/// Set callback function of the rmw client listener. +/** + * This API sets the callback function which will be called whenever the + * client listener is notified about a new client request. + * The callback may be called from a thread that the rmw implementation + * created, rather than a thread owned by the user, i.e. some thread other + * than user owned threads calling rmw functions such as rmw_wait() or + * rmw_publish(). + * + * \param[in] rmw_client The rmw client to which the listener belongs + * \param[in] listener_callback The callback to be called by the listener + * \param[in] user_data Used as arg for the call of the listener_callback + * \return `RMW_RET_OK` if callback was set to the listener, or + * \return `RMW_RET_UNSUPPORTED` if the API is not implemented in the dds implementation + */ +RMW_PUBLIC +RMW_WARN_UNUSED +rmw_ret_t +rmw_client_set_listener_callback( + rmw_client_t * rmw_client, + rmw_listener_callback_t listener_callback, + const void * user_data); + +/// Set callback function of the rmw guard condition listener. +/** + * This API sets the callback function which will be called whenever the + * guard condition listener is notified about the guard condition being triggered. + * The callback may be called from a thread that the rmw implementation + * created, rather than a thread owned by the user, i.e. some thread other + * than user owned threads calling rmw functions such as rmw_wait() or + * rmw_publish(). + * + * \param[in] rmw_guard_condition The rmw guard condition to which the listener belongs + * \param[in] listener_callback The callback to be called by the listener + * \param[in] user_data Used as arg for the call of the listener_callback + * \param[in] use_previous_events Boolean flag to indicate if events happened before the + * set of the listener callback should be taken into account or ignored + * \return `RMW_RET_OK` if callback was set to the listener, or + * \return `RMW_RET_UNSUPPORTED` if the API is not implemented in the dds implementation + */ +RMW_PUBLIC +RMW_WARN_UNUSED +rmw_ret_t +rmw_guard_condition_set_listener_callback( + rmw_guard_condition_t * rmw_guard_condition, + rmw_listener_callback_t listener_callback, + const void * user_data, + bool use_previous_events); + +/// Set callback function of the rmw event listener. +/** + * This API sets the callback function which will be called whenever the + * event listener is notified about a new event, like a QoS change. + * The callback may be called from a thread that the rmw implementation + * created, rather than a thread owned by the user, i.e. some thread other + * than user owned threads calling rmw functions such as rmw_wait() or + * rmw_publish(). + * + * \param[in] rmw_event The rmw event to which the listener belongs + * \param[in] listener_callback The callback to be called by the listener + * \param[in] user_data Used as arg for the call of the listener_callback + * \param[in] use_previous_events Boolean flag to indicate if events happened before the + * set of the listener callback should be taken into account or ignored + * \return `RMW_RET_OK` if callback was set to the listener, or + * \return `RMW_RET_UNSUPPORTED` if the API is not implemented in the dds implementation + */ +RMW_PUBLIC +RMW_WARN_UNUSED +rmw_ret_t +rmw_event_set_listener_callback( + rmw_event_t * rmw_event, + rmw_listener_callback_t listener_callback, + const void * user_data, + bool use_previous_events); + #ifdef __cplusplus } #endif diff --git a/rmw/include/rmw/types.h b/rmw/include/rmw/types.h index fa14c668..1ea78654 100644 --- a/rmw/include/rmw/types.h +++ b/rmw/include/rmw/types.h @@ -207,6 +207,43 @@ typedef struct RMW_PUBLIC_TYPE rmw_guard_condition_t rmw_context_t * context; } rmw_guard_condition_t; +/// Define publisher/subscription events +typedef enum rmw_event_type_t +{ + // subscription events + RMW_EVENT_LIVELINESS_CHANGED, + RMW_EVENT_REQUESTED_DEADLINE_MISSED, + RMW_EVENT_REQUESTED_QOS_INCOMPATIBLE, + RMW_EVENT_MESSAGE_LOST, + + // publisher events + RMW_EVENT_LIVELINESS_LOST, + RMW_EVENT_OFFERED_DEADLINE_MISSED, + RMW_EVENT_OFFERED_QOS_INCOMPATIBLE, + + // sentinel value + RMW_EVENT_INVALID +} rmw_event_type_t; + +/// Define publisher/subscription event types +typedef enum rmw_event_data_type_t +{ + RMW_SUBSCRIBER_EVENT, + RMW_PUBLISHER_EVENT +} rmw_event_data_type_t; + +/// Encapsulate the RMW event implementation, data, and type. +typedef struct RMW_PUBLIC_TYPE rmw_event_t +{ + /// Implementation identifier, used to ensure two different implementations are not being mixed. + const char * implementation_identifier; + /// Data specific to this event type from either the publisher or subscriber. + void * data; + /// The event type that occurred. + rmw_event_type_t event_type; + rmw_event_data_type_t event_data_type; +} rmw_event_t; + /// Allocation of memory for an rmw publisher typedef struct RMW_PUBLIC_TYPE rmw_publisher_allocation_t {