Modern C++ API Design

Rvalue references and modern type design

Titus Winters (titus@google.com)

Confidential + Proprietary Confidential + Proprietary

A Talk in Three Parts

A Refresher on Rvalue-References
How to use Rvalue-References in API Design
How to use those APIs in Type Design

Confidential + Proprietary
Refresher: rvalue refs

What is an rvalue ref?

Confidential + Proprietary
Refresher: rvalue refs

What is an rvalue ref?

A reference to an rvalue

Confidential + Proprietary
Refresher: rvalue refs

What is an rvalue?

Confidential + Proprietary
Refresher: rvalue refs

What is an rvalue?

Something you could only have on the right side of

an assignment.
Confidential + Proprietary
Refresher: rvalue refs

What is an rvalue?

int foo = GetInt();

GetInt() = foo;

Confidential + Proprietary
Refresher: rvalue refs

What is an rvalue?
int GetInt();
int foo = GetInt();
GetInt() = foo;

Confidential + Proprietary
Refresher: rvalue refs

What is an rvalue?
int& GetInt();
int foo = GetInt();
GetInt() = foo;

Confidential + Proprietary
Refresher: rvalue refs

What is an rvalue ref, informally?

Confidential + Proprietary
Refresher: rvalue refs

What is an rvalue ref, informally?

(Usually) A value without a name, that you couldn’t

print in a debugger.
Confidential + Proprietary
Refresher: rvalue refs

void f() {
GetStrings(); // <- ???
}

Confidential + Proprietary
Refresher: rvalue refs

void f() {
AcceptStrings(GetStrings());
}

Confidential + Proprietary
Refresher: rvalue refs

void f() {
std::vector<std::string> strings = GetStrings();
}

Confidential + Proprietary
Refresher: rvalue refs

void f() {
std::vector<std::string> strings = GetStrings();
auto more_strings = strings;
}

Confidential + Proprietary
Refresher: rvalue refs

What is an rvalue ref, informally?

(Sometimes) An lvalue that was std::move’ed.

Confidential + Proprietary
Refresher: rvalue refs

What is std::move?

A cast to rvalue-reference.

Confidential + Proprietary
Refresher: rvalue refs

What is std::move?

“A name eraser”

Confidential + Proprietary
Refresher: rvalue refs

void f() {
std::vector<std::string> strings = GetStrings();
auto more_strings = std::move(strings);
}

Confidential + Proprietary
Refresher: rvalue refs
void ZeroNamesIsATemporary() {
AcceptsStrings(GetStrings());
}

void OneNameIsAMove() {
std::vector<std::string> strings = GetStrings();
}

void TwoNamesIsACopy() {
std::vector<std::string> strings = GetStrings();
auto copy = strings;
}

void AndStdMoveMakesANameNotCount() {
std::vector<std::string> strings = GetStrings();
auto not_a_copy = std::move(strings);
}
Confidential + Proprietary
Refresher: rvalue refs

What’s a move c’tor/move assignment op?

Confidential + Proprietary
Refresher: rvalue refs

What’s a move c’tor/move assignment op?

How a type implements move semantics.

Confidential + Proprietary
Refresher: rvalue refs

class Foo {
public:
Foo(const Foo&); // copy c'tor
Foo(Foo&&) noexcept; // move c'tor

Foo& operator= (const Foo&); // copy

Foo& operator= (Foo&&) noexcept; // move
};
Confidential + Proprietary
Refresher: rvalue refs

What’s a move c’tor/move assignment op?

Move is a source-mutating copy

Confidential + Proprietary
Refresher: rvalue refs

Foo::Foo(Foo&& other)
: member_(std::move(other.member_)) noexcept {}

Foo& Foo::operator= (Foo&& other) noexcept {

member_ = std::move(other.member_);
return *this;
}

Confidential + Proprietary
Refresher: rvalue refs

What’s a forwarding reference?

Confidential + Proprietary
Refresher: rvalue refs

What’s a forwarding reference?

How you express in templates “take whatever

category this was and keep it the same.”

Confidential + Proprietary
Refresher: rvalue refs
template <typename T, typename... Args>
typename memory_internal::MakeUniqueResult<T>::scalar make_unique(
    Args&&... args) {
  return std::unique_ptr<T>(new T(std::forward<Args>(args)...));
}

Confidential + Proprietary
Refresher: rvalue refs

What’s reference qualification?

Confidential + Proprietary
Refresher: rvalue refs

What’s reference qualification?

Like const-qualification on a method: restrict calls

to a method based on the reference-category of
the object.
Confidential + Proprietary
Refresher: rvalue refs
class Foo {
public:
void Print() & { cout << "lvalue" << endl; }
void Print() && { cout << "rvalue" << endl; }
};

void f() {
Foo f;
f.Print();
std::move(f).Print();
}
Confidential + Proprietary
A Talk in Three Parts

A Refresher on Rvalue-References
How to use Rvalue-References in API Design
How to use those APIs in Type Design

Confidential + Proprietary
Good Uses for Rvalue-Refs
Optimization: const-ref + rvalue-ref overload set

void std::vector<T>::push_back(const T&);

void std::vector<T>::push_back(T&&);

These are everywhere in the standard

Confidential + Proprietary
Good Uses for Rvalue-Refs
Optimization: Ref qualified member function overload set

T& std::optional<T>::value() &;

const T& std::optional<T>::value() const &;
T&& std::optional<T>::value() &&;
const T&& std::optional<T>::value() const &&;

Translation: no matter the const-ness or reference category of the optional, give

me the same version of the underlying T.

Confidential + Proprietary
Good Uses for Rvalue-Refs
Ref qualified member function - Rvalue ref qualified means “steal”

std::string std::stringbuf::str() const;

std::string std::stringbuf::str() &&;

std::stringbuf buf;
buf << "Hello World!";
return buf.str();

Confidential + Proprietary
Good Uses for Rvalue-Refs
Ref qualified member function - Rvalue ref qualified means “steal”

std::string std::stringbuf::str() const;

std::string std::stringbuf::str() &&;

std::stringbuf buf;
buf << "Hello World!";
return std::move(buf).str();

Confidential + Proprietary
Good Uses for Rvalue-Refs
Or rvalue ref qualified means ”do once”.

Consider a call-once, move-only Callable:

std::mfunction<int(std::string)> GetCallable();
void f() {
GetCallable()("Hello World!");
}

Confidential + Proprietary
Good Uses for Rvalue-Refs
Or rvalue ref qualified means ”do once”.

Consider a call-once, move-only Callable:

void f(std::mfunction<int(std::string)> c) {
std::move(c)("Hello World!");
}

Confidential + Proprietary
Good Uses for Rvalue-Refs
As a parameter, when not an overload set: “maybe move”.

The proposed RCU type (wg21.link/P0561) has

bool try_update(const snapshot_ptr<T>& expected,

std::unique_ptr<T>&& desired);

Confidential + Proprietary
Bad Uses for Rvalue-Refs
As a parameter, when not an overload set: “disallow copies”

void Expensive(std::string&& big);

Confidential + Proprietary
Bad Uses for Rvalue-Refs
As a parameter, when not an overload set: “disallow copies”

void Expensive(std::string&& big);

std::string my_data = GetData();

Expensive(std::move(my_data));

Confidential + Proprietary
Bad Uses for Rvalue-Refs
As a parameter, when not an overload set: “disallow copies”

void Expensive(std::string&& big);

std::string my_data = GetData();

Expensive(std::move(my_data));
Expensive(std::move(my_data));

Confidential + Proprietary
Bad Uses for Rvalue-Refs
As a parameter, when not an overload set: “because optimization”

void Cheap(std::string s);

or

void Cheap(const std::string& s);

void Cheap(std::string&& s);

Confidential + Proprietary
Bad Uses for Rvalue-Refs
As a parameter, in a deleted member of an overload set, to “prevent passing
temporaries.”

Foo(const std::string& s);

Foo(std::string&& s) = delete;

Foo f("Hello");

Confidential + Proprietary
Bad Uses for Rvalue-Refs
As a parameter, in a deleted member of an overload set, to “prevent passing
temporaries.”

Foo(const std::string& s);

Foo(std::string&& s) = delete;

{
std::string hello = "Hello";
Foo f(hello);
}

Confidential + Proprietary
Bad Uses for Rvalue-Refs
As a parameter, in a deleted member of an overload set, to “prevent passing
temporaries.”

Foo(const std::string& s);

Foo(std::string&& s) = delete;

{
std::string hello = "Hello";
auto f = make_unique<Foo>(hello);
}

Confidential + Proprietary
C++ 11 and on: New Type Designs
Other move-semantics designs:

● move-only types/unique ownership: std::unique_ptr

Types that are less-Regular (std::string_view)

Confidential + Proprietary
A Talk in Three Parts

A Refresher on Rvalue-References
How to use Rvalue-References in API Design
How to use those APIs in Type Design

Confidential + Proprietary
Properties of types
● Invariants
● Thread safety
● Comparable
● Ordered
● Copyable
● Mutable
● Movable

Confidential + Proprietary
Properties of types - Invariants
Type design is really "What invariants are there on the data members of a T?"

std::vector has invariants like:

● capacity >= size

● data[i] is a valid T for all i in [0, size)
● data is a valid / non-null pointer with an allocation of capacity

Confidential + Proprietary
Properties of types - Invariants
Invariants also involve the state model for your type (if any).

Avoid adding states if possible.

● Prefer factory functions or c’tors that throw, rather than T::Init() methods.
● Avoid distinct moved-from states.

Confidential + Proprietary
Properties of types - Thread Safety
Which operations are safe to call upon a T concurrently?

● thread-safe:
○ Concurrent const and non-const operations are OK
● thread-compatible:
○ Concurrent const operations are OK.
○ Any non-const operation requires all operations to synchronize
● thread-unsafe:
○ Not even const operations can be invoked concurrently

Confidential + Proprietary
Properties of types - Comparability
Are operators == and != defined?

Confidential + Proprietary
Types - Logical State
There may be a difference between the data members and the logical state of a type.

std::string a = "abc";
std::string b;
b.reserve(1000);
b.push_back('a');
b.push_back('b');
b.push_back('c');
assert(a == b);
Confidential + Proprietary
Properties of types - Ordering
Is there a partial or total order for objects of type T?

Which of the operators ==, !=, <, >, <=, and >= are defined?

Confidential + Proprietary
Properties of types - Ordering
Don’t define Ordering just to put something in a map. If you need a sort order for
storage, that’s a property of the storage, not the type.

Ordering depends on the logical state of the type.

Confidential + Proprietary
Properties of types - Copyable
Given a T, can you duplicate its logical state into a new T?

There are two important constraints for copyable types:

● If it is copy-assignable (operator=) it should be copy-constructible (a copy

constructor). In most cases the reverse is also true.
● The logical state is what is copied.
T a = b;
assert(a == b);

Confidential + Proprietary
Properties of types - Mutable
Given a T, can you modify its logical state? In particular, can you modify its state via
operator=?

Confidential + Proprietary
Properties of types - Movable
Given a T, can you move its logical state into a new T?

Confidential + Proprietary
Properties of types - Movable
Given a T, can you move its logical state into a new T?

std::is_move_constructible is equivalent to the following being well-formed:

T Foo();

T a = Foo();

Confidential + Proprietary
Regular Types
AKA “value” types - “do what ints do”

● Thread-compatible
● Comparable and ordered
● Copyable, assignable, movable
● Moved-from state?

Example: std::string

Confidential + Proprietary
Structs
Types with no data invariants

Example: std::pair

Confidential + Proprietary
Non-Copyable / Business logic types
These are usually blocks of business logic that hold accessors / handles / streams
and perform some business-logic permutations.

● Non-copyable
● Usually non-movable
● Incomparable / unordered

Confidential + Proprietary
Immutable Types
In situations where an object is shared across many threads concurrently, it may be
preferable for all objects of that type to be immutable (after construction).

● Potentially copyable
● Immutable
● Not movable

Confidential + Proprietary
Reference types
Non-owning, lightweight types that may become invalid because of external
changes.

Good for parameters, lightweight representations.

Tricky semantics: careful review of type design strongly suggested.

Example: std::string_view, gsl::span/absl::Span

Confidential + Proprietary
Move-only types
If your type needs to uniquely represent some resource, move-only semantics may
be a good model.

● non-copyable
● Data invariants are guaranteed

Example: std::unique_ptr

Confidential + Proprietary
What’s Next?
● Google Style Guide
● Abseil Tip of the Week
● Updated Core Guidelines?

Confidential + Proprietary
A Talk in Three Parts

Questions?

Confidential + Proprietary