diff --git a/rmw/CMakeLists.txt b/rmw/CMakeLists.txt index 265b137f..632e32dd 100644 --- a/rmw/CMakeLists.txt +++ b/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" diff --git a/rmw/include/rmw/publisher_options.h b/rmw/include/rmw/publisher_options.h new file mode 100644 index 00000000..ccedea2d --- /dev/null +++ b/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_ diff --git a/rmw/include/rmw/rmw.h b/rmw/include/rmw/rmw.h index 3b0826fe..1335dcbc 100644 --- a/rmw/include/rmw/rmw.h +++ b/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,6 +280,21 @@ 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 * @@ -286,7 +302,8 @@ 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 diff --git a/rmw/include/rmw/subscription_options.h b/rmw/include/rmw/subscription_options.h new file mode 100644 index 00000000..30fb23cd --- /dev/null +++ b/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_ diff --git a/rmw/include/rmw/types.h b/rmw/include/rmw/types.h index de239dfe..b726aacf 100644 --- a/rmw/include/rmw/types.h +++ b/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 diff --git a/rmw/src/publisher_options.c b/rmw/src/publisher_options.c new file mode 100644 index 00000000..4ead9bae --- /dev/null +++ b/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 diff --git a/rmw/src/subscription_options.c b/rmw/src/subscription_options.c new file mode 100644 index 00000000..1b405ba0 --- /dev/null +++ b/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