destroy

Destroys the given object and optionally resets to initial state. It's used to destroy an object, calling its destructor or finalizer so it no longer references any other objects. It does not initiate a GC cycle or free any GC memory. If initialize is supplied false, the object is considered invalid after destruction, and should not be referenced.

void destroy(T obj)
void destroy(T obj)
void destroy(T obj)
void destroy(T obj)
void destroy(T obj)
void
destroy
(
bool initialize = true
T
)
(
ref T obj
)
if (
!is(T == struct) &&
!is(T == interface)
&&
!is(T == class)
&&
!__traits(isStaticArray, T)
)

Examples

Reference type demonstration

class C
{
    struct Agg
    {
        static int dtorCount;

        int x = 10;
        ~this() { dtorCount++; }
    }

    static int dtorCount;

    string s = "S";
    Agg a;
    ~this() { dtorCount++; }
}

C c = new C();
assert(c.dtorCount == 0);   // destructor not yet called
assert(c.s == "S");         // initial state `c.s` is `"S"`
assert(c.a.dtorCount == 0); // destructor not yet called
assert(c.a.x == 10);        // initial state `c.a.x` is `10`
c.s = "T";
c.a.x = 30;
assert(c.s == "T");         // `c.s` is `"T"`
destroy(c);
assert(c.dtorCount == 1);   // `c`'s destructor was called
assert(c.s == "S");         // `c.s` is back to its inital state, `"S"`
assert(c.a.dtorCount == 1); // `c.a`'s destructor was called
assert(c.a.x == 10);        // `c.a.x` is back to its inital state, `10`

C++ classes work too

extern (C++) class CPP
{
    struct Agg
    {
        __gshared int dtorCount;

        int x = 10;
        ~this() { dtorCount++; }
    }

    __gshared int dtorCount;

    string s = "S";
    Agg a;
    ~this() { dtorCount++; }
}

CPP cpp = new CPP();
assert(cpp.dtorCount == 0);   // destructor not yet called
assert(cpp.s == "S");         // initial state `cpp.s` is `"S"`
assert(cpp.a.dtorCount == 0); // destructor not yet called
assert(cpp.a.x == 10);        // initial state `cpp.a.x` is `10`
cpp.s = "T";
cpp.a.x = 30;
assert(cpp.s == "T");         // `cpp.s` is `"T"`
destroy!false(cpp);           // destroy without initialization
assert(cpp.dtorCount == 1);   // `cpp`'s destructor was called
assert(cpp.s == "T");         // `cpp.s` is not initialized
assert(cpp.a.dtorCount == 1); // `cpp.a`'s destructor was called
assert(cpp.a.x == 30);        // `cpp.a.x` is not initialized
destroy(cpp);
assert(cpp.dtorCount == 2);   // `cpp`'s destructor was called again
assert(cpp.s == "S");         // `cpp.s` is back to its inital state, `"S"`
assert(cpp.a.dtorCount == 2); // `cpp.a`'s destructor was called again
assert(cpp.a.x == 10);        // `cpp.a.x` is back to its inital state, `10`

Value type demonstration

int i;
assert(i == 0);           // `i`'s initial state is `0`
i = 1;
assert(i == 1);           // `i` changed to `1`
destroy!false(i);
assert(i == 1);           // `i` was not initialized
destroy(i);
assert(i == 0);           // `i` is back to its initial state `0`

Nested struct type

int dtorCount;
struct A
{
    int i;
    ~this()
    {
        dtorCount++; // capture local variable
    }
}
A a = A(5);
destroy!false(a);
assert(dtorCount == 1);
assert(a.i == 5);

destroy(a);
assert(dtorCount == 2);
assert(a.i == 0);

// the context pointer is now null
// restore it so the dtor can run
import core.lifetime : emplace;
emplace(&a, A(0));
// dtor also called here

destroy

Examples

Meta

Source