Skip to content

Commit 4882850

Browse files
wjwwoodwjwwood
authored
refactor init to allow options to be passed and to not be global (#154)
* refactor init to allow options to be passed and to not be global Signed-off-by: William Woodall <[email protected]> * use implementation identifier in init and shutdown functions Signed-off-by: William Woodall <[email protected]> * refactors and renames Signed-off-by: William Woodall <[email protected]> * refactor init_options into its own files Signed-off-by: William Woodall <[email protected]>
1 parent c3b7077 commit 4882850

File tree

8 files changed

+479
-18
lines changed

8 files changed

+479
-18
lines changed

‎rmw/CMakeLists.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@ include_directories(include)
2727
set(rmw_sources
2828
"src/allocators.c"
2929
"src/convert_rcutils_ret_to_rmw_ret.c"
30+
"src/init.c"
31+
"src/init_options.c"
3032
"src/names_and_types.c"
3133
"src/sanity_checks.c"
3234
"src/node_security_options.c"

‎rmw/include/rmw/init.h‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
// Copyright 2014-2018 Open Source Robotics Foundation, Inc.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
#ifndef RMW__INIT_H_
16+
#define RMW__INIT_H_
17+
18+
#ifdef __cplusplus
19+
extern "C"
20+
{
21+
#endif
22+
23+
#include <stdint.h>
24+
25+
#include "rmw/init_options.h"
26+
#include "rmw/macros.h"
27+
#include "rmw/ret_types.h"
28+
#include "rmw/visibility_control.h"
29+
30+
/// Implementation defined context structure returned by rmw_init().
31+
/**
32+
* This should be defined by the rmw implementation.
33+
*/
34+
typedef struct rmw_context_impl_t rmw_context_impl_t;
35+
36+
/// Initialization context structure which is used to store init specific information.
37+
typedef struct RMW_PUBLIC_TYPE rmw_context_t
38+
{
39+
/// Locally (process local) unique ID that represents this init/shutdown cycle.
40+
uint64_t instance_id;
41+
/// Implementation identifier, used to ensure two different implementations are not being mixed.
42+
const char * implementation_identifier;
43+
/// Implementation defined context information.
44+
/** May be NULL if there is no implementation defined context information. */
45+
rmw_context_impl_t * impl;
46+
} rmw_context_t;
47+
48+
/// Return a zero initialized context structure.
49+
RMW_PUBLIC
50+
RMW_WARN_UNUSED
51+
rmw_context_t
52+
rmw_get_zero_initialized_context(void);
53+
54+
/// Initialize the middleware with the given options, and yielding an context.
55+
/**
56+
* The given context must be zero initialized, and is filled with
57+
* middleware specific data upon success of this function.
58+
* The context is used when initializing some entities like nodes and
59+
* guard conditions, and is also required to properly call rmw_shutdown().
60+
*
61+
* <hr>
62+
* Attribute | Adherence
63+
* ------------------ | -------------
64+
* Allocates Memory | Yes
65+
* Thread-Safe | No
66+
* Uses Atomics | No
67+
* Lock-Free | Yes
68+
*
69+
* This should be defined by the rmw implementation.
70+
*
71+
* \param[in] options initialization options to be used during initialization
72+
* \param[out] context resulting context struct
73+
* \return `RMW_RET_OK` if successful, or
74+
* \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if the implementation
75+
* identifier does not match, or
76+
* \return `RMW_RET_INVALID_ARGUMENT` if any arguments are null or invalid, or
77+
* \return `RMW_RET_ERROR` if an unexpected error occurs.
78+
*/
79+
RMW_PUBLIC
80+
RMW_WARN_UNUSED
81+
rmw_ret_t
82+
rmw_init(const rmw_init_options_t * options, rmw_context_t * context);
83+
84+
/// Shutdown the middleware for a given context.
85+
/**
86+
* The given context must be a valid context which has been initialized
87+
* with rmw_init().
88+
*
89+
* <hr>
90+
* Attribute | Adherence
91+
* ------------------ | -------------
92+
* Allocates Memory | Yes
93+
* Thread-Safe | No
94+
* Uses Atomics | No
95+
* Lock-Free | Yes
96+
*
97+
* This should be defined by the rmw implementation.
98+
*
99+
* \param[in] context resulting context struct
100+
* \return `RMW_RET_OK` if successful, or
101+
* \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if the implementation
102+
* identifier does not match, or
103+
* \return `RMW_RET_INVALID_ARGUMENT` if the argument is null or invalid, or
104+
* \return `RMW_RET_ERROR` if an unexpected error occurs.
105+
*/
106+
RMW_PUBLIC
107+
RMW_WARN_UNUSED
108+
rmw_ret_t
109+
rmw_shutdown(rmw_context_t * context);
110+
111+
#ifdef __cplusplus
112+
}
113+
#endif
114+
115+
#endif // RMW__INIT_H_

‎rmw/include/rmw/init_options.h‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
// Copyright 2014-2018 Open Source Robotics Foundation, Inc.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
#ifndef RMW__INIT_OPTIONS_H_
16+
#define RMW__INIT_OPTIONS_H_
17+
18+
#ifdef __cplusplus
19+
extern "C"
20+
{
21+
#endif
22+
23+
#include <stdint.h>
24+
25+
#include "rcutils/allocator.h"
26+
#include "rmw/macros.h"
27+
#include "rmw/ret_types.h"
28+
#include "rmw/visibility_control.h"
29+
30+
/// Implementation defined options structure used during rmw_init().
31+
/**
32+
* This should be defined by the rmw implementation.
33+
*/
34+
typedef struct rmw_init_options_impl_t rmw_init_options_impl_t;
35+
36+
/// Options structure used during rmw_init().
37+
typedef struct RMW_PUBLIC_TYPE rmw_init_options_t
38+
{
39+
/// Locally (process local) unique ID that represents this init/shutdown cycle.
40+
/**
41+
* This should be set by the caller of `rmw_init()` to a number that is
42+
* unique within this process.
43+
* It is designed to be used with `rcl_init()` and `rcl_get_instance_id()`.
44+
*/
45+
uint64_t instance_id;
46+
/// Implementation identifier, used to ensure two different implementations are not being mixed.
47+
const char * implementation_identifier;
48+
// TODO(wjwwood): replace with rmw_allocator_t when that refactor happens
49+
/// Allocator used during internal allocation of init options, if needed.
50+
rcutils_allocator_t allocator;
51+
/// Implementation defined init options.
52+
/** May be NULL if there are no implementation defined options. */
53+
rmw_init_options_impl_t * impl;
54+
} rmw_init_options_t;
55+
56+
/// Return a zero initialized init options structure.
57+
RMW_PUBLIC
58+
RMW_WARN_UNUSED
59+
rmw_init_options_t
60+
rmw_get_zero_initialized_init_options(void);
61+
62+
/// Initialize given init_options with the default values and implementation specific values.
63+
/**
64+
* The given allocator is used, if required, during setup of the init options,
65+
* but is also used during initialization.
66+
*
67+
* In either case the given allocator is stored in the returned init options.
68+
*
69+
* The `impl` pointer should not be changed manually.
70+
*
71+
* <hr>
72+
* Attribute | Adherence
73+
* ------------------ | -------------
74+
* Allocates Memory | Yes
75+
* Thread-Safe | No
76+
* Uses Atomics | Yes
77+
* Lock-Free | Yes
78+
*
79+
* This should be defined by the rmw implementation.
80+
*
81+
* \param[inout] init_options object to be setup
82+
* \param[in] allocator to be used during setup and during initialization
83+
* \return `RMW_RET_OK` if setup is successful, or
84+
* \return `RMW_RET_INVALID_ARGUMENT` if init_options has already be initialized, or
85+
* \return `RMW_RET_INVALID_ARGUMENT` if any arguments are invalid, or
86+
* \return `RMW_RET_BAD_ALLOC` if allocating memory failed, or
87+
* \return `RMW_RET_ERROR` if an unspecified error occurs.
88+
*/
89+
RMW_PUBLIC
90+
RMW_WARN_UNUSED
91+
rmw_ret_t
92+
rmw_init_options_init(rmw_init_options_t * init_options, rcutils_allocator_t allocator);
93+
94+
/// Copy the given source init options to the destination init options.
95+
/**
96+
* The allocator from the source is used for any allocations and stored in the
97+
* destination.
98+
*
99+
* The destination should either be zero initialized with
100+
* `rmw_get_zero_initialized_init_options()` or should have had
101+
* `rmw_init_options_fini()` called on it.
102+
* Giving an already initialized init options for the destination will result
103+
* in a failure with return code `RMW_RET_INVALID_ARGUMENT`.
104+
*
105+
* <hr>
106+
* Attribute | Adherence
107+
* ------------------ | -------------
108+
* Allocates Memory | Yes
109+
* Thread-Safe | No
110+
* Uses Atomics | Yes
111+
* Lock-Free | Yes
112+
*
113+
* This should be defined by the rmw implementation.
114+
*
115+
* \param[in] src rcl_init_options_t object to be copied from
116+
* \param[out] dst rcl_init_options_t object to be copied into
117+
* \return `RMW_RET_OK` if the copy is successful, or
118+
* \return `RMW_RET_INCORRECT_RMW_IMPLEMENTATION` if the implementation
119+
* identifier for src does not match the implementation of this function, or
120+
* \return `RMW_RET_INVALID_ARGUMENT` if the dst has already be initialized, or
121+
* \return `RMW_RET_INVALID_ARGUMENT` if any arguments are invalid, or
122+
* \return `RMW_RET_BAD_ALLOC` if allocating memory failed, or
123+
* \return `RMW_RET_ERROR` if an unspecified error occurs.
124+
*/
125+
RMW_PUBLIC
126+
RMW_WARN_UNUSED
127+
rmw_ret_t
128+
rmw_init_options_copy(const rmw_init_options_t * src, rmw_init_options_t * dst);
129+
130+
/// Finalize the given init_options.
131+
/**
132+
* The given init_options must be non-`NULL` and valid, i.e. had
133+
* `rmw_init_options_init()` called on it but not this function yet.
134+
*
135+
* <hr>
136+
* Attribute | Adherence
137+
* ------------------ | -------------
138+
* Allocates Memory | Yes
139+
* Thread-Safe | No
140+
* Uses Atomics | Yes
141+
* Lock-Free | Yes
142+
*
143+
* This should be defined by the rmw implementation.
144+
*
145+
* \param[inout] init_options object to be setup
146+
* \return `RMW_RET_OK` if setup is successful, or
147+
* \return `RMW_RET_INVALID_ARGUMENT` if any arguments are invalid, or
148+
* \return `RMW_RET_ERROR` if an unspecified error occurs.
149+
*/
150+
RMW_PUBLIC
151+
RMW_WARN_UNUSED
152+
rmw_ret_t
153+
rmw_init_options_fini(rmw_init_options_t * init_options);
154+
155+
#ifdef __cplusplus
156+
}
157+
#endif
158+
159+
#endif // RMW__INIT_OPTIONS_H_

‎rmw/include/rmw/ret_types.h‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
// Copyright 2014-2018 Open Source Robotics Foundation, Inc.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
#ifndef RMW__RET_TYPES_H_
16+
#define RMW__RET_TYPES_H_
17+
18+
#ifdef __cplusplus
19+
extern "C"
20+
{
21+
#endif
22+
23+
#include <stdint.h>
24+
25+
typedef int32_t rmw_ret_t;
26+
#define RMW_RET_OK 0
27+
#define RMW_RET_ERROR 1
28+
#define RMW_RET_TIMEOUT 2
29+
30+
/// Failed to allocate memory return code.
31+
#define RMW_RET_BAD_ALLOC 10
32+
/// Invalid argument return code.
33+
#define RMW_RET_INVALID_ARGUMENT 11
34+
/// Incorrect rmw implementation.
35+
#define RMW_RET_INCORRECT_RMW_IMPLEMENTATION 12
36+
37+
#ifdef __cplusplus
38+
}
39+
#endif
40+
41+
#endif // RMW__RET_TYPES_H_

0 commit comments

Comments
 (0)