From 2423b1d5127484848e036d6626524fba3156bf43 Mon Sep 17 00:00:00 2001 From: Taylor Cramer Date: Mon, 26 Feb 2024 23:12:48 +0000 Subject: [PATCH] docs: Prefer rvalue references Change-Id: Ief1a6c32bd951ed6b3ebaeca6722bf1998449558 Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/193647 Reviewed-by: Kayce Basques Reviewed-by: Wyatt Hepler Commit-Queue: Taylor Cramer --- docs/style/cpp.rst | 20 ++++++++++++++++++++ pw_function/docs.rst | 2 ++ 2 files changed, 22 insertions(+) diff --git a/docs/style/cpp.rst b/docs/style/cpp.rst index 76ba330fc7..9c645e67b6 100644 --- a/docs/style/cpp.rst +++ b/docs/style/cpp.rst @@ -199,6 +199,26 @@ comment line, even if the blank comment line is the last line in the block. // bool SomeFunction(); +Rvalue references +================= +Move-only or expensive-to-copy function arguments should typically be passed +by reference (``T&``) or const-reference (``const T&&``, preferred). However, +when a function consumes or moves such an argument, it should accept an rvalue +reference (``T&&``) rather than taking the argument by-value (``T``). An rvalue +reference forces the caller to ``std::move`` when passing a preexisting +variable, which makes the transfer of ownership explicit. + +Compared with accepting arguments by-value, rvalue references prevent +unnecessary object instances and extra calls to move constructors. This has been +shown to significantly impact code size and stack usage for Pigweed users. + +This guidance overrides the standard `Google Style Guide +`. + +This is especially important when using ``pw::Function``. For more information +about accepting ``pw::Function`` arguments, see +:ref:`module-pw_function-move-semantics`. + Control statements ================== diff --git a/pw_function/docs.rst b/pw_function/docs.rst index cd4e55bf1e..db35238537 100644 --- a/pw_function/docs.rst +++ b/pw_function/docs.rst @@ -208,6 +208,8 @@ place of a function pointer or equivalent callable. void DoTheThing(int arg, const pw::Function& callback); // Note the parameter name within the function signature template for clarity. +.. _module-pw_function-move-semantics: + Move semantics ============== :cpp:type:`pw::Function` is movable, but not copyable, so APIs must accept