From c5af0ee8c7acd50e5edfad32985c8a715f620fc5 Mon Sep 17 00:00:00 2001 From: William Woodall Date: Mon, 19 Nov 2018 16:49:23 -0600 Subject: [PATCH] refactor init_options into its own files Signed-off-by: William Woodall --- rmw/CMakeLists.txt | 1 + rmw/include/rmw/init.h | 49 +++------- rmw/include/rmw/init_options.h | 159 +++++++++++++++++++++++++++++++++ rmw/src/init.c | 4 +- rmw/src/init_options.c | 36 ++++++++ 5 files changed, 208 insertions(+), 41 deletions(-) create mode 100644 rmw/include/rmw/init_options.h create mode 100644 rmw/src/init_options.c diff --git a/rmw/CMakeLists.txt b/rmw/CMakeLists.txt index 4d64da44..cf643706 100644 --- a/rmw/CMakeLists.txt +++ b/rmw/CMakeLists.txt @@ -28,6 +28,7 @@ set(rmw_sources "src/allocators.c" "src/convert_rcutils_ret_to_rmw_ret.c" "src/init.c" + "src/init_options.c" "src/names_and_types.c" "src/sanity_checks.c" "src/node_security_options.c" diff --git a/rmw/include/rmw/init.h b/rmw/include/rmw/init.h index ce38615f..5d4426b9 100644 --- a/rmw/include/rmw/init.h +++ b/rmw/include/rmw/init.h @@ -22,41 +22,11 @@ extern "C" #include +#include "rmw/init_options.h" #include "rmw/macros.h" #include "rmw/ret_types.h" #include "rmw/visibility_control.h" -/// Implementation defined options structure used during rmw_init(). -/** - * This should be defined by the rmw implementation. - */ -typedef struct rmw_init_options_impl_t rmw_init_options_impl_t; - -/// Options structure used during rmw_init(). -typedef struct RMW_PUBLIC_TYPE rmw_init_options_t { - /// Locally (process local) unique ID that represents this init/shutdown cycle. - /** - * This should be set by the caller of `rmw_init()` to a number that is - * unique within this process. - * It is designed to be used with `rcl_init()` and `rcl_get_instance_id()`. - */ - uint64_t instance_id; - /// Implementation identifier, used to ensure two different implementations are not being mixed. - const char * implementation_identifier; - /// Implementation defined init options. - /** May be NULL if there are no implementation defined options. */ - rmw_init_options_impl_t * impl; -} rmw_init_options_t; - -/// Return the default init options. -/** - * This should be defined by the rmw implementation. - */ -RMW_PUBLIC -RMW_WARN_UNUSED -rmw_init_options_t -rmw_get_default_init_options(void); - /// Implementation defined context structure returned by rmw_init(). /** * This should be defined by the rmw implementation. @@ -64,27 +34,28 @@ rmw_get_default_init_options(void); typedef struct rmw_context_impl_t rmw_context_impl_t; /// Initialization context structure which is used to store init specific information. -typedef struct RMW_PUBLIC_TYPE rmw_context_t { +typedef struct RMW_PUBLIC_TYPE rmw_context_t +{ /// Locally (process local) unique ID that represents this init/shutdown cycle. uint64_t instance_id; /// Implementation identifier, used to ensure two different implementations are not being mixed. const char * implementation_identifier; - /// Implementation defined init context information. + /// Implementation defined context information. /** May be NULL if there is no implementation defined context information. */ rmw_context_impl_t * impl; } rmw_context_t; -/// Return a zero initialized init context structure. +/// Return a zero initialized context structure. RMW_PUBLIC RMW_WARN_UNUSED rmw_context_t rmw_get_zero_initialized_context(void); -/// Initialize the middleware with the given options, and yielding an init context. +/// Initialize the middleware with the given options, and yielding an context. /** - * The given init context must be zero initialized, and is filled with + * The given context must be zero initialized, and is filled with * middleware specific data upon success of this function. - * The init context is used when initializing some entities like nodes and + * The context is used when initializing some entities like nodes and * guard conditions, and is also required to properly call rmw_shutdown(). * *
@@ -110,9 +81,9 @@ RMW_WARN_UNUSED rmw_ret_t rmw_init(const rmw_init_options_t * options, rmw_context_t * context); -/// Shutdown the middleware for a given init context. +/// Shutdown the middleware for a given context. /** - * The given init context must be a valid context which has been initialized + * The given context must be a valid context which has been initialized * with rmw_init(). * *
diff --git a/rmw/include/rmw/init_options.h b/rmw/include/rmw/init_options.h new file mode 100644 index 00000000..8d8a64cc --- /dev/null +++ b/rmw/include/rmw/init_options.h @@ -0,0 +1,159 @@ +// Copyright 2014-2018 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__INIT_OPTIONS_H_ +#define RMW__INIT_OPTIONS_H_ + +#ifdef __cplusplus +extern "C" +{ +#endif + +#include + +#include "rcutils/allocator.h" +#include "rmw/macros.h" +#include "rmw/ret_types.h" +#include "rmw/visibility_control.h" + +/// Implementation defined options structure used during rmw_init(). +/** + * This should be defined by the rmw implementation. + */ +typedef struct rmw_init_options_impl_t rmw_init_options_impl_t; + +/// Options structure used during rmw_init(). +typedef struct RMW_PUBLIC_TYPE rmw_init_options_t +{ + /// Locally (process local) unique ID that represents this init/shutdown cycle. + /** + * This should be set by the caller of `rmw_init()` to a number that is + * unique within this process. + * It is designed to be used with `rcl_init()` and `rcl_get_instance_id()`. + */ + uint64_t instance_id; + /// Implementation identifier, used to ensure two different implementations are not being mixed. + const char * implementation_identifier; + // TODO(wjwwood): replace with rmw_allocator_t when that refactor happens + /// Allocator used during internal allocation of init options, if needed. + rcutils_allocator_t allocator; + /// Implementation defined init options. + /** May be NULL if there are no implementation defined options. */ + rmw_init_options_impl_t * impl; +} rmw_init_options_t; + +/// Return a zero initialized init options structure. +RMW_PUBLIC +RMW_WARN_UNUSED +rmw_init_options_t +rmw_get_zero_initialized_init_options(void); + +/// Initialize given init_options with the default values and implementation specific values. +/** + * The given allocator is used, if required, during setup of the init options, + * but is also used during initialization. + * + * In either case the given allocator is stored in the returned init options. + * + * The `impl` pointer should not be changed manually. + * + *
+ * Attribute | Adherence + * ------------------ | ------------- + * Allocates Memory | Yes + * Thread-Safe | No + * Uses Atomics | Yes + * Lock-Free | Yes + * + * This should be defined by the rmw implementation. + * + * \param[inout] init_options object to be setup + * \param[in] allocator to be used during setup and during initialization + * \return `RMW_RET_OK` if setup is successful, or + * \return `RMW_RET_INVALID_ARGUMENT` if init_options has already be initialized, or + * \return `RMW_RET_INVALID_ARGUMENT` if any arguments are invalid, or + * \return `RMW_RET_BAD_ALLOC` if allocating memory failed, or + * \return `RMW_RET_ERROR` if an unspecified error occurs. + */ +RMW_PUBLIC +RMW_WARN_UNUSED +rmw_ret_t +rmw_init_options_init(rmw_init_options_t * init_options, rcutils_allocator_t allocator); + +/// Copy the given source init options to the destination init options. +/** + * The allocator from the source is used for any allocations and stored in the + * destination. + * + * The destination should either be zero initialized with + * `rmw_get_zero_initialized_init_options()` or should have had + * `rmw_init_options_fini()` called on it. + * Giving an already initialized init options for the destination will result + * in a failure with return code `RMW_RET_INVALID_ARGUMENT`. + * + *
+ * Attribute | Adherence + * ------------------ | ------------- + * Allocates Memory | Yes + * Thread-Safe | No + * Uses Atomics | Yes + * Lock-Free | Yes + * + * This should be defined by the rmw implementation. + * + * \param[in] src rcl_init_options_t object to be copied from + * \param[out] dst rcl_init_options_t object to be copied into + * \return `RMW_RET_OK` if the copy is successful, or + * \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if the implementation + * identifier for src does not match the implementation of this function, or + * \return `RMW_RET_INVALID_ARGUMENT` if the dst has already be initialized, or + * \return `RMW_RET_INVALID_ARGUMENT` if any arguments are invalid, or + * \return `RMW_RET_BAD_ALLOC` if allocating memory failed, or + * \return `RMW_RET_ERROR` if an unspecified error occurs. + */ +RMW_PUBLIC +RMW_WARN_UNUSED +rmw_ret_t +rmw_init_options_copy(const rmw_init_options_t * src, rmw_init_options_t * dst); + +/// Finalize the given init_options. +/** + * The given init_options must be non-`NULL` and valid, i.e. had + * `rmw_init_options_init()` called on it but not this function yet. + * + *
+ * Attribute | Adherence + * ------------------ | ------------- + * Allocates Memory | Yes + * Thread-Safe | No + * Uses Atomics | Yes + * Lock-Free | Yes + * + * This should be defined by the rmw implementation. + * + * \param[inout] init_options object to be setup + * \return `RMW_RET_OK` if setup is successful, or + * \return `RMW_RET_INVALID_ARGUMENT` if any arguments are invalid, or + * \return `RMW_RET_ERROR` if an unspecified error occurs. + */ +RMW_PUBLIC +RMW_WARN_UNUSED +rmw_ret_t +rmw_init_options_fini(rmw_init_options_t * init_options); + +#ifdef __cplusplus +} +#endif + +#endif // RMW__INIT_OPTIONS_H_ diff --git a/rmw/src/init.c b/rmw/src/init.c index 7c8f0450..22255b36 100644 --- a/rmw/src/init.c +++ b/rmw/src/init.c @@ -25,8 +25,8 @@ rmw_context_t rmw_get_zero_initialized_context(void) { return (const rmw_context_t) { - .instance_id = 0, - .impl = NULL + .instance_id = 0, + .impl = NULL }; } diff --git a/rmw/src/init_options.c b/rmw/src/init_options.c new file mode 100644 index 00000000..da7cfd69 --- /dev/null +++ b/rmw/src/init_options.c @@ -0,0 +1,36 @@ +// Copyright 2018 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 + +#include "rmw/init_options.h" + +#ifdef __cplusplus +extern "C" +{ +#endif + +rmw_init_options_t +rmw_get_zero_initialized_init_options(void) +{ + return (const rmw_init_options_t) { + .instance_id = 0, + .implementation_identifier = NULL, + .impl = NULL, + }; +} + +#ifdef __cplusplus +} +#endif