cpp/language/destructor

A destructor is a special that is called when the  ends. The purpose of the destructor is to free the resources that the object may have acquired during its lifetime.

Syntax
@1@ Typical declaration of a destructor. @2@ Virtual destructor is usually required in a base class. @3@ Forcing a destructor to be generated by the compiler. @4@ Disabling the implicit destructor. @5@ Formal syntax of a destructor declaration.

Explanation
The destructor is called whenever an object's ends, which includes
 * program termination, for objects with static


 * end of scope, for objects with automatic storage duration and for temporaries whose life was extended by binding to a reference
 * , for objects with dynamic storage duration
 * end of the full, for nameless temporaries
 * , for objects with automatic storage duration when an exception escapes their block, uncaught.

The destructor may also be called directly, e.g. to destroy an object that was constructed using or through an allocator member function such as, to destroy an object that was constructed through the allocator. Note that calling a destructor directly for an ordinary object, such as a local variable, invokes undefined behavior when the destructor is called again, at the end of scope.

In generic contexts, the destructor call syntax can be used with an object of non-class type; this is known as pseudo-destructor call: see.

{{rrev|since=c++20|

Prospective destructor
A class may have one or more prospective destructors, one of which is selected as the destructor for the class.

In order to determine which prospective destructor is the destructor, at the end of the definition of the class, is performed among prospective destructors declared in the class with an empty argument list. If the overload resolution fails, the program is ill-formed. Destructor selection does not the selected destructor, and the selected destructor may be deleted.

All prospective destructors are special member functions. If no user-declared prospective destructor is provided for class, the compiler will always declare one (see below), and the implicitly declared prospective destructor is also the destructor for. }}

Implicitly-declared destructor
If no user-declared destructor is provided for a  (,, or ), the compiler will always declare a destructor as an  member of its class.

As with any implicitly-declared special member function, the exception specification of the implicitly-declared destructor is non-throwing unless. In practice, implicit destructors are unless the class is "poisoned" by a base or member whose destructor is.

Deleted implicitly-declared destructor
The implicitly-declared or explicitly defaulted destructor for class is  if any of the following is true:
 * has a non-static data member that cannot be destructed (has deleted or inaccessible destructor).
 * has direct or virtual base class that cannot be destructed (has deleted or inaccessible destructors).


 * The implicitly-declared destructor is virtual (because the base class has a virtual destructor) and the lookup for the deallocation function results in a call to ambiguous, deleted, or inaccessible function.

Trivial destructor
The destructor for class is trivial if all of the following is true: A trivial destructor is a destructor that performs no action. Objects with trivial destructors don't require a delete-expression and may be disposed of by simply deallocating their storage. All data types compatible with the C language (POD types) are trivially destructible.
 * The destructor is not user-provided (meaning, it is either implicitly declared, or explicitly defined as defaulted on its first declaration).
 * The destructor is not virtual (that is, the base class destructor is not virtual).
 * All direct base classes have trivial destructors.
 * All non-static data members of class type (or array of class type) have trivial destructors.

Implicitly-defined destructor
If an implicitly-declared destructor is not deleted, it is implicitly defined (that is, a function body is generated and compiled) by the compiler when it is. This implicitly-defined destructor has an empty body.

Destruction sequence
For both user-defined or implicitly-defined destructors, after executing the body of the destructor and destroying any automatic objects allocated within the body, the compiler calls the destructors for all non-static non-variant data members of the class, in reverse order of declaration, then it calls the destructors of all direct non-virtual base classes in (which in turn call the destructors of their members and their base classes, etc), and then, if this object is of most-derived class, it calls the destructors of all virtual bases.

Even when the destructor is called directly (e.g. ), the return statement in does not return control to the caller immediately: it calls all those member and base destructors first.

Virtual destructors
Deleting an object through pointer to base invokes undefined behavior unless the destructor in the base class is :

A common guideline is that a destructor for a base class must be either public and virtual or protected and nonvirtual.

Pure virtual destructors
A destructor may be declared, for example in a base class which needs to be made abstract, but has no other suitable functions that could be declared pure virtual. A pure virtual destructor must have a definition, since all base class destructors are always called when the derived class is destroyed:

Exceptions
As any other function, a destructor may terminate by throwing an, however if this destructor happens to be called during , std is called instead.

Although std may sometimes be used to detect stack unwinding in progress, it is generally considered bad practice to allow any destructor to terminate by throwing an exception. This functionality is nevertheless used by some libraries, such as SOCI and Galera 3, which rely on the ability of the destructors of nameless temporaries to throw exceptions at the end of the full expression that constructs the temporary.

in Library fundamental TS v3 may have a potentially-throwing destructor, which throws an exception when the scope is exited normally and the exit function throws an exception.