init_options.h File Reference

#include <stdint.h>
#include "rcutils/allocator.h"
#include "rmw/domain_id.h"
#include "rmw/localhost.h"
#include "rmw/macros.h"
#include "rmw/ret_types.h"
#include "rmw/security_options.h"
#include "rmw/visibility_control.h"

Include dependency graph for init_options.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	rmw_init_options_t
	Options structure used during rmw_init(). More...

Typedefs
typedef struct rmw_init_options_impl_t	rmw_init_options_impl_t
	Implementation defined options structure used during rmw_init(). More...
typedef struct RMW_PUBLIC_TYPE rmw_init_options_t	rmw_init_options_t
	Options structure used during rmw_init(). More...

Functions
rmw_init_options_t	rmw_get_zero_initialized_init_options (void)
	Return a zero initialized init options structure. More...
rmw_ret_t	rmw_init_options_init (rmw_init_options_t *init_options, rcutils_allocator_t allocator)
	Initialize given init options with the default values and implementation specific values. More...
rmw_ret_t	rmw_init_options_copy (const rmw_init_options_t *src, rmw_init_options_t *dst)
	Copy the given source init options to the destination init options. More...
rmw_ret_t	rmw_init_options_fini (rmw_init_options_t *init_options)
	Finalize the given init options. More...

Typedef Documentation

rmw_init_options_impl_t

typedef struct rmw_init_options_impl_t rmw_init_options_impl_t

Implementation defined options structure used during rmw_init().

This should be defined by the rmw implementation.

rmw_init_options_t

typedef struct RMW_PUBLIC_TYPE rmw_init_options_t rmw_init_options_t

Options structure used during rmw_init().

Function Documentation

rmw_get_zero_initialized_init_options()

rmw_init_options_t rmw_get_zero_initialized_init_options

(

void

)

Return a zero initialized init options structure.

rmw_init_options_init()

rmw_ret_t rmw_init_options_init	(	rmw_init_options_t *	init_options,
		rcutils_allocator_t	allocator
	)

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.

Precondition

The given init options must be zero initialized.

Postcondition

If initialization fails, init options will remain zero initialized.

Remarks

Giving an already initialized init options 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.

Parameters

[in,out]	init_options	object to be setup
[in]	allocator	to be used during setup and during initialization

Returns

RMW_RET_OK if setup is successful, or

RMW_RET_INVALID_ARGUMENT if any arguments are invalid, or

RMW_RET_BAD_ALLOC if allocating memory failed, or

RMW_RET_ERROR if an unspecified error occurs.

rmw_init_options_copy()

rmw_ret_t rmw_init_options_copy	(	const rmw_init_options_t *	src,
		rmw_init_options_t *	dst
	)

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.

Precondition

The source init options must have been initialized i.e. had rmw_init_options_init() called on.

The destination init options must be zero initialized.

Postcondition

If copy fails, destination init options will remain zero initialized.

Remarks

Giving an zero initialized init options as a source will result in a failure with return code RMW_RET_INVALID_ARGUMENT.

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.

Parameters

[in]	src	rcl_init_options_t object to be copied from
[out]	dst	rcl_init_options_t object to be copied into

Returns

RMW_RET_OK if the copy is successful, or

RMW_RET_INCORRECT_RMW_IMPLEMENTATION if the implementation identifier for src does not match the implementation of this function, or

RMW_RET_INVALID_ARGUMENT if any arguments are invalid, or

RMW_RET_BAD_ALLOC if allocating memory failed, or

RMW_RET_ERROR if an unspecified error occurs.

rmw_init_options_fini()

rmw_ret_t rmw_init_options_fini

(

rmw_init_options_t *

init_options

)

Finalize the given init options.

This function will return early if a logical error, such as RMW_RET_INVALID_ARGUMENT or RMW_RET_INCORRECT_RMW_IMPLEMENTATION, ensues, leaving the given init options unchanged. Otherwise, it will proceed despite errors, freeing as much resources as it can and zero initializing the given init options.

Precondition

The given init options must have been initialized i.e. had rmw_init_options_init() called on.

Remarks

If init options are zero initialized, then RMW_RET_INVALID_ARGUMENT is returned.

---

Attribute	Adherence
Allocates Memory	Yes
Thread-Safe	No
Uses Atomics	Yes
Lock-Free	Yes

This should be defined by the rmw implementation.

Parameters

[in,out]

init_options

object to finalized

Returns

RMW_RET_OK if finalization is successful, or

RMW_RET_INVALID_ARGUMENT if any arguments are invalid, or

RMW_RET_INCORRECT_RMW_IMPLEMENTATION if the implementation identifier does not match the implementation of this function, or

RMW_RET_ERROR if an unspecified error occurs.