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.manageStreamSubscription(someStream.listen(() => null));
   }

   @override
   void manageStreamSubscription(StreamSubscription sub) {
     _disposable.manageStreamSubscription(sub);
   }

   // ...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.