Function rcl_node_init

• Defined in File node.h

Function Documentation

rcl_ret_t rcl_node_init(rcl_node_t *node, const char *name, const char *namespace_, rcl_context_t *context, const rcl_node_options_t *options)

Initialize a ROS node.

Calling this on a rcl_node_t makes it a valid node handle until rcl_shutdown is called or until rcl_node_fini is called on it.

After calling, the ROS node object can be used to create other middleware primitives like publishers, services, parameters, etc.

The name of the node must not be NULL and adhere to naming restrictions, see the rmw_validate_node_name() function for rules.

Todo:

TODO(wjwwood): node name uniqueness is not yet enforced

The name of the node cannot coincide with another node of the same name. If a node of the same name is already in the domain, it will be shutdown.

The namespace of the node should not be NULL and should also pass the rmw_validate_namespace() function’s rules.

Additionally this function allows namespaces which lack a leading forward slash. Because there is no notion of a relative namespace, there is no difference between a namespace which lacks a forward and the same namespace with a leading forward slash. Therefore, a namespace like "foo/bar" is automatically changed to "/foo/bar" by this function. Similarly, the namespace "" will implicitly become "/" which is a valid namespace.

Todo:

TODO(wjwwood): Parameter infrastructure is currently initialized in the language specific client library, e.g. rclcpp for C++, but will be initialized here in the future. When that happens there will be an option to avoid parameter infrastructure with an option in the rcl_node_options_t struct.

A node contains infrastructure for ROS parameters, which include advertising publishers and service servers. This function will create those external parameter interfaces even if parameters are not used later.

The rcl_node_t given must be allocated and zero initialized. Passing an rcl_node_t which has already had this function called on it, more recently than rcl_node_fini, will fail. An allocated rcl_node_t with uninitialized memory is undefined behavior.

Expected usage:

rcl_context_t context = rcl_get_zero_initialized_context();
// ... initialize the context with rcl_init()
rcl_node_t node = rcl_get_zero_initialized_node();
rcl_node_options_t node_ops = rcl_node_get_default_options();
// ... node options customization
rcl_ret_t ret = rcl_node_init(&node, "node_name", "/node_ns", &context, &node_ops);
// ... error handling and then use the node, but eventually deinitialize it:
ret = rcl_node_fini(&node);
// ... error handling for rcl_node_fini()

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

[1] if returns true for

Parameters:

• node – [inout] a preallocated rcl_node_t

• name – [in] the name of the node, must be a valid c-string

• namespace_ – [in] the namespace of the node, must be a valid c-string

• context – [in] the context instance with which the node should be associated

• options – [in] the node options. The options are deep copied into the node. The caller is always responsible for freeing memory used options they pass in.

Pre:

the node handle must be allocated, zero initialized, and invalid

Pre:

the context handle must be allocated, initialized, and valid

Post:

the node handle is valid and can be used in other rcl_* functions

Returns:

RCL_RET_OK if the node was initialized successfully, or

Returns:

RCL_RET_ALREADY_INIT if the node has already be initialized, or

Returns:

RCL_RET_NOT_INIT if the given context is invalid, or

Returns:

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

Returns:

RCL_RET_BAD_ALLOC if allocating memory failed, or

Returns:

RCL_RET_NODE_INVALID_NAME if the name is invalid, or

Returns:

RCL_RET_NODE_INVALID_NAMESPACE if the namespace_ is invalid, or

Returns:

RCL_RET_ERROR if an unspecified error occurs.