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