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 <[email protected]>

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

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_

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

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
 {