Struct NodeBuilder

Source

pub struct NodeBuilder { /* private fields */ }

Expand description

A builder for creating a Node.

The builder pattern allows selectively setting some fields, and leaving all others at their default values. This struct instance can be created via Node::builder().

The default values for optional fields are:

namespace: "/"
use_global_arguments: true
arguments: []
enable_rosout: true
clock_type: ClockType::RosTime
clock_qos: QOS_PROFILE_CLOCK

§Example

let context = Context::new([])?;
// Building a node in a single expression
let node = NodeBuilder::new(&context, "foo_node").namespace("/bar").build()?;
assert_eq!(node.name(), "foo_node");
assert_eq!(node.namespace(), "/bar");
// Building a node via Node::builder()
let node = Node::builder(&context, "bar_node").build()?;
assert_eq!(node.name(), "bar_node");
// Building a node step-by-step
let mut builder = Node::builder(&context, "goose");
builder = builder.namespace("/duck/duck");
let node = builder.build()?;
assert_eq!(node.fully_qualified_name(), "/duck/duck/goose");

Implementations§

Source §

impl NodeBuilder

Source

pub fn new(context: &Context, name: &str) -> NodeBuilder

Creates a builder for a node with the given name.

See the Node docs for general information on node names.

§Rules for valid node names

The rules for a valid node name are checked by the rmw_validate_node_name() function. They are:

Must contain only the a-z, A-Z, 0-9, and _ characters
Must not be empty and not be longer than RMW_NODE_NAME_MAX_NAME_LENGTH
Must not start with a number

Note that node name validation is delayed until NodeBuilder::build().

§Example

let context = Context::new([])?;
// This is a valid node name
assert!(NodeBuilder::new(&context, "my_node").build().is_ok());
// This is another valid node name (although not a good one)
assert!(NodeBuilder::new(&context, "_______").build().is_ok());
// This is an invalid node name
assert!(matches!(
    NodeBuilder::new(&context, "röböt")
        .build()
        .unwrap_err(),
    RclrsError::RclError { code: RclReturnCode::NodeInvalidName, .. }
));

Source

pub fn namespace(self, namespace: &str) -> Self

Sets the node namespace.

See the Node docs for general information on namespaces.

§Rules for valid namespaces

The rules for a valid node namespace are based on the rules for a valid topic and are checked by the rmw_validate_namespace() function. However, a namespace without a leading forward slash is automatically changed to have a leading forward slash before it is checked with this function.

Thus, the effective rules are:

Must contain only the a-z, A-Z, 0-9, _, and / characters
Must not have a number at the beginning, or after a /
Must not contain two or more / characters in a row
Must not have a / character at the end, except if / is the full namespace

Note that namespace validation is delayed until NodeBuilder::build().

§Example

let context = Context::new([])?;
// This is a valid namespace
let builder_ok_ns = Node::builder(&context, "my_node").namespace("/some/nested/namespace");
assert!(builder_ok_ns.build().is_ok());
// This is an invalid namespace
assert!(matches!(
    Node::builder(&context, "my_node")
        .namespace("/10_percent_luck/20_percent_skill")
        .build()
        .unwrap_err(),
    RclrsError::RclError { code: RclReturnCode::NodeInvalidNamespace, .. }
));
// A missing forward slash at the beginning is automatically added
assert_eq!(
    Node::builder(&context, "my_node")
        .namespace("foo")
        .build()?
        .namespace(),
    "/foo"
);

Source

pub fn use_global_arguments(self, enable: bool) -> Self

Enables or disables using global arguments.

The “global” arguments are those used in creating the context.

§Example

let context_args = ["--ros-args", "--remap", "__node:=your_node"]
  .map(String::from);
let context = Context::new(context_args)?;
// Ignore the global arguments:
let node_without_global_args =
  rclrs::create_node_builder(&context, "my_node")
  .use_global_arguments(false)
  .build()?;
assert_eq!(node_without_global_args.name(), "my_node");
// Do not ignore the global arguments:
let node_with_global_args =
  rclrs::create_node_builder(&context, "my_other_node")
  .use_global_arguments(true)
  .build()?;
assert_eq!(node_with_global_args.name(), "your_node");

Source

pub fn arguments(self, arguments: impl IntoIterator<Item = String>) -> Self

Sets node-specific command line arguments.

These arguments are parsed the same way as those for Context::new(). However, the node-specific command line arguments have higher precedence than the arguments used in creating the context.

For more details about command line arguments, see here.

§Example

// Usually, this would change the name of "my_node" to "context_args_node":
let context_args = ["--ros-args", "--remap", "my_node:__node:=context_args_node"]
  .map(String::from);
let context = Context::new(context_args)?;
// But the node arguments will change it to "node_args_node":
let node_args = ["--ros-args", "--remap", "my_node:__node:=node_args_node"]
  .map(String::from);
let node =
  rclrs::create_node_builder(&context, "my_node")
  .arguments(node_args)
  .build()?;
assert_eq!(node.name(), "node_args_node");