1. Abstract
Add a class template,indirect_value
, to the C++ Standard Library to support free-store-allocated objects with value-like semantics.
2. Change history
Changes in P1950r2
-
Wording fixes.
-
Add allocator support.
-
support.constexpr
Changes in P1950r1
-
Add design discussion.
-
Add comparison with
andunique_ptr
.polymorphic_value -
Add node-based container and hot-cold splitting as further motivational examples.
-
Add examples of similar classes already in use.
3. Introduction
The class template,indirect_value
, confers value-like semantics on a free-store-allocated object. An indirect_value
may hold an object of a class T, copying the indirect_value
will copy the object T
. When a parent object contains a member of type indirect_value < T >
and
is accessed through a const access path, const
ness will propagate from the parent object to the instance of T
owned by the indirect_value
member.
3.1. Motivation
It may be desirable for a class member to be an incomplete type or for the storage used by a member object to be separate from the class itself. In both such cases, the member would traditionally be represented as pointer:
class MyClass { AType data_member_ ; AnotherType * indirect_data_member_ ; };
The author of such a class will need to implement special member functions as the compiler-generated special member functions will not function correctly (indirect data will not be copied, assigned to or deleted, only the pointer).
Special care will be needed when using the class in multithreaded environments. An instance of
accessed through a const-access-path
will not propagate the
-ness to the indirect data (only to the pointer itself) as pointers do not propagate
to their pointees.
The class template
is a drop-in replacement for pointer members in cases where non-polymorphic data referenced by the
pointer member is logically part of the class. Use of
will ensure that the compiler-generated special member functions
behave correctly and that
is propagated to indirect data.
3.1.1. Node-based containers
A tree or linked list can be implemented as a node-based container. This gives stable references to data in the nodes at the cost of memory indirection when accessing data.
Nodes would typically contain data and pointer(s) to other nodes so that the list or tree can be navigated:
class ForwardListNode { int data_ ; ForwardListNode * next_ ; }; class ForwardList { ForwardListNode * head_ ; public : // ... };
The special member functions of
would need to be user-implemented as the
compiler-generated versions would not copy, move or delete the nodes correctly.
Care must be taken when implementing
-qualified member functions as
will not propagate down
from the
to the
s nor to the data that the nodes contain.
Implementing the ForwardList and ForwardListNode with
corrects these issues:
class ForwardListNode { int data_ ; indirect_value < ForwardListNode > next_ ; }; class ForwardList { indirect_value < ForwardListNode > head_ ; public : // ... };
Compiler-generated special member functions will behave correctly and do not need to be written manually.
-propagation will allow the compiler to ensure that data that is logically part of the container
cannot be modified through a
access path.
3.1.2. Hot-cold splitting
When working with collections of data, CPU caches are often under-utilized when algorithms access certain data members much more frequently than others. This results in some cache lines becoming busier than others, prefetchers preemptively caching memory which is later evicted without being used by the CPU or memory bandwidth becoming a limiting factor in performance. In such cases segregating data structures in terms of hot and cold data can remove pressure on system resources.
class Element { SmallData frequently_accessed_data ; LargeData infrequently_accessed_data ; }; vector < Element > elements ; auto active = find_if ( elements . begin (), elements . end (), []( const auto & e ) { return e . frequently_accessed_data . active (); });
In such cases adding a level of indirection to the larger, less frequently-accessed data can relieve bandwidth
pressure [C. Ericson]. Using
in this refactoring does not change guarantees around
ness. Compiler-generated special member functions will behave correctly and do not need to be manually implemented.
class Element { SmallData frequently_accessed_data ; indirect_value < LargeData > infrequently_accessed_data ; }; vector < Element > elements ; auto active = find_if ( elements . begin (), elements . end (), []( const auto & e ) { return e . frequently_accessed_data . active (); });
3.1.3. Pointer to Implementation - PImpl
In C++, when anything in a class definition changes, dependent classes require recompilation. As early as 1992 the
Handle/Body idiom was suggested to break this dependency [J. Coplien]. From this pattern, the PImpl idiom was
specialised [H. Sutter]. Despite its relative maturity, using the PImpl idiom requires careful thought about copying
and
-propagation.
// Header file class widget { public : widget (); ~ widget (); private : class impl ; std :: unique_ptr < impl > pimpl_ ; };
// Implementation file class widget :: impl { // ::: }; widget :: widget () : pimpl_ { std :: make_unique < impl > ( /*...*/ } { } // Destructor needs to be defined in a the same TU as <code data-opaque bs-autolink-syntax='`widget::impl`'>widget::impl</code>. widget ::~ widget () = default ;
For convenience, the widget class will be referred to as the “visible class” and impl class the “
class”. Note, semantically the
class is the implementation details of the visible class.
3.1.3.1. Issues with const-propagation
Usingstd :: unique_ptr
to store the implementation object introduces an issue - within a const
-qualified
member function, an instance of the visible class can mutate data inside the implementation object. This is because const
-qualification applies only to the unique_ptr
value, and not the pointed-to-object.
The compiler is unable to make thread-compatibility assumptions for
objects when
does not propagate:
does not mean immutable in the face of pointer-like-member data.
The desired semantics of a PImpl-owner are value-like, like those of
which has appropriate
and non-
-qualified overloads for
and
.
3.1.3.2. Issues with copies
The copy-constructor and copy-assignment operator ofstd :: unique_ptr
are deleted. Users of a class with a std :: unique_ptr
member will be
required to implement copy-construction and copy-assignment [S. Meyers].
3.1.3.3. An indirect_value
implementation of the PImpl Idiom
Using indirect_value
to implement the PImpl idiom ensures that the PImpl object is const
when accessed through a const
access path and that compiler-generated special member functions will behave correctly and do not need to be manually implemented.
// Header file class widget { public : widget (); widget ( widget && rhs ) noexcept ; widget ( const widget & rhs ); widget & operator = ( widget && rhs ) noexcept ; widget & operator = ( const widget & rhs ); ~ widget (); private : class impl ; std :: indirect_value < impl >> pimpl ; };
// Implementation file class widget :: impl { // ::: }; // Special-member functions need to be defined in a the same TU as <code data-opaque bs-autolink-syntax='`widget::impl`'>widget::impl</code>. widget :: widget () : pimpl ( new impl ) {} widget :: widget ( widget && rhs ) noexcept = default ; widget :: widget ( const widget & rhs ) = default ; widget & widget :: operator = ( widget && rhs ) noexcept = default ; widget & widget :: operator = ( const widget & rhs ) = default ; widget ::~ widget () = default ;
3.2. Design decisions
3.2.1. Should there be be an empty state?
There is a design decision to be made about the default constructor of
.
It could place
in an empty state with no owned object or it could
default construct an owned object so that
is never empty. This would
either add a requirement that
supports default construction or only support default
construction conditionally when also supported by
.
If
is never empty then
must be default constructible for
to be a regular type. The default constructor of
would then need to allocate memory, which cannot be controlled by the user-supplied
copier or deleter.
If the default constructed state of
is non-empty then the moved from
state should be similarly non-empty. This requires that
is noexcept move constructible.
Allowing an empty state for
imposes preconditions on operator* and operator->
(similar to those of the raw pointer it may be replacing) but removes requirements on
and the need
to allocate memory.
A nullable
could be mimicked with
but this is verbose, does not solve the problem of
needing to be noexcept
move-constructible and would require partial template specialization of
to avoid the overhead that would be incurred by a nullable
. But perhaps
the most unfortunate side effect of this approach is that to access the underlying
the
must be dereferenced to get to the
, which then requires
a second dereference to get to the underlying
. This pattern makes usage unwieldy.
As designed,
has an empty state where it owns no object.
A default constructed
is empty and the empty state is the state of a moved-from object.
3.2.2. How are allocators supported?
It may be desirable for users to control the way memory is managed by an instance of a class.
Classes such as
and
allow an allocator to be specified as a template argument
to control memory management. There is existing precedence for allocator support of types in the memory
management library;
supports allocators via
, [M. Knejp] suggested
the introduction of
to support allocator use with
.
Like
,
allows a deleter to be provided as a template argument
so that disposal of the owned object can be customized.
also allows copying to be
customized by specifying a copier, another template argument. However, this raises the question of if the
copier and deleter should be combined types. If not combined then both must hold either a reference to an
allocator (doubling the storage requirements) or, if encapsulating the allocator, then one must own the
allocator while the second holds a reference. While combining the interfaces into one type would solve this
it would reduce the usage with custom lambdas without specialising for a combined object to be created
from the two copier and deleter lambda via something akin to the overload pattern. This issue is not
addressed further, instead opting to keep to the pre-allocator design, but the authors welcome feedback here.
Memory management for
can be fully controlled via the
function
which allows passing in an allocator to control the source of memory. Custom copier and deleter then use
the allocator for allocations and deallocations.
3.2.3. Is there a small-buffer object optimization?
Previous revisions of the paper suggested this was permissible as a quality of implementation improvement.
However, this revision has introduced allocator support, which offers an alternative mechanism for
supporting the small-buffer optimization. An allocator, supporting small buffer optimization, can be
provided. This allows achieving the same results while separating the details of the small buffer
optimization from
.
3.3. Prior Art
There have been previous proposal for deep-copying smart pointers that proposed copy semantics [W. Brown].cloned_ptr
was proposed in [J. Coe], however under guidance of LEWG this was renamed to polymorphic_value
. With this change in name came the addition of const propagation.
This paper is not unique in these ideas. GitHub code search finds 602k lines of code referencing "PImpl" and 99 C
++ repositories claiming to provide generic implementations of Pimpl. Google Carbon Language, an experimental successor to C++ includes
as a vocabulary type. Additionally other authors have addressed this
topic [A. Upadyshev]. Some generic implementations of note in the wild are:
Project | Link | Deep Copying | Const Propagation |
---|---|---|---|
Carbon Language | https://github.com/carbon-language/carbon-lang/blob/trunk/common/indirect_value.h | Yes | Yes |
Boost Pimpl | https://github.com/sean-/boost-pimpl | Yes | Yes |
pimpl | https://github.com/JonChesterfield/pimpl | Yes | No |
impl_ptr | https://github.com/sth/impl_ptr | Yes | Yes |
Simpl | https://github.com/oliora/samples/blob/master/spimpl.h | Yes | Yes |
smart_pimpl | https://github.com/SBreezyx/smart_pimpl | No | No |
pimpl_on_stack | https://github.com/kuznetsss/pimpl_on_stack/ | Yes | Yes |
deep_const_ptr | https://github.com/torbjoernk/deep_const_ptr | No | Yes |
Divergence on issues such as deep copying and const propagation along with subtleties in implementation mean that a single standardized solution would be of broad benefit to the community of C++ users.
3.4. Completeness of T
Smart pointer types in the Standard Library expect that some of the members can be instantiated with incomplete types [H.Hinnant]. Similarly, this is the case forindirect_value
, the table outlines the expected behaviour for incomplete
pointer types:
Function | Description | Incomplete/Complete |
---|---|---|
| Default constructor | Incomplete |
| Copy-constructor | Complete |
| Move-constructor | Incomplete |
| Destructor | Complete |
| Copy-assignment | Complete |
| Move-assignment | Complete |
| Indirection-operator | Incomplete |
| Indirection-operator | Incomplete |
| Member-of-pointer-operator | Incomplete |
| Member-of-pointer-operator | Incomplete |
| Bool-operator | Incomplete |
| Swap | Incomplete |
3.5. Comparison with unique_ptr < T >
and polymorphic_value < T >
The class template
is in many respects similar to
and the proposed
[J. Coe]. The table below highlights the similarities and differences:
Behaviour |
|
|
|
---|---|---|---|
Default constructed state | Empty | Empty | Empty |
Copyable | Yes | Yes | No |
Const-propagating | Yes | Yes | No |
Polymorphic | No | Yes | Yes |
Customizable memory access | Yes | No | Yes |
3.6. Impact on the standard
This proposal is a pure library extension. It requires additions to be made to the standard library header< memory >
.
4. Technical specifications
4.1. Additions in [memory.syn] 20.2.2:
// [indirect.value], class template indirect_value template < class T > struct default_copy ; template < class T > struct copier_traits ; template < class T , class C = std :: default_copy < T > , class D = typename std :: copier_traits < C >:: deleter_type > class indirect_value ; template < class T , class ... Ts > constexpr indirect_value < T > make_indirect_value ( Ts && ... ts ); template < class T , class A = std :: allocator < T > , class ... Ts > constexpr indirect_value < T > allocate_indirect_value ( std :: allocator_arg_t , A & a , Ts && ... ts ); template < class T > constexpr void swap ( indirect_value < T >& p , indirect_value < T >& u ) noexcept ;
4.2. X.X Class template copier_traits
[copier.traits]
namespace std { template < class T > struct copier_traits { using deleter_type = * see below * ; }; }
using deleter_type = see below ;
-
Type:
if the qualified-idT :: deleter_type
is valid and denotes a type; otherwise,T :: deleter_type
ifvoid ( * )( U * )
is of the formT
for typesU * ( * )( V )
andU
; otherwise, there is no memberV
.deleter_type
4.3. X.Y Class template default_copy
[default.copy]
The class template default_copy [J. Coe] serves as the default copier for the class templatenamespace std { template < class T > struct default_copy { using deleter_type = default_delete < T > ; constexpr T * operator ()( const T & t ) const ; }; } // namespace std
indirect_value
.
The template parameter T
of default_copy
may be an incomplete type.
-
Returns:
new T ( t );
4.4. X.Z Class template indirect_value
[indirect_value]
4.4.1. X.Z.1 Class template indirect_value
general [indirect_value.general]
An indirect_value
is an object that owns another object and manages that other object through a pointer. More precisely, an indirect value is an object v
that stores a pointer to a second object p
and will dispose of p
when v
is itself destroyed (e.g., when leaving block scope (9.7)). In this context, v
is said to own p
.
An
object is empty if it does not own a pointer.
Copying a non-empty
will copy the owned object so that the copied
will have its own unique copy of the owned object.
Copying from an empty
produces another empty
.
Copying and disposal of the owned object can be customised by supplying a copier and deleter.
The template parameter
of
must be a non-union class type.
The template parameter
of
may be an incomplete type.
A copier and deleter are said to be present if a
object is constructed from a non-null pointer, or from a
object where a copier and deleter are present.
4.4.2. X.Z.2 Class template indirect_value
synopsis [indirect_value.synopsis]
template < class T , class C = std :: default_copy < T > , class D = typename std :: copier_traits < C >:: deleter_type > class indirect_value { public : using value_type = T ; // Constructors constexpr indirect_value () noexcept ; constexpr explicit indirect_value ( T * p , C c = C {}, D d = D {}); constexpr indirect_value ( const indirect_value & p ); constexpr indirect_value ( indirect_value && p ) noexcept ; template < class ... Ts > constexpr indirect_value ( std :: in_place_t , Ts && ... ts ); // See below // Destructor constexpr ~ indirect_value (); // Assignment constexpr indirect_value & operator = ( const indirect_value & p ); constexpr indirect_value & operator = ( indirect_value && p ) noexcept ; // Modifiers constexpr void swap ( indirect_value < T >& p ) noexcept ; // Observers constexpr T & operator * (); constexpr T * operator -> (); constexpr const T & operator * () const ; constexpr const T * operator -> () const ; constexpr explicit operator bool () const noexcept ; }; // indirect_value creation template < class T , class ... Ts > constexpr indirect_value < T > make_indirect_value ( Ts && ... ts ); // See below template < class T , class A = std :: allocator < T > , class ... Ts > constexpr indirect_value < T > allocate_indirect_value ( std :: allocator_arg_t , A & a , Ts && ... ts ); // indirect_value specialized algorithms template < class T > constexpr void swap ( indirect_value < T >& p , indirect_value < T >& u ) noexcept ; } // end namespace std
4.4.3. X.Z.3 Class template indirect_value
constructors [indirect_value.ctor]
-
Effects: Constructs an empty
.indirect_value -
Postconditions:
.bool ( * this ) == false
-
Effects: Constructs a
which owns p, initializing the stored pointer with p. The copier and deleter of theindirect_value
constructed are moved fromindirect_value
andc
. Ifd
is null, creates an empty object.p -
Constraints:
is true.is_nothrow_move_assignable_v < C >
is true.is_nothrow_move_assignable_v < D > -
Preconditions:
andC
meet the Cpp17CopyConstructible requirements. If the argumentsD
and/orc
are not supplied, thend
and/orC
respectively are default constructible types that are not pointer types. IfD
is non-null then the expressionp
returns a non-nullc ( * p )
is as if copy constructed from *p. The expressionT *
has well-defined behaviour, and does not throw exceptions.d ( p ) -
Postconditions:
.bool ( * this ) == bool ( p ) -
Mandates: The expression
is well-formed.d ( p )
-
Constraints:
is true.is_copy_constructible_v < T > -
Effects: Creates a
object that owns a copy of the object managed byindirect_value
. The copy is created by the copier inp
. Ifp
has a custom copier and deleter then the custom copier and deleter of thep
constructed are copied from those inindirect_value
.p -
Remarks: The constructor must work with pointer to an complete type
.T -
Throws: Any exception thrown by the copier or
if required storage cannot be obtained.bad_alloc -
Postconditions:
.bool ( * this ) == bool ( p )
-
Effects: Move-constructs an
instance fromindirect_value
. Ifp
has a custom copier and deleter then the copier and deleter of thep
constructed are the same as those inindirect_value
.p -
Postconditions:
contains the old value of* this
.p
is empty.p
-
Effects: Constructs an
which owns an object of typeindirect_value
direct-non-list-initialized withT std :: forward < Ts > ( ts )... -
Throws: Any exception thrown by the selected constructor of
orT
if required storage cannot be obtained.bad_alloc -
Preconditions:
.is_same_v < C , default_copy > && is_same_v < D , default_delete >
4.4.4. X.Z.4 Class template indirect_value
destructor [indirect_value.dtor]
constexpr ~ indirect_value ();
-
Effects: If
there are no effects. If a custom deleter* this
is present thend
is called and the copier and deleter are destroyed. Otherwise the destructor of the managed object is called.d ( p ) -
Remarks: The constructor must work with pointer to an complete type
.T
4.4.5. X.Z.5 Class template indirect_value
assignment [indirect_value.assignment]
constexpr indirect_value & operator = ( const indirect_value & p );
-
Constraints:
is true.is_copy_assignable_v < C >
is true.is_copy_assignable_v < D > -
Effects: If
is empty, assigns an empty object. Otherwise creates an object that owns a copy of the object managed byp
. The copy is created by the copier inp
, and the copier and deleter ofp
are copied from those in* this
.p -
Remarks: The function must work with pointer to an complete type
.T -
Throws: Any exception thrown by the copier or
if required storage cannot be obtained.bad_alloc -
Returns:
.* this -
Postconditions:
.bool ( * this ) == bool ( p )
-
Constraints:
is true.is_nothrow_move_assignable_v < C >
is true.is_nothrow_move_assignable_v < D > -
Effects: Ownership of the resource managed by
is transferred to this. Ifp
has a custom copier and deleter then the copier and deleter ofp
is the same as those in* this
.p -
Remarks: The function must work with pointer to an complete type
.T -
Returns:
.* this -
Postconditions:
contains the old value of* this
.p
is empty.p
4.4.6. X.Z.6 Class template indirect_value
modifiers [indirect_value.modifiers]
constexpr void swap ( indirect_value & p ) noexcept ;
-
Effects: Exchanges the contents of
andp
.* this
4.4.7. X.Z.7 Class template indirect_value
observers [indirect_value.observers]
constexpr T & operator * (); constexpr const T & operator * () const ;
-
Preconditions:
is true.bool ( * this ) -
Returns: A reference to the owned object.
constexpr T * operator -> () noexcept ; constexpr const T * operator -> () const noexcept ;
-
Preconditions:
is true.bool ( * this ) -
Returns: A pointer to the owned object.
-
Returns: false if the
is empty, otherwise true.indirect_value
4.4.8. X.Z.8 Class template indirect_value
creation [indirect_value.creation]
template < class T , class U = T , class ... Ts > constexpr indirect_value < T > make_indirect_value ( Ts && ... ts );
-
Constraints:
is true.is_constructible_v < U , Ts ... > -
Preconditions:
meets theU
requirements.Cpp17CopyConstructible -
Returns: A
owning an object of type direct-non-list-initialized withindirect_value < T >
.std :: forward < Ts > ( ts )... -
Preconditions:
.is_same_v < C , default_copy > && is_same_v < D , default_delete >
template < class T , class U = T , class A = std :: allocator < U > , class ... Ts > constexpr indirect_value < T > allocate_indirect_value ( std :: allocator_arg_t , A & a , Ts && ... ts );
-
Constraints:
is true.is_constructible_v < U , Ts ... > -
Preconditions:
meets theU
requirements.Cpp17CopyConstructible -
Returns: A
owning an object of type direct-non-list-initialized withindirect_value < T >
.std :: forward < Ts > ( ts )... -
Preconditions
.is_same_v < C , allocator_copy > && is_same_v < D , allocator_delete >
5. Acknowledgements
Contributions to the open source reference implementation have forwarded the design, including but not limited to contribution from Kilian Henneberger, Ed Catmur, Stephen Kelly & Malcolm Parsons. The authors would like to thank Thomas Russell for the original suggestions of allocator support, Bengt Gustafsson for useful discussion on SBO and nullstate representation via std::optional specialisation, Jonathan Wakely & Daniel Krügler for document reviews, Andrew Bennieston for useful discussions on the topic and the BSI panel for on-going support.6. References
[W. Brown] n3339: A Preliminary Proposal for a Deep-Copying Smart Pointer, Walter E. Brown, 2012
[J. Coe] p0201r5: A polymorphic value-type for C++
[J. Coplien] Advanced C++ Programming Styles and Idioms (Addison-Wesley), James O. Coplien, 1992
[C. Ericson] Memory Optimization, Christer Ericson, Games Developers Conference, 2003
[R. Grimm] Visiting a std::variant with the Overload Pattern
[H. Hinnant] “Incomplete types and shared_ptr / unique_ptr”, Howard Hinnant, 2011
[M. Knejp] P0316R0: allocate_unique and allocator_delete
[H. Sutter] "Pimpls - Beauty Marks You Can Depend On", Herb Sutter, 1998
[Impl] Reference implementation: indirect_value, J.B.Coe
[S. Meyers] Effective Modern C++, Item 22: When using the Pimpl Idiom, define special member functions in the implementation file, Scott Meyers, 2014
[A. Upadyshev] PIMPL, Rule of Zero and Scott Meyers, Andrey Upadyshev, 2015