Perfect Forwarding and std::forward

In our previous lesson on move semantics, we discussed the cost associated with copying objects, particularly those with extensive nested resources. Move semantics provide a solution by allowing the direct transfer of resources to a new object, bypassing the need for complete duplication.

Because this process involves transferring resources away from our original object, this process leaves the object in a degraded, "moved-from" state. But, in scenarios where the original object is no longer required, this is perfectly acceptable.

The decision on whether and how to implement move semantics is based on the specific requirements of our class and the nature of its resources. A minimalist example is shown below:

1#include <iostream>
2
3class Character {
4public:
5  Character(){}
6
7  // Copy Constructor
8  Character(const Character& Original){
9    std::cout << "Copying\n";
10  }
11
12  // Move Constructor
13  Character(Character&& Original){
14    std::cout << "Moving\n";
15  }
16};
17
18int main(){
19  Character A;
20  Character B{A};
21  Character C{std::move(A)};
22}

In this example, the Character we pass to the constructor on line 20 is an lvalue.

On line 21, by wrapping the argument in std::move(), we cast it to an rvalue. This tells the compiler it's safe to "move from" the character A, and therefore the move constructor is invoked.

The move constructor is the constructor that accepts an rvalue reference, denoted by the && on line 13. Our previous program had the following output:

1Copying
2Moving

Objects can also be copied or moved using the assignment operator, eg B = A. To fully implement copy and move semantics, we'd want to implement those operators too.

For this lesson, we'll just implement simple constructors, as our focus is on forwarding rather than semantics. We have dedicated lessons on copy semantics and move semantics earlier in the course:

Correctly implementing move semantics has some challenges when there is an intermediate function that exists between our calling code and our constructor. We've seen examples of this in the standard library.

For example, functions like std::make_unique() and std::make_shared() receive a list of arguments that are eventually going to be forwarded to a constructor.

The emplace() method that exists on various containers like arrays and linked lists has similar requirements.

Let's imagine we need to create such an intermediate template function. This will let us see some of the challenges, and how we can solve them. We'll call ours Build():

1#include <iostream>
2
Character Class|Show
3class Character {/*...*/};
16
17template <typename T>
18T Build(T& Original){
19  T NewObject{Original};
20  return NewObject;
21}
22
23int main(){
24  Character A;
25  Character B{Build(A)};
26  Character C{Build(std::move(A))};
27}

Our first challenge is that our reference parameter cannot accept an rvalue reference at all. We get the compilation error:

1A non-const reference may only be bound to an lvalue

To fix this, we can update our parameter list to accept a new type of reference - a forwarding reference using &&:

1template <typename T>
2T Build(T&& Original){
3  T NewObject{Original};
4  return NewObject;
5}

This may be confusing, as we previously showed that && denotes an rvalue reference. However, when used with a template type (including an auto function parameter), && denotes the type is forwarding reference.

A forwarding reference can bind to both lvalues and rvalues, preserving their value category:

1#include <iostream>
2
Character Class|Show
3class Character {/*...*/};
16
17template <typename T>
18T Build(T&& Original){
19  T NewObject{Original};
20  return NewObject;
21}
22
23int main(){
24  Character A;
25  Character B{Build(A)};
26  Character C{Build(std::move(A))};
27}

Our code now compiles, but we've lost the benefits of move semantics. Our object is being copied, regardless of whether we provide an lvalue or rvalue. The output of the previous code example is:

1Copying
2Copying

We'll fix this soon, but lets first introduce some helpful type traits.

Our Build() function now compiles successfully, but its behavior will be a bit confusing. This is because the template type T will sometimes be a value type (as in Character) and sometimes a reference type (as in Character& or Character&&). The possibility of each of these types also being const adds further complexity.

What is our Build() function actually building and what is it returning in each of these scenarios? The answer to that question is not exactly clear, as it depends on intricate details on how references get constructed from other references.

This is called reference collapsing, for those who want to investigate the underlying rules governing situations such as this. However, we don't want the behavior of our functions to be defined by esoteric rules if we can instead be clear and explicit about how our code is intended to work.

For example, let's imagine we want our Build() function to build a new object and return it by value. Ideas we introduced in our type traits lessons can help us implement this behavior unambiguously.

Specifically, if T is a reference type, we want to construct and return the equivalent value type. The standard library already has the std::remove_reference utility for exactly this scenario.

As usual, we access it through the <type_traits> header, and we retrieve the resulting type from its type static member, or by using the _t variation:

1#include <type_traits>
2
3class Character{};
4
5// It echoes non-reference types back to us
6// Therefore, T1 will be Character
7using T1 = std::remove_reference<Character>::type;
8
9// If we provide it a reference type, it returns
10// the corresponding value type
11// Therefore, T2 will also be Character
12using T2 = std::remove_reference<Character&>::type;
13
14// We can use the _t syntax instead of ::type
15using T3 = std::remove_reference_t<Character&>;

We also have the option of using its stronger std::decay friend. In addition to removing any reference component on the type, std::decay will also remove any const or volatile qualifiers:

1#include <type_traits>
2
3class Character{};
4
5// T4 will be Character
6using T4 = std::decay_t<const Character&>;

Let's apply this to our Build() template. Instead of constructing and returning a T, we'll construct and return a decayed T using std::decay_t<T>:

1#include <iostream>
2#include <type_traits>
3
Character Class|Show
4class Character {/*...*/};
17
18template <typename T>
19std::decay_t<T> Build(T&& Original) {
20  std::decay_t<T> NewObject{Original};
21  return NewObject;
22}
23
main Function (Unchanged)|Show
24int main() {/*...*/};

We can now also remove the intermediate NewObject local variable:

1#include <iostream>
2#include <type_traits>
3
Character Class|Show
4class Character {/*...*/};
17
18template <typename T>
19std::decay_t<T> Build(T&& Original) {
20  return std::decay_t<T>(Original);
21}
22
main Function (Unchanged)|Show
23int main() {/*...*/};

Our Build() function is now explicitly constructing and returning an object by value, but it's still ignoring the type's move semantics:

1Copying
2Copying

Let's fix that next.

The fact that our Build() function is always calling the lvalue version of our Character constructor is perhaps not surprising if we recall that a function argument and the associated parameter are not the same variables.

Even though the argument provided to Build() may be an rvalue returned from std::move(), within the context of the Build() function, the parameter Original is an lvalue. It has a name (Original) and a memory address (&Original).

We could of course cast it back to an rvalue using std::move() before forwarding it:

1template <typename T>
2std::decay_t<T> Build(T&& Original) {
3  return std::decay_t<T>(
4    std::move(Original)
5  );
6}

But we want our function to respect the original type that was provided as an argument. We don't want to assume it's always going to be a rvalue

Perfect forwarding is the process of forwarding arguments to other functions in a way that respects their original value category - whether they are lvalues or rvalues.

Wrapping an argument with the std::forward() function is the easiest way to implement this. std::forward() receives the type of the object as a template parameter, and the object itself as a function parameter:

1#include <iostream>
2#include <type_traits>
3
Character Class|Show
4class Character {/*...*/};
17
18template <typename T>
19std::decay_t<T> Build(T&& Original) {
20  return std::decay_t<T>(
21    std::forward<T>(Original)
22  );
23}
24
main Function (Unchanged)|Show
25int main() {/*...*/};

Our basic Build() function is now working correctly, complete with perfect forwarding:

1Copying
2Moving

One of the most common use cases for variadic functions is to implement the forwarding behavior seen in functions like std::make_unique() and the emplace() method on types like std::vector.

These functions cannot know in advance how many constructor arguments the underlying type will support. Therefore, they need to be implemented as variadic functions , accepting any number of arguments.

Let's do the same for our Build() function:

1#include <iostream>
2#include <type_traits>
3
Character Class|Show
4class Character {/*...*/};
23
24template <typename T, typename... Args>
25std::decay_t<T> Build(Args&&... Arguments){
26  return std::decay_t<T>{
27    Arguments...
28  };
29}
30
31int main(){
32  using namespace std::string_literals;
33  auto A{Build<Character>("Legolas"s, 100)};
34  auto B{Build<Character>(A)};
35  auto C{Build<Character>(std::move(A))};
36}

These arguments are being forwarded to a Character constructor but, without perfect forwarding, we've lost the benefits of move semantics:

1Constructing Legolas
2Copying Legolas
3Copying Legolas

To fix this, we can update our function to use std::forward() at the location where we're expanding our parameter pack:

1#include <iostream>
2#include <type_traits>
3
Character Class|Show
4class Character {/*...*/};
23
24template <typename T, typename... Args>
25std::decay_t<T> Build(Args&&... Arguments){
26  return std::decay_t<T>{
27    std::forward<Args>(Arguments)...
28  };
29}
30
main Function (Unchanged)|Show
31int main() {/*...*/};

1Constructing Legolas
2Copying Legolas
3Moving Legolas

In this lesson, we've introduced perfect forwarding, and how std::forward() can help us implement it. The key takeaways include:

• The basics of move semantics and how they allow for resource-efficient object management by transferring rather than copying data.
• The introduction and application of forwarding references, which allow templates to handle both lvalue and rvalue references.
• Using std::forward() to maintain the original value category of arguments, ensuring that our functions can perfectly forward arguments to other functions, preserving efficiency.
• A common use case for variadic functions is to collect arguments to be forwarded to some other function, and how to use std::forward() in that context.