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]
- 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 not initialized, or
- Returns:
RCL_RET_INVALID_ARGUMENT if any arguments are invalid or context is NULL, 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.