add pub/sub option structures to support rmw specific payload feature (…

…#187)

* add pub/sub option structures to support rmw specific payload feature

Signed-off-by: William Woodall <william@osrfoundation.org>

* link to design document in TODO

Signed-off-by: William Woodall <william@osrfoundation.org>

rmw/CMakeLists.txt

@@ -31,7 +31,9 @@ set(rmw_sources
   "src/init.c"
   "src/init_options.c"
   "src/names_and_types.c"
+  "src/publisher_options.c"
   "src/sanity_checks.c"
+  "src/subscription_options.c"
   "src/node_security_options.c"
   "src/validate_full_topic_name.c"
   "src/validate_namespace.c"

rmw/include/rmw/publisher_options.h

@@ -0,0 +1,37 @@
+// Copyright 2019 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__PUBLISHER_OPTIONS_H_
+#define RMW__PUBLISHER_OPTIONS_H_
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+#include "rmw/types.h"
+
+// For now, the rmw_publisher_options_t type is still defined in "rmw/types.h".
+
+/// Return a rmw_publisher_options_t initialized with default values.
+RMW_PUBLIC
+RMW_WARN_UNUSED
+rmw_publisher_options_t
+rmw_get_default_publisher_options(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // RMW__PUBLISHER_OPTIONS_H_

rmw/include/rmw/rmw.h

@@ -96,6 +96,7 @@ extern "C"
 #include "rmw/init.h"
 #include "rmw/macros.h"
 #include "rmw/qos_profiles.h"
+#include "rmw/subscription_options.h"
 #include "rmw/types.h"
 #include "rmw/visibility_control.h"
 
@@ -279,14 +280,30 @@ rmw_ret_t
 rmw_fini_publisher_allocation(
   rmw_publisher_allocation_t * allocation);
 
+/// Return a rmw_publisher_options_t initialized with default values.
+RMW_PUBLIC
+RMW_WARN_UNUSED
+rmw_publisher_options_t
+rmw_get_default_publisher_options(void);
+
+/// Create and return an rmw publisher.
+/**
+ * \TODO(wjwwood): add detailed documentation, adding a not about one of the
+ *   arguments for now.
+ *
+ * The argument `publisher_options` must not be nullptr.
+ *
+ * \param[in] publisher_options options for configuring the publisher
+ */
 RMW_PUBLIC
 RMW_WARN_UNUSED
 rmw_publisher_t *
 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_policies,
+  const rmw_publisher_options_t * publisher_options);
 
 RMW_PUBLIC
 RMW_WARN_UNUSED
@@ -506,6 +523,15 @@ rmw_ret_t
 rmw_fini_subscription_allocation(
   rmw_subscription_allocation_t * allocation);
 
+/// Create and return an rmw subscription.
+/**
+ * \TODO(wjwwood): add detailed documentation, adding a not about one of the
+ *   arguments for now.
+ *
+ * The argument `subscription_options` must not be nullptr.
+ *
+ * \param[in] subscription_options options for configuring the subscription
+ */
 RMW_PUBLIC
 RMW_WARN_UNUSED
 rmw_subscription_t *
@@ -514,7 +540,7 @@ rmw_create_subscription(
   const rosidl_message_type_support_t * type_support,
   const char * topic_name,
   const rmw_qos_profile_t * qos_policies,
-  bool ignore_local_publications);
+  const rmw_subscription_options_t * subscription_options);
 
 RMW_PUBLIC
 RMW_WARN_UNUSED

rmw/include/rmw/subscription_options.h

@@ -0,0 +1,37 @@
+// Copyright 2019 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__SUBSCRIPTION_OPTIONS_H_
+#define RMW__SUBSCRIPTION_OPTIONS_H_
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+#include "rmw/types.h"
+
+// For now, the rmw_subscription_options_t type is still defined in "rmw/types.h".
+
+/// Return a rmw_subscription_options_t initialized with default values.
+RMW_PUBLIC
+RMW_WARN_UNUSED
+rmw_subscription_options_t
+rmw_get_default_subscription_options(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // RMW__SUBSCRIPTION_OPTIONS_H_

rmw/include/rmw/types.h

@@ -45,18 +45,82 @@ typedef struct RMW_PUBLIC_TYPE rmw_node_t
   rmw_context_t * context;
 } rmw_node_t;
 
+/// Options that can be used to configure the creation of a publisher in rmw.
+typedef struct RMW_PUBLIC_TYPE rmw_publisher_options_t
+{
+  /// Used to pass rmw implementation specific resources during publisher creation.
+  /**
+   * This field is type erased (rather than forward declared) because it will
+   * usually be a non-owned reference to an language specific object, e.g.
+   * C++ it may be a polymorphic class that only the rmw implementation can use.
+   *
+   * The resource pointed to here needs to outlive this options structure, and
+   * any rmw_publisher objects that are created using it, as they copy this
+   * structure and may use this payload throughout their lifetime.
+   */
+  void * rmw_specific_publisher_payload;
+} rmw_publisher_options_t;
+
 typedef struct RMW_PUBLIC_TYPE rmw_publisher_t
 {
   const char * implementation_identifier;
   void * data;
   const char * topic_name;
+  /// Publisher options.
+  /**
+   * The options structure passed to rmw_create_publisher() should be
+   * assigned to this field by the rmw implementation.
+   * The fields should not be modified after creation, but
+   * the contents of the options structure may or may not be const, i.e.
+   * shallow const-ness.
+   * This field is not marked const to avoid any const casting during setup.
+   */
+  rmw_publisher_options_t options;
 } rmw_publisher_t;
 
+/// Options that can be used to configure the creation of a subscription in rmw.
+typedef struct RMW_PUBLIC_TYPE rmw_subscription_options_t
+{
+  /// Used to pass rmw implementation specific resources during subscription creation.
+  /**
+   * All the same details and restrictions of this field in
+   * rmw_publisher_options_t apply to this struct as well.
+   *
+   * \sa rmw_publisher_options_t.rmw_specific_publisher_payload
+   */
+  void * rmw_specific_subscription_payload;
+
+  /// If true then the middleware should not deliver data from local publishers.
+  /**
+   * This setting is most often used when data should only be received from
+   * remote nodes, especially to avoid "double delivery" when both intra- and
+   * inter- process communication is taking place.
+   *
+   * \TODO(wjwwood): nail this down when participant mapping is sorted out.
+   *   See: https://github.com/ros2/design/pull/250
+   *
+   * The definition of local is somewhat vague at the moment.
+   * Right now it means local to the node, and that definition works best, but
+   * may become more complicated when/if participants map to a context instead.
+   */
+  bool ignore_local_publications;
+} rmw_subscription_options_t;
+
 typedef struct RMW_PUBLIC_TYPE rmw_subscription_t
 {
   const char * implementation_identifier;
   void * data;
   const char * topic_name;
+  /// Subscription options.
+  /**
+   * The options structure passed to rmw_create_subscription() should be
+   * assigned to this field by the rmw implementation.
+   * The fields should not be modified after creation, but
+   * the contents of the options structure may or may not be const, i.e.
+   * shallow const-ness.
+   * This field is not marked const to avoid any const casting during setup.
+   */
+  rmw_subscription_options_t options;
 } rmw_subscription_t;
 
 typedef struct RMW_PUBLIC_TYPE rmw_service_t

rmw/src/publisher_options.c

@@ -0,0 +1,33 @@
+// Copyright 2019 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.
+
+#include "rmw/publisher_options.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+rmw_publisher_options_t
+rmw_get_default_publisher_options(void)
+{
+  rmw_publisher_options_t publisher_options = {
+    .rmw_specific_publisher_payload = NULL,
+  };
+  return publisher_options;
+}
+
+#ifdef __cplusplus
+}
+#endif

rmw/src/subscription_options.c

@@ -0,0 +1,34 @@
+// Copyright 2019 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.
+
+#include "rmw/subscription_options.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+rmw_subscription_options_t
+rmw_get_default_subscription_options(void)
+{
+  rmw_subscription_options_t subscription_options = {
+    .rmw_specific_subscription_payload = NULL,
+    .ignore_local_publications = false,
+  };
+  return subscription_options;
+}
+
+#ifdef __cplusplus
+}
+#endif