REP 2007: Type Adaptation

rep-2007.rst

@@ -0,0 +1,246 @@
+REP: 2007
+Title: Adapting C++ Types
+Author: Audrow Nash <audrow@openrobotics.org>
+Status: Draft
+Type: Standards Track
+Content-Type: text/x-rst
+Created: 28-Jan-2020
+Post-History: 28-Jan-2020
+
+
+Abstract
+========
+
+This REP proposes an extension to the creation of Publishers and Subscriptions in `rclcpp` to make it easier to convert between ROS 2 interfaces and custom C++ data structures.
+
+
+Motivation
+==========
+
+The primary reason for this change is to improve the developer's experience working with ROS 2.
+Currently, developers often write code to convert a ROS interface into another custom data structure for use in their programs.
+This can be trivial, in the case accessing the ``data`` field in ``std_msgs::msg::String``;
+or more involved such when converting OpenCV's ``cv::Map`` to ROS's ``sensor_msgs/msg/Image`` type [1]_.
+Such conversions are additional work for the programmer and are potential sources of errors.
+
+An additional reason for this change is performance.
+This interface will allow us to define methods for serializing directly to the user requested type, and/or using that type in intra-process communication without ever converting it.
+Whereas without this feature, even to send a ``cv::Mat`` from one publisher to a subscription in the same process would require converting it to a ``sensor_msgs::msg::Image`` first and then back again to cv::Mat.
+
+
+Terminology
+===========
+
+.. glossary::
+     Custom type (in code, ``CustomType``)
+       A data structure that *is not* a ROS 2 interface, such as ``std::string`` or ``cv::Mat``.
+     ROS type (in code, ``RosType``)
+       A data structure that *is* a ROS 2 interface, such as ``std_msgs::msg::String`` or ``sensor_msgs::msg::Image``.
+
+
+Specification
+=============
+
+There are different tiers of expressivity in the syntax for type adaptation, including both explicit to implicit forms.
+The explicit forms require the custom type and the ROS type to be specified; 
+while the implicit form makes an assumption about the ROS type based on the custom type.
+The explicit forms may be used to clearly communicate what is happening, which could be useful in examples or tutorials, or may be used depending on the preferences of the developer.
+While the implicit, and most concise, form will primarily be used for its convenience (although it lacks some of the functionality of the explicit forms).
+
+Below are examples of different syntaxes for type adaptation.
+In these examples and using the terminology above, ``std::string`` will be considered the custom type and the ROS interface ``std_msgs::msg::String`` will be considered the ROS type.
+Note that, for every publisher created in the examples below, a ``std::string`` type variable (the custom type) would be adapted to be published on the ROS network as a ``std_msgs::msg::String`` (the ROS type).
+
+.. code-block:: cpp
+
+   // Explicit Form 1: Most explicit
+   using MsgT = rclcpp::AdaptType<std::string>::to<std_msgs::msg::String>;
+   auto pub1 = std::make_shared<rclcpp::Publisher<MsgT>>();
+
+The most explicit form could be shortened in the following ways:
+
+.. code-block:: cpp
+
+   // Explicit Form 2
+   using MsgT = rclcpp::AdaptType<std::string, std_msgs::msg::String>;
+   auto pub2 = std::make_shared<rclcpp::Publisher<MsgT>>();
+
+   // Explicit Form 3
+   auto pub3 = std::make_shared<rclcpp::Publisher<std::string, std_msgs::msg::String>>();
+
+Note that the 3rd explicit form may be prohibitively complicated to implement since there are multiple template arguments already for publishers and subscribers.
+
+The final shorthand performs an implicit type adaptation with the custom type ``std::string`` which will be adapted to the ROS type``std_msgs::msg::String``:
+
+.. code-block:: cpp
+
+   // Implicit Form
+   auto pub4 = std::make_shared<rclcpp::Publisher<std::string>>();
+
+In this final form, if the custom type (``std::string``) has multiple ROS types that it could represent, then an error will be raised during compilation.
+
+
+Rationale
+=========
+
+Selecting a term
+----------------
+
+There are various terms that may be suitable for type adapting feature described.
+In selecting a term,  
+
+:High priority:
+
+* Clearly communicate the described feature
+* Clearly communicate the order of custom type and ROS type arguments
+
+:Low priority:
+
+* The custom type should be the first argument so that
+  * the custom type is the first argument in both the explicit and implicit syntax
+  * the custom type is read first, for convenience 
+* The syntax reads well
+
+Candidate terms
+^^^^^^^^^^^^^^^
+
+Several possible terms were considered.
+Here is a brief summary of the discussion around different terms.
+
+Masquerade
+""""""""""
+
+There is some precedent for using masquerade in similar settings, IP Masquerading in the Linux kernel [2]_ for example.
+"Masquerade" is also a verb, which may make it easier to discuss among developers.
+However, it was thought that "Masquerade" would be a confusing word for non-English and non-French speakers.
+One disadvantage of "Masquerade" is that there is ambiguity in its usage.
+For example,
+
+.. code-block:: cpp
+
+   Masquerade<std_msgs::msg::String>::as<std::string>
+
+and
+
+.. code-block:: cpp
+
+   Masquerade<std::string>::as<std_msgs::msg::String>   
+
+both seem to make sense.
+This ambiguity may result in frustration on the part of the ROS 2 developer:
+
+* frequently having to refer back to documentation
+* possibly opaque error messages
+
+Facade
+^^^^^^
+
+"Facade" seems to be a more common English word than "masquerade".
+It also is commonly used as a design pattern in object oriented programming.
+However, the "Facade pattern" is typically used to simplify a complex interface [3]_, which is not the major feature being proposed here.
+
+It was thought to use "Facade" in the following form:
+
+.. code-block:: cpp
+
+   Facade<std::string>::instead_of<std_msgs::msg::String>
+
+
+Adapt
+^^^^^
+
+"Adapt" is certainly a common English word, and the "Adapter pattern" is a common design pattern for adjusting an interface [4]_, which matches well with the feature being suggested here.
+Also, using "Adapt" is consistent with the documentation of a similar feature in ROS 1 (i.e., "Adapting C++ Types" [5]_).
+
+"Adapt" also has the advantage of being a verb and of being related to the noun "Adapter".
+This flexiblity may make it easier for developers to discuss its use.
+
+"Adapt" could be used in the following syntax:
+
+.. code-block:: cpp
+
+   Adapt<std::string>::to<std_msgs::msg::String>
+
+Additional terms considered
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Here is a brief listing of additional terms that were considered and why they were not selected:
+
+:Convert: Passed in favor of "Adapt", which expresses a similar idea and has a common design pattern.
+
+:Decorate: Passed in favor of "Fascade", which seems to be more common.
+
+:Mask: Overloaded as a computer science term [6]_.
+
+:Map: Expresses the idea well, but has a lot of meanings in math and programming.
+
+:Use: Possibly confusing with C++'s ``using`` keyword; also not terribly descriptive.
+
+:Wrap: Passed in favor of "Adapt", which seems to be more common.
+
+
+Including "Type" in the name
+----------------------------
+
+Most of the terms being considered refer to general design patterns and, thus, using just the pattern's name may cause naming collisions or confusion as those design patterns may be used in other parts of the ROS codebase. 
+To reduce ambiguity, including the term selected with "Type" would make its usage clearer and help avoid name collisions;
+it should also make it easier for developers to find relevant documentation.
+
+
+Adding this feature in ``rclcpp``
+---------------------------------
+
+Placing this feature in ROS 2's C client library, ``rcl``, would allow this feature to be used in other client libraries, such as ``rclcpp`` and ``rclpy``.
+However, it is not clear that the difficulty of implementing this feature in ``rcl`` is worth the benefit to other client libraries.
+The primary client library that is expected to use this feature is ROS 2's C++ client library, ``rclcpp``.
+Placing this feature in ``rclcpp`` would allow implementation to take advantage of C++'s standard template library, and thus, speed up development.
+
+
+Backwards Compatibility
+=======================
+
+The proposed feature adds new functionality while not modifying existing functionality.
+
+
+Reference Implementation
+========================
+
+The current reference implementation is a work in progress and can be found `here <https://repl.it/@ros2/TypeMasquerading#audrow_main.cpp>`_.
+
+
+References
+==========
+
+.. [1] ``cam2image.cpp`` demo 
+   (https://github.com/ros2/demos/blob/11e00ecf7eec25320f950227531119940496d615/image_tools/src/cam2image.cpp#L277-L291)
+
+.. [2] IP Masquerading in the Linux Kernel
+   (http://linuxdocs.org/HOWTOs/IP-Masquerade-HOWTO-2.html)
+
+.. [3] Facade Pattern
+   (https://en.wikipedia.org/wiki/Facade_pattern)
+
+.. [4] Adapter pattern
+   (https://en.wikipedia.org/wiki/Adapter_pattern)
+
+.. [5] Adapting C++ Types
+   (http://wiki.ros.org/roscpp/Overview/MessagesSerializationAndAdaptingTypes#Adapting_C.2B-.2B-_Types)
+
+.. [6] Masking (computing)
+   (https://en.wikipedia.org/wiki/Mask_(computing))
+
+
+Copyright
+=========
+
+This document has been placed in the public domain.
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   coding: utf-8
+   End: