diff --git a/source/docs/software/commandbased/cpp-command-ownership.rst b/source/docs/software/commandbased/cpp-command-ownership.rst new file mode 100644 index 0000000000..be4222ebaf --- /dev/null +++ b/source/docs/software/commandbased/cpp-command-ownership.rst @@ -0,0 +1,141 @@ +C++ Command Ownership Model +=========================== + +C++ Ownership Scope Semantics +----------------------------- + +Unlike languages (such as Java and Python) that hide memory management from the programmer, C++ programmers must be conscious of memory management and object lifetimes. + +When allocating on the stack, as following, the object is destroyed when it goes out of scope. In this case, ``x`` is destroyed when ``MyFunction`` returns: + +.. code-block:: c++ + + int* MyFunction() { + int x = 3; + // ... + return &x; // invalid pointer -- using it will crash/"segfault"!!! + } // x is destroyed here! + +Thus, it is important to store objects in the correct scope so they aren't destroyed while they're used -- this causes a whole category of C++ bugs called "use after free". + +Allocating on the heap (with ``new``) persists the object beyond the variable scope, but then the object must be destroyed manually, which is even more difficult to do at the right time: this can cause "use after free" bugs (if the object is destroyed too early) as well as memory leaks (if the object is not destroyed). + +In summary, each object should always be _owned_ by a scope that dictates its lifetime and is responsible for automatically destroying it. + + +Ownership of Command Objects +---------------------------- + +The C++ Command-based framework often uses two types with vastly different ownership semantics: + +- ``Command*`` is a raw pointer, non-owning: the command object is owned elsewhere. +- ``CommandPtr`` is an "smart" owning pointer (wrapper around ``std::unique_ptr``): whatever owns the ``CommandPtr`` transitively owns the command object. + +In other words, functions that take/return a ``CommandPtr`` take/return _ownership_ of the command object, as opposed to functions taking/returning a ``Command*`` that don't transfer ownership. + +For example, the :ref:`trigger bindings ` have overloads for both ``Command*`` and ``CommandPtr``. + +Command*: Non-Owning +^^^^^^^^^^^^^^^^^^^^ + +Here, the command objects are defined as variables of the ``RobotContainer`` class, and therefore are owned by the ``RobotContainer`` object and exist as long as the robot code is running. The variables can be of a ``Command`` subclass (such as ``InstantCommand`` in the case of ``m_driveHalfSpeed`` and ``m_driveHalfSpeed``), or as ``CommandPtr`` (as in ``m_spinUpShooter`` and ``m_stopShooter``). + +.. tab-set:: + + .. tab-item:: Command Subclass + :sync: tabcode-subclass + + .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.1.1-beta-3/wpilibcExamples/src/main/cpp/examples/StateSpaceDifferentialDriveSimulation/include/RobotContainer.h + :language: cpp + :lines: 26, 34, 43-46 + :linenos: + :lineno-start: 26 + + .. tab-item:: CommandPtr + :sync: tabcode-ptr + + .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.1.1-beta-3/wpilibcExamples/src/main/cpp/examples/Frisbeebot/include/RobotContainer.h + :language: cpp + :lines: 25, 32, 41-49 + :linenos: + :lineno-start: 25 + +To get a ``Command*``, use ``&`` (address-of operator) in case of a ``Command`` subclass or ``.get()`` in case of a ``CommandPtr``, and pass it the trigger binding method (such as ``OnTrue``): + +.. tab-set:: + + .. tab-item:: Command Subclass + :sync: tabcode-subclass + + .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.1.1-beta-3/wpilibcExamples/src/main/cpp/examples/StateSpaceDifferentialDriveSimulation/cpp/RobotContainer.cpp + :language: cpp + :lines: 50-58 + :linenos: + :lineno-start: 50 + + .. tab-item:: CommandPtr + :sync: tabcode-ptr + + .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.1.1-beta-3/wpilibcExamples/src/main/cpp/examples/Frisbeebot/cpp/RobotContainer.cpp + :language: cpp + :lines: 22-31 + :linenos: + :lineno-start: 22 + + +Since the command was passed as a ``Command*``, ownership is not transferred and the program relies on the command being owned in an appropriate scope. If the command object were to be defined in a different scope and get destroyed, this would be a use-after-free and the program would crash or otherwise misbehave ("Undefined Behavior"). + +CommandPtr: Owning +^^^^^^^^^^^^^^^^^^ + +Here, commands are defined as ``CommandPtr`` and _moved_ into the binding, ownership is passed to the scheduler. + +.. rli:: https://github.com/wpilibsuite/allwpilib/raw/v2024.1.1-beta-4/wpilibcExamples/src/main/cpp/examples/Frisbeebot/cpp/RobotContainer.cpp + :language: c++ + :lines: 22, 33-52 + :linenos: + :lineno-start: 22 + +Note the calls to ``std::move`` that hint at the ownership move. + +The ``shoot`` and ``stopFeeder`` variables will be destroyed when the function returns, but this isn't a problem because the object was moved (with ``std::move``) into the function. However, these variables are now in an invalid state and must not be used! Similar to use-after-free, using them would cause crashes or other undefined behavior: this is called use-after-move. + +To avoid the risk of use-after-move and invalid variables, ``CommandPtr`` expressions can also be passed inline: + +.. rli:: https://github.com/wpilibsuite/allwpilib/raw/v2024.1.1-beta-4/wpilibcExamples/src/main/cpp/examples/Frisbeebot/cpp/RobotContainer.cpp + :language: c++ + :lines: 22, 54-60 + :linenos: + :lineno-start: 22 + +It's also possible to convert ``Command`` subclasses to ``CommandPtr`` using ``.ToPtr()``: + +.. rli:: https://github.com/wpilibsuite/allwpilib/raw/v2024.1.1-beta-4/wpilibcExamples/src/main/cpp/examples/GearsBot/cpp/RobotContainer.cpp + :language: c++ + :lines: 37 + :linenos: + :lineno-start: 37 + +Ownership in Compositions +------------------------- + +As described in :ref:`docs/software/commandbased/command-compositions:Command Compositions`, command instances that have been passed to a command composition cannot be independently scheduled or passed to a second command composition. In C++, this interacts nicely with the ownership model: each composition owns its components! This way, double-composition bugs are nearly inexistent in C++ (whereas they pose a common error in Java). + +Therefore, compositions only take ``CommandPtr``s and not ``Command*``: + +.. rli:: https://github.com/wpilibsuite/allwpilib/raw/v2024.1.1-beta-4/wpilibcExamples/src/main/cpp/examples/MecanumControllerCommand/cpp/RobotContainer.cpp + :language: c++ + :lines: 112-121 + :linenos: + :lineno-start: 112 + +Ownership of Default Commands +----------------------------- + +All default commands are owned by the scheduler, therefore, ``SetDefaultCommand`` only takes a ``CommandPtr`` and not a ``Command*``: + +.. rli:: https://github.com/wpilibsuite/allwpilib/raw/v2024.1.1-beta-4/wpilibcExamples/src/main/cpp/examples/ArmBot/cpp/RobotContainer.cpp + :language: c++ + :lines: 22-27 + :linenos: + :lineno-start: 22 diff --git a/source/docs/software/commandbased/index.rst b/source/docs/software/commandbased/index.rst index acf476bdbe..a2e726f795 100644 --- a/source/docs/software/commandbased/index.rst +++ b/source/docs/software/commandbased/index.rst @@ -16,6 +16,7 @@ For a collection of example projects using the command-based framework, see :ref structuring-command-based-project organizing-command-based command-scheduler + cpp-command-ownership cpp-command-discussion pid-subsystems-commands profile-subsystems-commands