Drake
never_destroyed< T > Class Template Reference

Wraps an underlying type T such that its storage is a direct member field of this object (i.e., without any indirection into the heap), but unlike most member fields T's destructor is never invoked. More...

#include <drake/common/never_destroyed.h>

Public Member Functions

template<typename... Args>
 never_destroyed (Args &&... args)
 Passes the constructor arguments along to T using perfect forwarding. More...
 
 ~never_destroyed ()=default
 Does nothing. Guaranteed! More...
 
Taccess ()
 Returns the underlying T reference. More...
 
const Taccess () const
 
Does not allow copy, move, or assignment
 never_destroyed (const never_destroyed &)=delete
 
never_destroyedoperator= (const never_destroyed &)=delete
 
 never_destroyed (never_destroyed &&)=delete
 
never_destroyedoperator= (never_destroyed &&)=delete
 

Detailed Description

template<typename T>
class drake::never_destroyed< T >

Wraps an underlying type T such that its storage is a direct member field of this object (i.e., without any indirection into the heap), but unlike most member fields T's destructor is never invoked.

This is especially useful for function-local static variables that are not trivially destructable. We shouldn't call their destructor at program exit because of the "indeterminate order of ... destruction" as mentioned in cppguide's Static and Global Variables section, but other solutions to this problem place the objects on the heap through an indirection.

Compared with other approaches, this mechanism more clearly describes the intent to readers, avoids "possible leak" warnings from memory-checking tools, and is probably slightly faster.

Example uses:

The singleton pattern:

class Singleton {
public:
static Singleton& getInstance() {
static never_destroyed<Singleton> instance;
return instance.access();
}
private:
friend never_destroyed<Singleton>;
Singleton() = default;
};

A lookup table, created on demand the first time its needed, and then reused thereafter:

enum class Foo { kBar, kBaz };
Foo ParseFoo(const std::string& foo_string) {
using Dict = std::unordered_map<std::string, Foo>;
static const drake::never_destroyed<Dict> string_to_enum{
std::initializer_list<Dict::value_type>{
{"bar", Foo::kBar},
{"baz", Foo::kBaz},
}
};
return string_to_enum.access().at(foo_string);
}

Constructor & Destructor Documentation

◆ never_destroyed() [1/3]

never_destroyed ( const never_destroyed< T > &  )
delete

◆ never_destroyed() [2/3]

never_destroyed ( never_destroyed< T > &&  )
delete

◆ never_destroyed() [3/3]

never_destroyed ( Args &&...  args)
inlineexplicit

Passes the constructor arguments along to T using perfect forwarding.

◆ ~never_destroyed()

~never_destroyed ( )
default

Does nothing. Guaranteed!

Member Function Documentation

◆ access() [1/2]

T& access ( )
inline

Returns the underlying T reference.

◆ access() [2/2]

const T& access ( ) const
inline

◆ operator=() [1/2]

never_destroyed& operator= ( const never_destroyed< T > &  )
delete

◆ operator=() [2/2]

never_destroyed& operator= ( never_destroyed< T > &&  )
delete

The documentation for this class was generated from the following file: