Disposable class

Allows the creation of managed objects, including helpers for common patterns.

We recommend consuming this class in one of two ways.

  1. As a base class
  2. As a concrete proxy

We do not recommend using this class as a mixin or as an interface. Use as a mixin can cause the onDispose method to be shadowed. Use as an interface is just cumbersome.

If an interface is desired, the DisposableManager... interfaces are available.

In the case below, the class is used as a mixin. This provides both default implementations and flexibility since it does not occupy a spot in the class hierarchy. However, consumers should use caution if they choose to employ this pattern.

Helper methods, such as listenToStream allow certain cleanup to be automated. Managed subscriptions will be automatically canceled when dispose is called on the object.

 class MyDisposable extends Object with Disposable {
   StreamController _controller = new StreamController();

   MyDisposable(Stream someStream) {
     listenToStream(someStream, (_) => print('some stream'));
     manageStreamController(_controller);
   }

   Future<Null> onDispose() {
     // Other cleanup
   }
 }

The getManagedDisposer helper allows you to clean up arbitrary objects on dispose so that you can avoid keeping track of them yourself. To use it, simply provide a callback that returns a Future of any kind. For example:

 class MyDisposable extends Object with Disposable {
   StreamController _controller = new StreamController();

   MyDisposable() {
     var thing = new ThingThatRequiresCleanup();
     getManagedDisposer(() {
       thing.cleanUp();
       return new Future(() {});
     });
   }
 }

Cleanup will then be automatically performed when the parent object is disposed. If returning a future is inconvenient or otherwise undesirable, you may also return null explicitly.

Implementing the onDispose method is entirely optional and is only necessary if there is cleanup required that is not covered by one of the helpers.

It is possible to schedule a callback to be called after the object is disposed for purposes of further, external, cleanup or bookkeeping (for example, you might want to remove any objects that are disposed from a cache). To do this, use the didDispose future:

 var myDisposable = new MyDisposable();
 myDisposable.didDispose.then((_) {
   // External cleanup
 });

Below is an example of using the class as a concrete proxy.

 class MyLifecycleThing implements DisposableManager {
   Disposable _disposable = new Disposable();

   MyLifecycleThing() {
     _disposable.listenToStream(someStream, (_) => null));
   }

   @override
   StreamSubscription<T> listenToStream<T>(
       Stream<T> stream, void onData(T event),
       {Function onError, void onDone(), bool cancelOnError}) {
     return _disposable.listenToStream(
       stream, onData,
       onError: onError,
       onDone: onDone,
       cancelOnError: cancelOnError
     );
   }

   // ...more methods

   Future<Null> unload() async {
     await _disposable.dispose();
   }
 }

In this case, we want MyLifecycleThing to have its own lifecycle without explicit reference to Disposable. To do this, we use composition to include the Disposable machinery without changing the public interface of our class or polluting its lifecycle.

Implemented types
Implementers

Constructors

Disposable()

Properties

didDispose → Future<Null>
A Future that will complete when this object has been disposed.
read-only
disposableTypeName → String
A type name, similar to runtimeType but intended to work with minified code. [...]
read-only
disposalTreeSize → int
The total size of the disposal tree rooted at the current Disposable instance. [...]
read-only
isDisposed → bool
Whether this object has been disposed.
read-only
isDisposedOrDisposing → bool
Whether this object has been disposed or is currently disposing. [...]
read-only
isDisposing → bool
Whether this object is in the process of being disposed. [...]
read-only
isLeakFlagSet → bool
Whether the leak flag for this object has been set. [...]
read-only
isOrWillBeDisposed → bool
Whether the disposal of this object has been requested, is in progress, or is complete. [...]
read-only
hashCode → int
The hash code for this object.
read-only, inherited
runtimeType → Type
A representation of the runtime type of the object.
read-only, inherited

Methods

awaitBeforeDispose<T>(Future<T> future) → Future<T>
Add future to a list of futures that will be awaited before the object is disposed. [...]
@mustCallSuper, override
dispose() → Future<Null>
Dispose of the object, cleaning up to prevent memory leaks.
flagLeak([String description ]) → void
Flag the object as having been disposed in a way that allows easier profiling. [...]
@mustCallSuper
getManagedDelayedFuture<T>(Duration duration, T callback()) → Future<T>
Creates a Future that will complete, with the value returned by callback, after the given amount of time has elapsed. [...]
@mustCallSuper, override
getManagedDisposer(Disposer disposer) ManagedDisposer
Automatically handle arbitrary disposals using a callback. [...]
@mustCallSuper, override
getManagedPeriodicTimer(Duration duration, void callback(Timer timer)) → Timer
Creates a periodic Timer that will be cancelled if active upon disposal.
@mustCallSuper, override
getManagedTimer(Duration duration, void callback()) → Timer
Creates a Timer instance that will be cancelled if active upon disposal.
@mustCallSuper, override
listenToStream<T>(Stream<T> stream, void onData(T event), { Function onError, void onDone(), bool cancelOnError }) → StreamSubscription<T>
Returns a StreamSubscription which handles events from the stream using the provided onData, onError and onDone handlers. [...]
@mustCallSuper, override
manageAndReturnDisposable(Disposable disposable) Disposable
Automatically dispose another object when this object is disposed. [...]
@mustCallSuper, override
manageAndReturnTypedDisposable<T extends Disposable>(T disposable) → T
Automatically dispose another object when this object is disposed. [...]
@mustCallSuper, override
manageCompleter<T>(Completer<T> completer) → Completer<T>
Ensure that a completer is completed when the object is disposed. [...]
@mustCallSuper, override
manageDisposable(Disposable disposable) → void
Automatically dispose another object when this object is disposed. [...]
@mustCallSuper, override
manageDisposer(Disposer disposer) → void
Automatically handle arbitrary disposals using a callback. [...]
@mustCallSuper, override
manageStreamController(StreamController controller) → void
Automatically cancel a stream controller when this object is disposed. [...]
@mustCallSuper, override
manageStreamSubscription(StreamSubscription subscription) → void
Automatically cancel a stream subscription when this object is disposed. [...]
@mustCallSuper, override
onDispose() → Future<Null>
Callback to allow arbitrary cleanup on dispose.
@protected
onWillDispose() → Future<Null>
Callback to allow arbitrary cleanup as soon as disposal is requested (i.e. dispose is called) but prior to disposal actually starting. [...]
@protected
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed.
inherited
toString() → String
Returns a string representation of this object.
inherited

Operators

operator ==(dynamic other) → bool
The equality operator.
inherited

Static Methods

disableDebugMode() → void
Disables all debug features enabled by enableDebugMode.
enableDebugMode({bool disableLogging, bool disableTelemetry }) → void
Causes messages to be logged for various lifecycle and management events. [...]