C# Reference ยท Classes and Object-Oriented Concepts
Finalizers
Reference for C# finalizers: the ~ClassName syntax, when the garbage collector runs them, why they are rarely needed and how Dispose suppresses them.
A finalizer is a method the garbage collector calls on an object after it has found that nothing references it any more, just before the object's memory is reclaimed. In C# you write it with a tilde and the class name, ~Name(). Despite the common name "destructor", it is not like a C++ destructor: you cannot call it, you cannot know when it runs, and in some situations it does not run at all (for example when the process exits quickly).
Because of that, finalizers are a safety net, not a cleanup mechanism. Normal cleanup belongs in IDisposable.Dispose(). Most classes should never have a finalizer; you need one only when the class directly owns an unmanaged resource that no SafeHandle wraps.
class NativeBuffer { ~NativeBuffer() { // last-chance cleanup of unmanaged memory } }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
class Name { ~Name() { /* body */ } }
The compiler turns ~Name() into an override of Object.Finalize() that wraps your body in a try and calls the base finalizer in a finally. You cannot write Finalize() directly.
| Rule | Description |
|---|---|
| Allowed on | Classes only (not structs, records structs or interfaces). |
| Modifiers | None. No access modifier, no parameters, no overloads. |
| Count | At most one per class. |
| Inheritance | Finalizers are chained automatically from most derived to base. |
Usage notes
- Timing is not guaranteed. The finalizer runs on a dedicated finalizer thread some time after the object becomes unreachable, and not at all if the process ends first. Do not rely on it for correctness (flushing data, releasing locks).
- Finalizable objects are costly. They are tracked on a special queue and survive at least one extra collection. A class with a finalizer that is always disposed should call
GC.SuppressFinalize(this)inDispose()to avoid that cost. - The finalizer thread cannot touch other managed objects safely. They may already be finalized. This is why the standard pattern uses
Dispose(bool disposing)and skips managed fields whendisposingisfalse. - Exceptions escaping a finalizer terminate the process. Keep the body minimal and catch everything.
- Do not resurrect the object by storing
thissomewhere reachable. It is legal but confusing. - Prefer
SafeHandle. Subclasses ofSafeHandlealready implement a reliable finalizer, so wrappers around native handles typically need none of their own. - Order is undefined. Two objects that became unreachable together can finalize in any order.
GC.Collect()andWaitForPendingFinalizers()are for demos and tests only. Production code should not force collections.