11 Classes [class]

11.4 Class members [class.mem]

11.4.7 Destructors [class.dtor]

A declaration whose declarator-id has an unqualified-id that begins with a ~ declares a prospective destructor; its declarator shall be a function declarator ([dcl.fct]) of the form

ptr-declarator ( parameter-declaration-clause ) noexcept-specifier

_{o p t}

attribute-specifier-seq

_{o p t}

where the ptr-declarator consists solely of an id-expression, an optional attribute-specifier-seq, and optional surrounding parentheses, and the id-expression has one of the following forms:

(1.1)
in a member-declaration that belongs to the member-specification of a class or class template but is not a friend declaration ([class.friend]), the id-expression is ~class-name and the class-name is the injected-class-name ([class.pre]) of the immediately-enclosing entity or
(1.2)
otherwise, the id-expression is nested-name-specifier ~class-name and the class-name is the injected-class-name of the class nominated by the nested-name-specifier.

A prospective destructor shall take no arguments ([dcl.fct]).

Each decl-specifier of the decl-specifier-seq of a prospective destructor declaration (if any) shall be friend, inline, virtual, or constexpr.

If a class has no user-declared prospective destructor, a prospective destructor is implicitly declared as defaulted ([dcl.fct.def]).

An implicitly-declared prospective destructor is an inline public member of its class.

An implicitly-declared prospective destructor for a class X will have the form ~X()

At the end of the definition of a class, overload resolution is performed among the prospective destructors declared in that class with an empty argument list to select the destructor for the class, also known as the selected destructor.

The program is ill-formed if overload resolution fails.

Destructor selection does not constitute a reference to, or odr-use ([basic.def.odr]) of, the selected destructor, and in particular, the selected destructor may be deleted ([dcl.fct.def.delete]).

The address of a destructor shall not be taken.

[Note 1:

A return statement in the body of a destructor cannot specify a return value ([stmt.return]).

— end note]

A destructor can be invoked for a const, volatile or const volatile object.

const and volatile semantics ([dcl.type.cv]) are not applied on an object under destruction.

They stop being in effect when the destructor for the most derived object ([intro.object]) starts.

[Note 2:

A declaration of a destructor that does not have a noexcept-specifier has the same exception specification as if it had been implicitly declared ([except.spec]).

— end note]

A defaulted destructor for a class X is defined as deleted if

(7.1)
any potentially constructed subobject has class type M (or possibly multi-dimensional array thereof) and M has a destructor that is deleted or is inaccessible from the defaulted destructor or, in the case of a variant member, is non-trivial,
(7.2)
or, for a virtual destructor, lookup of the non-array deallocation function results in an ambiguity or in a function that is deleted or inaccessible from the defaulted destructor.

A destructor is trivial if it is not user-provided and if

(8.1)
the destructor is not virtual,
(8.2)
all of the direct base classes of its class have trivial destructors, and
(8.3)
for all of the non-static data members of its class that are of class type (or array thereof), each such class has a trivial destructor.

Otherwise, the destructor is non-trivial.

A defaulted destructor is a constexpr destructor if it is constexpr-suitable ([dcl.constexpr]).

Before a defaulted destructor for a class is implicitly defined, all the non-user-provided destructors for its base classes and its non-static data members are implicitly defined.

A prospective destructor can be declared virtual ([class.virtual]) and with a pure-specifier ([class.abstract]).

If the destructor of a class is virtual and any objects of that class or any derived class are created in the program, the destructor shall be defined.

[Note 3:

Some language constructs have special semantics when used during destruction; see [class.cdtor].

— end note]

After executing the body of the destructor and destroying any objects with automatic storage duration allocated within the body, a destructor for class X calls the destructors for X's direct non-variant non-static data members other than anonymous unions, the destructors for X's non-virtual direct base classes and, if X is the most derived class ([class.base.init]), its destructor calls the destructors for X's virtual base classes.

All destructors are called as if they were referenced with a qualified name, that is, ignoring any possible virtual overriding destructors in more derived classes.

Bases and members are destroyed in the reverse order of the completion of their constructor (see [class.base.init]).

[Note 4:

A return statement ([stmt.return]) in a destructor might not directly return to the caller; before transferring control to the caller, the destructors for the members and bases are called.

— end note]

Destructors for elements of an array are called in reverse order of their construction (see [class.init]).

A destructor is invoked implicitly

(14.1)
for a constructed object with static storage duration ([basic.stc.static]) at program termination ([basic.start.term]),
(14.2)
for a constructed object with thread storage duration ([basic.stc.thread]) at thread exit,
(14.3)
for a constructed object with automatic storage duration ([basic.stc.auto]) when the block in which an object is created exits ([stmt.dcl]),
(14.4)
for a constructed temporary object when its lifetime ends ([conv.rval], [class.temporary]).

In each case, the context of the invocation is the context of the construction of the object.

A destructor may also be invoked implicitly through use of a delete-expression ([expr.delete]) for a constructed object allocated by a new-expression ([expr.new]); the context of the invocation is the delete-expression.

[Note 5:

An array of class type contains several subobjects for each of which the destructor is invoked.

— end note]

A destructor can also be invoked explicitly.

A destructor is potentially invoked if it is invoked or as specified in [expr.new], [stmt.return], [dcl.init.aggr], [class.base.init], and [except.throw].

A program is ill-formed if a destructor that is potentially invoked is deleted or not accessible from the context of the invocation.

At the point of definition of a virtual destructor (including an implicit definition), the non-array deallocation function is determined as if for the expression delete this appearing in a non-virtual destructor of the destructor's class (see [expr.delete]).

If the lookup fails or if the deallocation function has a deleted definition ([dcl.fct.def]), the program is ill-formed.

[Note 6:

This assures that a deallocation function corresponding to the dynamic type of an object is available for the delete-expression ([class.free]).

— end note]

In an explicit destructor call, the destructor is specified by a ~ followed by a type-name or computed-type-specifier that denotes the destructor's class type.

The invocation of a destructor is subject to the usual rules for member functions ([class.mfct]); that is, if the object is not of the destructor's class type and not of a class derived from the destructor's class type (including when the destructor is invoked via a null pointer value), the program has undefined behavior.

[Note 7:

Invoking delete on a null pointer does not call the destructor; see [expr.delete].

— end note]

[Example 1: struct B { virtual ~B() { } }; struct D : B { ~D() { } }; D D_object; typedef B B_alias; B* B_ptr = &D_object; void f() { D_object.B::~B(); // calls B's destructor B_ptr->~B(); // calls D's destructor B_ptr->~B_alias(); // calls D's destructor B_ptr->B_alias::~B(); // calls B's destructor B_ptr->B_alias::~B_alias(); // calls B's destructor } — end example]

[Note 8:

An explicit destructor call must always be written using a member access operator ([expr.ref]) or a qualified-id ([expr.prim.id.qual]); in particular, the unary-expression ~X() in a member function is not an explicit destructor call ([expr.unary.op]).

— end note]

[Note 9:

Explicit calls of destructors are rarely needed.

One use of such calls is for objects placed at specific addresses using a placement new-expression.

Such use of explicit placement and destruction of objects can be necessary to cope with dedicated hardware resources and for writing memory management facilities.

[Example 2: void* operator new(std::size_t, void* p) { return p; } struct X { X(int); ~X(); }; void f(X* p); void g() { // rare, specialized use: char* buf = new char[sizeof(X)]; X* p = new(buf) X(222); // use buf[] and initialize f(p); p->X::~X(); // cleanup } — end example]

— end note]

Once a destructor is invoked for an object, the object's lifetime ends; the behavior is undefined if the destructor is invoked for an object whose lifetime has ended ([basic.life]).

[Example 3:

If the destructor for an object with automatic storage duration is explicitly invoked, and the block is subsequently left in a manner that would ordinarily invoke implicit destruction of the object, the behavior is undefined.

— end example]

[Note 10:

The notation for explicit call of a destructor can be used for any scalar type name ([expr.prim.id.dtor]).

Allowing this makes it possible to write code without having to know if a destructor exists for a given type.

For example: typedef int I; I* p; p->I::~I();

— end note]

A destructor shall not be a coroutine.