DisposableStack

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

TheDisposableStack object represents a stack ofdisposers to run when the stack itself is disposed. Disposer functions are executed in reverse order of registration, with strong error handling guarantees. Calling itsmove() method will transfer responsibility for calling the current registered disposers to a newDisposableStack and prevent registering any additional disposers.

Description

ADisposableStack is not exactly a "stack" in terms of its interface. It has several methods for pushing disposers to it, but it has no way to pop one disposer off. Rather,all disposers are popped and executed one-by-one when the stack is disposed.

You registerdisposable resources to theDisposableStack using itsuse(),adopt(), ordefer() methods.

using disposer = new DisposableStack();const reader = disposer.use(stream.getReader());

Then, when thedisposer goes out of scope, all resources registered to it are disposed in reverse order of registration, unless they have been moved out withmove().

It is good practice tonot extract the resource acquisition expression to a separate statement, no matter how long the expression is. You should always wrap theuse() oradopt() call around the resource acquisition expression to ensure that the resource is registered to the stack immediately.

using disposer = new DisposableStack();const reader = stream.getReader();disposer.use(reader);

Functionally, these two code snippets are equivalent. However, the first one is less error-prone because the resource is declared and registered in a single line. If someone puts more code between the second and third lines of the second snippet, an error could occur, causing the resource to leak.

Constructor

DisposableStack(): Creates a newDisposableStack object.

Instance properties

These properties are defined onDisposableStack.prototype and shared by allDisposableStack instances.

DisposableStack.prototype.constructor: The constructor function that created the instance object. ForDisposableStack instances, the initial value is theDisposableStack constructor.
DisposableStack.prototype.disposed: Read-only. Returnstrue if theDisposableStack has been disposed, orfalse if not.
DisposableStack.prototype[Symbol.toStringTag]: The initial value of the[Symbol.toStringTag] property is the string"DisposableStack". This property is used inObject.prototype.toString().

Instance methods

DisposableStack.prototype.adopt(): Registers a value that doesn't implement the disposable protocol to the stack by providing a custom disposer function.
DisposableStack.prototype.defer(): Takes a callback function to be called when the stack is disposed.
DisposableStack.prototype.dispose(): Disposes this stack by calling all disposers registered to it in reverse order of registration.
DisposableStack.prototype.move(): Creates a newDisposableStack instance that contains the same disposers as this stack, and then marks this stack as disposed, without calling any disposers.
DisposableStack.prototype.use(): Registers a value that implements the disposable protocol to the stack.
DisposableStack.prototype[Symbol.dispose]: An alias for thedispose() method.