ROS C++ Details

These notes discuss C++, as it appears in the ROS 2 Cpp publisher example below.

// From: https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Writing-A-Simple-Cpp-Publisher-And-Subscriber.html#write-the-publisher-node0
// Accessed on: 1/17/2023
#include <chrono>
#include <functional>
#include <memory>
#include <string>

#include "rclcpp/rclcpp.hpp"
#include "std_msgs/msg/string.hpp"

using namespace std::chrono_literals;

/* This example creates a subclass of Node and uses std::bind() to register a */
/* member function as a callback from the timer. */

class MinimalPublisher : public rclcpp::Node
{
  public:
    MinimalPublisher()
    : Node("minimal_publisher"), count_(0)
    {
      publisher_ = this->create_publisher<std_msgs::msg::String>("topic", 10);
      timer_ = this->create_wall_timer(
      500ms, std::bind(&MinimalPublisher::timer_callback, this));
    }

  private:
    void timer_callback()
    {
      auto message = std_msgs::msg::String();
      message.data = "Hello, world! " + std::to_string(count_++);
      RCLCPP_INFO(this->get_logger(), "Publishing: '%s'", message.data.c_str());
      publisher_->publish(message);
    }
    rclcpp::TimerBase::SharedPtr timer_;
    rclcpp::Publisher<std_msgs::msg::String>::SharedPtr publisher_;
    size_t count_;
};

int main(int argc, char * argv[])
{
  rclcpp::init(argc, argv);
  rclcpp::spin(std::make_shared<MinimalPublisher>());
  rclcpp::shutdown();
  return 0;
}

• The .cpp file uses the pre-processor directive to #include several header files.
• The pre-processor searches for these files on the include path and textually replaces them (i.e., copies and pastes the text directly), creating an intermediate file.

• Files that are include with <> are searched for on the standard include path (which is provided by default).

  #include <chrono>      // timing-related functions
  #include <functional>  // functional programming
  #include <memory>      // smart pointers
  #include <string>      // strings
  

• Other include files are for libraries (including other ROS and non-standard system libraries)

  #include "rclcpp/rclcpp.hpp"
  #include "std_msgs/msg/string.hpp"
  

• These files, unless they are installed to a standard location on the system (i.e., /usr/include) must be explicitly added to the include path
• When you target_link_libraries(mytarget alibrary) in CMakeLists.txt, the include directories necessary for mytarget to use alibrary are automatically added to the include path
• If your code #include=s a header from a library, that library is a =build_depend dependency, and likely a build_export_depend, so it makes sense to add a depend in the package.xml
  • rosdep can be used to automatically fetch dependencies
  • Only dependencies that are registered with ros can be fetched with rosdep, but anybody can register a package (though there are humans who review such additions).

• The first encounter with a namespace is using namespace std::chrono_literals
• Generally the form of using namspace X is discouraged, however, an exception is a namespace containing literal suffixes
• Literal suffixes are a C++11 feature that enable you to write a custom literal suffix operator that converts a literal into a given type
  • Examples of built-in suffixes are f (for float) and u for unsigned (so 1f is a floating point number and 1u is an unsigned integer)
• std::chrono_literals allows using some intuitive suffixes to specify time, such as
  • 11ms is 11 milliseconds and 12h is 12 hours.
• C++ namespaces are used to prevent issues related to multiple projects having the same name for things (and thus making them incompatible with each other
• Everything in C++ is in a namespace. The global namespace is blank and automatically visible, but it can be explicitly invoked using ::item, where item is something defined in the given namespace
• To reference an item in a namespace (e.g., ns) you can provide the fully-qualified name ns::item
• It is also possible to make a single item from a namespace visible with using ns::item, which makes item visible in the scope that using ns::item is called in.
  • For example if placed at the top of a file (and outside any function) item will be visible anywhere below the using ns::item
  • If used at the top of a function item will be visible within that function. More generally, if used within {}, item will be visible anywhere below the using ns::item that is also within the nearest block of {}
• It is possible (but you should not do this) to make all items in a namespace visible by doing using namespace ns.
  • However, doing this can introduce name conflicts and unexpected behavior as it effectively overrides the purpose of namespaces

• The class MinimalPublisher : public rclcpp::Node is declared.
• The MinimalPublisher class is a subclass (or child) of the rclcpp::Node class
• Subclassing the rclcpp::Node class is the "preferred" method of creating ROS2 nodes in C++
  • The reason for this preference is explained in Node Composition and Managed Nodes are two other types of ROS nodes in C++ and these nodes depend upon sub-classing
  • Composable nodes can be loaded into the same process at runtime, thus reducing the overhead of any messages/services called between them
  • Managed Nodes (also called lifecycle nodes) enable a user to control when a node starts, shuts down and other events in the lifetime of a node
• The canonical documentation for rclcpp is located in the API docs
  • Go to https://index.ros.org and search for rclcpp, then click the link for the API documentation for details on rclcpp::Node

• RAII stands for "Resource Acquisition is Initialization", and this is the primary tool used for memory and exception safety in C++
• What this means is that constructors acquire resources and destructors release them
• RAII is very important in the face of exceptions
  • Imagine you need to allocate 3 resources, but the allocation may throw an exception
  • If the second allocation throws an exception you need to free the 1st resource
  • If the third allocatin throws you need to free the 1st and 2nd resource
  • By freeing resources in destructors this happens automatically, otherwise you would need to handle each of the above cases manually, which can lead to a lot of error handling code
• std::vector<> uses RAII
  • The vector class allocates memory in its constructor, and it is automatically freed when the vector is destructed

• Smart pointers are used to track and automatically free memory
• There are two main smart pointer types in C++
  • std::unique_ptr<T>, which allows one "owner" of the memory
    • What this means is that there is only ever 1 valid unique_ptr pointing to memory at any given time
    • Anytime a unique_ptr is "copied", the source pointer is invalidated and using it again results in an error
    • When the unique_ptr goes out of scope, the memory is freed
  • std::shared_ptr<T>, which allows multiple shared "owners" of the memory
    • The shared_ptr is reference counted, meaning that every time a shared_ptr is copied, it's reference count is increased
    • When a shared_ptr is destructed, the reference count is decremented. If the reference count is 0 (meaning all =shared_ptr=s referring to given memory were deallocated) the memory is freed
• Shared pointers enable automatic memory management and work as long as their are no circular reference (A -> B and B -> A). Circular references can be broken with weak_ptr

• Pass by value (void dostuff(int x)), when calling dostuff(y) the value of y is copied into x.
  • Changes made to x within dostuff() happen in the copy and do not modify y
  • This type of argument is an [in] argument as it is an input to a function
• Pass by reference (void dostuff(int & x)), when calling dostuff(y), x is a reference to y
  • No copy is made (which is good for a large datastructure)
  • Changes to x within dostuff() are reflected in x
  • This can be either an [in] argument (if dostuff() reads from x) and [out] argument (if dostuff() writes to x) or both
• Pass by reference to const (void dostuff(const int & x)) or equivalently void dostuff(int const & x)
  • This method is the same as pass by reference but dostuff cannot modify x, so it is always an [in] value
  • This method is the preferred way of passing large objects to functions
• Move (void dostuff(std::vector<int> && x))
  • This method requires that dostuff is called with an lvalue reference (basically some value that cannot appear on the left-hand side of an assignment (=) expression
  • dostuff is allowed to modify and destroy x, since it can never be referenced again
  • For example dostuff(std::vector<int>(10)) creates a temporary vector which, since it is temporary can't be referenced again. Therefore its memory, instead of being deallocated, can be reused within dostuff

• In C++ variables and class methods can be marked const
• If a method does not modify any class members then it should generally be marked const
  • const methods can be invoked on const objects (whereas non-const methods cannot)
• const correctness is enforced by the compiler. It is helpful because when functions can't change values you can rely on them being the same (which makes debugging easier).