destroy and scoped - D Programming Language

Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Downloads
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Calendar
  - Discord (community-run)
  - Forums
  - IRC
  - Wiki
  - Issues
  - Contributing
  - Contributors
  - Foundation
  - Security Team
  - Donate
  - Sponsors
- Resources
  - Tour
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - run.dlang.io
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

# destroy and scoped

We have seen the lifetimes of objects in the Lifetimes and Fundamental Operations chapter.

In later chapters, we have seen that the objects are prepared for use in the constructor, which is called `this()`; and the final operations of objects are applied in the destructor, which is called `~this()`.

For structs and other value types, the destructor is executed at the time when the lifetime of an object ends. For classes and other reference types, it is executed by the garbage collector some time in the future. The important distinction is that the destructor of a class object is not executed when its lifetime ends.

System resources are commonly returned back to the system in destructors. For example, `std.stdio.File` returns the file resource back to the operating system in its destructor. As it is not certain when the destructor of a class object will be called, the system resources that it holds may not be returned until too late when other objects cannot get a hold of the same resource.

##### An example of calling destructors late

Let's define a class to see the effects of executing class destructors late. The following constructor increments a `static` counter, and the destructor decrements it. As you remember, there is only one of each `static` member, which is shared by all of the objects of a type. Such a counter would indicate the number of objects that are yet to be destroyed.

    class LifetimeObserved {
        int[] array;           // ← Belongs to each object

        static size_t counter; // ← Shared by all objects

        this() {
            /* We are using a relatively large array to make each
             * object consume a large amount of memory. Hopefully
             * this will make the garbage collector call object
             * destructors more frequently to open up space for
             * more objects. */
            array.length = 30_000;

            /* Increment the counter for this object that is being
             * constructed. */
            ++counter;
        }

        ~this() {
            /* Decrement the counter for this object that is being
             * destroyed. */
            --counter;
        }
    }

The following program constructs objects of that class inside a loop:

    import std.stdio;

    void main() {
        foreach (i; 0 .. 20) {
            auto variable = new LifetimeObserved;  // ← start
            write(LifetimeObserved.counter, ' ');
        } // ← end

        writeln();
    }

The lifetime of each `LifetimeObserved` object is in fact very short: Its life starts when it is constructed by the `new` keyword and ends at the closing curly bracket of the `foreach` loop. Each object then becomes the responsibility of the garbage collector. The start and end comments indicate the start and end of the lifetimes.

Even though there is up to one object alive at a given time, the value of the counter indicates that the destructor is not executed when the lifetime ends:

    1 2 3 4 5 6 7 8 2 3 4 5 6 7 8 2 3 4 5 6

According to that output, the memory sweep algorithm of the garbage collector has delayed executing the destructor for up to 8 objects. (Note: The output may be different depending on the garbage collection algorithm, available memory, and other factors.)

##### `destroy()` to execute the destructor

`destroy()` executes the destructor for an object:

    void main() {
        foreach (i; 0 .. 20) {
            auto variable = new LifetimeObserved;
            write(LifetimeObserved.counter, ' ');
            destroy(variable);
        }

        writeln();
    }

Like before, the value of `LifetimeObserved.counter` is incremented by the constructor as a result of `new`, and becomes 1. This time, right after it gets printed, `destroy()` executes the destructor for the object and the value of the counter is decremented again down to zero. For that reason, this time its value is always 1:

    1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1

Once destroyed, the object should be considered to be in an invalid state and must not be used anymore:

        destroy(variable);
        // ...
        // Warning: Using a potentially invalid object
        writeln(variable.array);

Although `destroy()` is primarily for reference types, it can also be called on `struct` objects to destroy them before the end of their normal lifetimes.

##### When to use

As has been seen in the previous example, `destroy()` is used when resources need to be released at a specific time without relying on the garbage collector.

##### Example

We had designed an `XmlElement` struct in the Constructor and Other Special Functions chapter. That struct was being used for printing XML elements in the format `<tag>value</tag>`. Printing the closing tag has been the responsibility of the destructor:

    struct XmlElement {
        // ...

        ~this() {
            writeln(indentation, "</", name, '>');
        }
    }

The following output was produced by a program that used that struct. This time, I am replacing the word "class" with "course" to avoid confusing it with the `class` keyword:

    <courses>
      <course0>
        <grade>
          72
        </grade>   ← The closing tags appear on correct lines
        <grade>
          97
        </grade>   ←
        <grade>
          90
        </grade>   ←
      </course0>   ←
      <course1>
        <grade>
          77
        </grade>   ←
        <grade>
          87
        </grade>   ←
        <grade>
          56
        </grade>   ←
      </course1>   ←
    </courses>     ←

The previous output happens to be correct because `XmlElement` is a `struct`. The desired output is achieved simply by placing the objects in appropriate scopes:

    void main() {
        const courses = XmlElement("courses", 0);

        foreach (courseId; 0 .. 2) {
            const courseTag = "course" ~ to!string(courseId);
            const courseElement = XmlElement(courseTag, 1);

            foreach (i; 0 .. 3) {
                const gradeElement = XmlElement("grade", 2);
                const randomGrade = uniform(50, 101);

                writeln(indentationString(3), randomGrade);

            } // ← gradeElement is destroyed

        } // ← courseElement is destroyed

    } // ← courses is destroyed

The destructor prints the closing tags as the objects gets destroyed.

To see how classes behave differently, let's convert `XmlElement` to a class:

    import std.stdio;
    import std.array;
    import std.random;
    import std.conv;

    string indentationString(int level) {
        return replicate(" ", level * 2);
    }

    class XmlElement {
        string name;
        string indentation;

        this(string name, int level) {
            this.name = name;
            this.indentation = indentationString(level);

            writeln(indentation, '<', name, '>');
        }

        ~this() {
            writeln(indentation, "</", name, '>');
        }
    }

    void main() {
        const courses = new XmlElement("courses", 0);

        foreach (courseId; 0 .. 2) {
            const courseTag = "course" ~ to!string(courseId);
            const courseElement = new XmlElement(courseTag, 1);

            foreach (i; 0 .. 3) {
                const gradeElement = new XmlElement("grade", 2);
                const randomGrade = uniform(50, 101);

                writeln(indentationString(3), randomGrade);
            }
        }
    }

As the responsibility of calling the destructors are now left to the garbage collector, the program does not produce the desired output:

    <courses>
      <course0>
        <grade>
          57
        <grade>
          98
        <grade>
          87
      <course1>
        <grade>
          84
        <grade>
          60
        <grade>
          99
        </grade>   ← The closing tags appear at the end
        </grade>   ←
        </grade>   ←
      </course1>   ←
        </grade>   ←
        </grade>   ←
        </grade>   ←
      </course0>   ←
    </courses>     ←

The destructor is still executed for every object but this time at the end when the program is exiting. (Note: The garbage collector does not guarantee that the destructor will be called for every object. In reality, it is possible that there are no closing tags printed at all.)

`destroy()` ensures that the destructor is called at desired points in the program:

    void main() {
        const courses = new XmlElement("courses", 0);

        foreach (courseId; 0 .. 2) {
            const courseTag = "course" ~ to!string(courseId);
            const courseElement = new XmlElement(courseTag, 1);

            foreach (i; 0 .. 3) {
                const gradeElement = new XmlElement("grade", 2);
                const randomGrade = uniform(50, 101);

                writeln(indentationString(3), randomGrade);

                destroy(gradeElement);
            }

            destroy(courseElement);
        }

        destroy(courses);
    }

With those changes, the output of the code now matches the output of the code that use structs:

    <courses>
      <course0>
        <grade>
          66
        </grade>   ← The closing tags appear on correct lines
        <grade>
          75
        </grade>   ←
        <grade>
          68
        </grade>   ←
      </course0>   ←
      <course1>
        <grade>
          73
        </grade>   ←
        <grade>
          62
        </grade>   ←
        <grade>
          100
        </grade>   ←
      </course1>   ←
    </courses>     ←

##### `scoped()` to call the destructor automatically

The program above has a weakness: The scopes may be exited before the `destroy()` lines are executed, commonly by thrown exceptions. If the `destroy()` lines must be executed even when exceptions are thrown, a solution is to take advantage of `scope()` and other features that we saw in the Exceptions chapter.

Another solution is to construct class objects by `std.typecons.scoped` instead of by the `new` keyword. `scoped()` wraps the class object inside a `struct` and the destructor of that `struct` object destroys the class object when itself goes out of scope.

The effect of `scoped()` is to make class objects behave similar to struct objects regarding lifetimes.

With the following changes, the program produces the expected output as before:

    import std.typecons;
    // ...
    void main() {
        const courses = scoped!XmlElement("courses", 0);

        foreach (courseId; 0 .. 2) {
            const courseTag = "course" ~ to!string(courseId);
            const courseElement = scoped!XmlElement(courseTag, 1);

            foreach (i; 0 .. 3) {
                const gradeElement = scoped!XmlElement("grade", 2);
                const randomGrade = uniform(50, 101);

                writeln(indentationString(3), randomGrade);
            }
        }
    }

Note that there are no `destroy()` lines anymore.

`scoped()` is a function that returns a special `struct` object encapsulating the actual `class` object. The returned object acts as a proxy to the encapsulated one. (In fact, the type of `courses` above is `Scoped`, not `XmlElement`.)

When the destructor of the `struct` object is called automatically as its lifetime ends, it calls `destroy()` on the `class` object that it encapsulates. (This is an application of the Resource Acquisition Is Initialization (RAII) idiom. `scoped()` achieves this by the help of templates and `alias this`, both of which we will see in later chapters.)

It is desirable for a proxy object to be used as conveniently as possible. In fact, the object that `scoped()` returns can be used exactly like the actual `class` type. For example, the member functions of the actual type can be called on it:

    import std.typecons;

    class C {
        void foo() {
        }
    }

    void main() {
        auto p = scoped!C();
        p.foo();    // Proxy object p is being used as type C
    }

However, that convenience comes with a price: The proxy object may hand out a reference to the actual object right before destroying it. This can happen when the actual `class` type is specified explicitly on the left hand-side:

        C c = scoped!C();    // ← BUG
        c.foo();             // ← Accesses a destroyed object

In that definition, `c` is not the proxy object; rather, as defined by the programmer, a `class` variable referencing the encapsulated object. Unfortunately, the proxy object that is constructed on the right-hand side gets terminated at the end of the expression that constructs it. As a result, using `c` in the program would be an error, likely causing a runtime error:

    Segmentation fault

For that reason, do not define `scoped()` variables by the actual type:

        C         a = scoped!C();    // ← BUG
        auto      b = scoped!C();    // ← correct
        const     c = scoped!C();    // ← correct
        immutable d = scoped!C();    // ← correct

##### Summary

- `destroy()` is for executing the destructor of a class object explicitly.
- Objects that are constructed by `scoped()` are destroyed upon leaving their respective scopes.
- It is a bug to define `scoped()` variables by the actual type.

Copyright © 1999-2026 by the D Language Foundation | Page generated by Ddoc on Wed Aug 5 11:24:17 2026