Menu
Search

API Documentation

version 2.097.0

overview

View source code
Display the source code in core/memory.d from which this page was generated on github.
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 local clone.

Function core.memory.GC.inFinalizer

Queries the GC whether the current thread is running object finalization as part of a GC collection, or an explicit call to runFinalizers.

static extern(C) bool inFinalizer() nothrow @nogc @safe;

As some GC implementations (such as the current conservative one) don't support GC memory allocation during object finalization, this function can be used to guard against such programming errors.

Returns

true if the current thread is in a finalizer, a destructor invoked by the GC.

Example

// Only code called from a destructor is executed during finalization.
assert(!GC.inFinalizer);

Example

enum Outcome
{
    notCalled,
    calledManually,
    calledFromDruntime
}

static class Resource
{
    static Outcome outcome;

    this()
    {
        outcome = Outcome.notCalled;
    }

    ~this()
    {
        if (GC.inFinalizer)
        {
            outcome = Outcome.calledFromDruntime;

            import core.exception : InvalidMemoryOperationError;
            try
            {
                /*
                 * Presently, allocating GC memory during finalization
                 * is forbidden and leads to
                 * `InvalidMemoryOperationError` being thrown.
                 *
                 * `GC.inFinalizer` can be used to guard against
                 * programming erros such as these and is also a more
                 * efficient way to verify whether a destructor was
                 * invoked by the GC.
                 */
                cast(void) GC.malloc(1);
                assert(false);
            }
            catch (InvalidMemoryOperationError e)
            {
                return;
            }
            assert(false);
        }
        else
            outcome = Outcome.calledManually;
    }
}

static void createGarbage()
{
    auto r = new Resource;
    r = null;
}

writeln(Resource.outcome); // Outcome.notCalled
createGarbage();
GC.collect;
assert(
    Resource.outcome == Outcome.notCalled ||
    Resource.outcome == Outcome.calledFromDruntime);

auto r = new Resource;
GC.runFinalizers((cast(const void*)typeid(Resource).destructor)[0..1]);
writeln(Resource.outcome); // Outcome.calledFromDruntime
Resource.outcome = Outcome.notCalled;

debug(MEMSTOMP) {} else
{
    // assume Resource data is still available
    r.destroy;
    writeln(Resource.outcome); // Outcome.notCalled
}

r = new Resource;
writeln(Resource.outcome); // Outcome.notCalled
r.destroy;
writeln(Resource.outcome); // Outcome.calledManually

Authors

Sean Kelly, Alex Rønne Petersen

License

Boost License 1.0