From 511496bb83064c4702b6e540abab0b05ac4ae15b Mon Sep 17 00:00:00 2001 From: Mauro Date: Fri, 2 Oct 2020 16:32:53 +0100 Subject: [PATCH 1/7] 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 e8643b01..d6fe5c66 100644 --- a/rmw/include/rmw/types.h +++ b/rmw/include/rmw/types.h @@ -244,6 +244,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 { From 70686b3e75506607b18e772c95992ffe99c0b5a7 Mon Sep 17 00:00:00 2001 From: Mauro Passerino Date: Fri, 12 Mar 2021 10:38:59 -0300 Subject: [PATCH 2/7] Restore event data types Signed-off-by: Mauro Passerino --- rmw/include/rmw/event.h | 37 +++++++++++++++++++++++++++++++++++++ rmw/include/rmw/rmw.h | 1 + rmw/include/rmw/types.h | 37 ------------------------------------- 3 files changed, 38 insertions(+), 37 deletions(-) diff --git a/rmw/include/rmw/event.h b/rmw/include/rmw/event.h index b051dde8..8857fb60 100644 --- a/rmw/include/rmw/event.h +++ b/rmw/include/rmw/event.h @@ -29,6 +29,43 @@ 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; + +/// 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; + /// Return a zero initialized event structure. RMW_PUBLIC RMW_WARN_UNUSED diff --git a/rmw/include/rmw/rmw.h b/rmw/include/rmw/rmw.h index acccd7da..09038bd6 100644 --- a/rmw/include/rmw/rmw.h +++ b/rmw/include/rmw/rmw.h @@ -98,6 +98,7 @@ extern "C" #include "rosidl_runtime_c/service_type_support_struct.h" #include "rosidl_runtime_c/sequence_bound.h" +#include "rmw/event.h" #include "rmw/init.h" #include "rmw/listener_callback_type.h" #include "rmw/macros.h" diff --git a/rmw/include/rmw/types.h b/rmw/include/rmw/types.h index d6fe5c66..e8643b01 100644 --- a/rmw/include/rmw/types.h +++ b/rmw/include/rmw/types.h @@ -244,43 +244,6 @@ 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 { From d3eb90f0cddf5d25f9aab28ccce71824a3572343 Mon Sep 17 00:00:00 2001 From: Mauro Passerino Date: Tue, 23 Mar 2021 17:37:57 -0300 Subject: [PATCH 3/7] remove event_data_type Signed-off-by: Mauro Passerino --- rmw/include/rmw/event.h | 8 -------- 1 file changed, 8 deletions(-) diff --git a/rmw/include/rmw/event.h b/rmw/include/rmw/event.h index 8857fb60..75db9352 100644 --- a/rmw/include/rmw/event.h +++ b/rmw/include/rmw/event.h @@ -47,13 +47,6 @@ typedef enum rmw_event_type_t 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 { @@ -63,7 +56,6 @@ typedef struct RMW_PUBLIC_TYPE rmw_event_t void * data; /// The event type that occurred. rmw_event_type_t event_type; - rmw_event_data_type_t event_data_type; } rmw_event_t; /// Return a zero initialized event structure. From f6265722955554f2f1d29b4f8bccc0bb520bec83 Mon Sep 17 00:00:00 2001 From: Mauro Passerino Date: Wed, 24 Mar 2021 16:53:52 -0300 Subject: [PATCH 4/7] Remove use_previous_event Signed-off-by: Mauro Passerino --- rmw/include/rmw/rmw.h | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/rmw/include/rmw/rmw.h b/rmw/include/rmw/rmw.h index 09038bd6..f1d8ed79 100644 --- a/rmw/include/rmw/rmw.h +++ b/rmw/include/rmw/rmw.h @@ -2873,8 +2873,6 @@ rmw_client_set_listener_callback( * \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 */ @@ -2884,8 +2882,7 @@ 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); + const void * user_data); /// Set callback function of the rmw event listener. /** @@ -2899,8 +2896,6 @@ rmw_guard_condition_set_listener_callback( * \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 */ @@ -2910,8 +2905,7 @@ 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); + const void * user_data); #ifdef __cplusplus } From e06d3f4788d551ede9c96222dca87ae5805d029f Mon Sep 17 00:00:00 2001 From: Mauro Passerino Date: Thu, 25 Mar 2021 11:44:54 -0300 Subject: [PATCH 5/7] Add num_events arg Signed-off-by: Mauro Passerino --- rmw/include/rmw/listener_callback_type.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rmw/include/rmw/listener_callback_type.h b/rmw/include/rmw/listener_callback_type.h index 3ec65fd3..53a5cad2 100644 --- a/rmw/include/rmw/listener_callback_type.h +++ b/rmw/include/rmw/listener_callback_type.h @@ -1,4 +1,4 @@ -// Copyright 2020 Open Source Robotics Foundation, Inc. +// Copyright 2021 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. @@ -20,7 +20,7 @@ extern "C" { #endif -typedef void (* rmw_listener_callback_t)(const void * user_data); +typedef void (* rmw_listener_callback_t)(const void * user_data, size_t num_events); #ifdef __cplusplus } From 906fa07a22865737a55fa63a5001e2568e873551 Mon Sep 17 00:00:00 2001 From: Mauro Passerino Date: Wed, 31 Mar 2021 17:54:20 -0300 Subject: [PATCH 6/7] Remove guard condition listener Signed-off-by: Mauro Passerino --- rmw/include/rmw/rmw.h | 23 ----------------------- 1 file changed, 23 deletions(-) diff --git a/rmw/include/rmw/rmw.h b/rmw/include/rmw/rmw.h index f1d8ed79..a1151690 100644 --- a/rmw/include/rmw/rmw.h +++ b/rmw/include/rmw/rmw.h @@ -2861,29 +2861,6 @@ rmw_client_set_listener_callback( 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 - * \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); - /// Set callback function of the rmw event listener. /** * This API sets the callback function which will be called whenever the From 94923368144bd7c96ab9674d112f94f3c77ba3d7 Mon Sep 17 00:00:00 2001 From: William Woodall Date: Thu, 1 Apr 2021 20:59:36 -0700 Subject: [PATCH 7/7] refactor to remove listener term Signed-off-by: William Woodall --- rmw/include/rmw/event_callback_type.h | 52 +++++++++ rmw/include/rmw/listener_callback_type.h | 29 ----- rmw/include/rmw/rmw.h | 132 +++++++++++++++-------- 3 files changed, 142 insertions(+), 71 deletions(-) create mode 100644 rmw/include/rmw/event_callback_type.h delete mode 100644 rmw/include/rmw/listener_callback_type.h diff --git a/rmw/include/rmw/event_callback_type.h b/rmw/include/rmw/event_callback_type.h new file mode 100644 index 00000000..8833b49f --- /dev/null +++ b/rmw/include/rmw/event_callback_type.h @@ -0,0 +1,52 @@ +// Copyright 2021 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__EVENT_CALLBACK_TYPE_H_ +#define RMW__EVENT_CALLBACK_TYPE_H_ + +#include + +#ifdef __cplusplus +extern "C" +{ +#endif + +/// Common event callback type signature. +/** + * Event callbacks of this type can be called in various scenarios, e.g. + * data becomes available on a subscription, a QoS event has occurred, or + * something similar. + * + * The user_data argument is given by the user when registering the callback, + * and is given back to the callback each time so it can have associated, + * user-defined state. + * + * The number_of_events argument indicates the number of events since the + * callback was called. + * This is most often 1, but can be > 1 when events occur before the callback + * is registered. + * It should never be 0. + * + * \sa rmw_subscription_set_on_new_message_callback() + * \sa rmw_service_set_on_new_request_callback() + * \sa rmw_client_set_on_new_response_callback() + * \sa rmw_event_set_callback() + */ +typedef void (* rmw_event_callback_t)(const void * user_data, size_t number_of_events); + +#ifdef __cplusplus +} +#endif + +#endif // RMW__EVENT_CALLBACK_TYPE_H_ diff --git a/rmw/include/rmw/listener_callback_type.h b/rmw/include/rmw/listener_callback_type.h deleted file mode 100644 index 53a5cad2..00000000 --- a/rmw/include/rmw/listener_callback_type.h +++ /dev/null @@ -1,29 +0,0 @@ -// Copyright 2021 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, size_t num_events); - -#ifdef __cplusplus -} -#endif - -#endif // RMW__LISTENER_CALLBACK_TYPE_H_ diff --git a/rmw/include/rmw/rmw.h b/rmw/include/rmw/rmw.h index a1151690..9c206b08 100644 --- a/rmw/include/rmw/rmw.h +++ b/rmw/include/rmw/rmw.h @@ -100,7 +100,7 @@ extern "C" #include "rmw/event.h" #include "rmw/init.h" -#include "rmw/listener_callback_type.h" +#include "rmw/event_callback_type.h" #include "rmw/macros.h" #include "rmw/message_sequence.h" #include "rmw/qos_profiles.h" @@ -2770,8 +2770,8 @@ rmw_compare_gids_equal(const rmw_gid_t * gid1, const rmw_gid_t * gid2, bool * re * \param[out] is_available * set to true if there is a service server available, else false * \return `RMW_RET_OK` if node the check was made successfully, or - * \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if the `publisher` implementation - * identifier does not match this implementation, or + * \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if the implementation + * identifier for any arguments does not match this implementation, or * \return `RMW_RET_ERROR` if an unspecified error occurs. */ RMW_PUBLIC @@ -2792,96 +2792,144 @@ RMW_WARN_UNUSED rmw_ret_t rmw_set_log_severity(rmw_log_severity_t severity); -/// Set callback function of the rmw subscription listener. +/// Set the on new message callback function for the subscription. /** - * This API sets the callback function which will be called whenever the - * subscription listener is notified about a new message for the subscription. + * This API sets the callback function to be called whenever the + * subscription is notified about a new message. + * + * This callback is called for each new message received by the subscription. + * If messages arrive before the callback is registered, the number_of_events + * argument given to the callback may be > 1. + * * 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 + * This function is thread-safe. + * This is required of the rmw implementation because the callback may be called + * from any middleware thread, and this function could be called by the user + * at any time. + * + * \param[in] subscription The subscription on which to set the callback + * \param[in] callback The callback to be called when new messages arrive + * \param[in] user_data Given to the callback when called later, may be NULL + * \return `RMW_RET_OK` if successful, or + * \return `RMW_RET_INVALID_ARGUMENT` if `subscription` or `callback` is NULL, 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, +rmw_subscription_set_on_new_message_callback( + rmw_subscription_t * subscription, + rmw_event_callback_t callback, const void * user_data); -/// Set callback function of the rmw service listener. +/// Set the on new request callback function for the service. /** - * This API sets the callback function which will be called whenever the - * service listener is notified about a service ready. + * This API sets the callback function to be called whenever the + * service is notified about a new request. + * + * This callback is called for each new request received by the service. + * If requests arrive before the callback is registered, the number_of_events + * argument given to the callback may be > 1. + * * 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(). + * rmw_send_request(). + * + * This function is thread-safe. + * This is required of the rmw implementation because the callback may be called + * from any middleware thread, and this function could be called by the user + * at any time. * - * \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 + * \param[in] service The service on which to set the callback + * \param[in] callback The callback to be called when new requests arrive + * \param[in] user_data Given to the callback when called later, may be NULL * \return `RMW_RET_OK` if callback was set to the listener, or + * \return `RMW_RET_INVALID_ARGUMENT` if `service` or `callback` is NULL, 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, +rmw_service_set_on_new_request_callback( + rmw_service_t * service, + rmw_event_callback_t callback, const void * user_data); -/// Set callback function of the rmw client listener. +/// Set the on new response callback function for the client. /** - * This API sets the callback function which will be called whenever the - * client listener is notified about a new client request. + * This API sets the callback function to be called whenever the + * client is notified about a new response. + * + * This callback is called for each new response received by the client. + * If responses arrive before the callback is registered, the number_of_events + * argument given to the callback may be > 1. + * * 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(). + * rmw_take_response(). * - * \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 + * This function is thread-safe. + * This is required of the rmw implementation because the callback may be called + * from any middleware thread, and this function could be called by the user + * at any time. + * + * \param[in] client The client on which to set the callback + * \param[in] callback The callback to be called when new responses arrive + * \param[in] user_data Given to the callback when called later, may be NULL * \return `RMW_RET_OK` if callback was set to the listener, or + * \return `RMW_RET_INVALID_ARGUMENT` if `client` or `callback` is NULL, 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, +rmw_client_set_on_new_response_callback( + rmw_client_t * client, + rmw_event_callback_t callback, const void * user_data); -/// Set callback function of the rmw event listener. +/// Set the callback function for the event. /** - * This API sets the callback function which will be called whenever the - * event listener is notified about a new event, like a QoS change. + * This API sets the callback function to be called whenever the + * event is notified about a new instance of the event. + * + * For example, this could be called when incompatible QoS is detected, or + * a deadline is missed, or any other QoS event. + * + * This callback is called for each new event that occurs for this rmw_event_t + * instance. + * If events occur before the callback is registered, the number_of_events + * argument given to the callback may be > 1. + * * 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 + * This function is thread-safe. + * This is required of the rmw implementation because the callback may be called + * from any middleware thread, and this function could be called by the user + * at any time. + * + * \param[in] event The event on which to set the callback + * \param[in] callback The callback to be called when new events occur + * \param[in] user_data Given to the callback when called later, may be NULL * \return `RMW_RET_OK` if callback was set to the listener, or + * \return `RMW_RET_INVALID_ARGUMENT` if `event` or `callback` is NULL, 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, +rmw_event_set_callback( + rmw_event_t * event, + rmw_event_callback_t callback, const void * user_data); #ifdef __cplusplus