Programming in D – Tutorial and Reference
Ali Çehreli

Other D Resources

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