Disposable

An implementation of disposable for Dart.

Build Status

Documentation

API Docs are available.

Installation

Add Disposable to your project's pubspec.yaml file and run pub get. We recommend the following version constraint:

dependencies:
  disposable: '>=0.3.0<0.4.0'

Main Classes

Disposable, BooleanDisposable

Provides a mechanism for releasing unmanaged resources.

import 'package:disposable/disposable.dart';

main() {
  final disposable = new Disposable.create(() {
    print('disposed');
  });
  disposable.dispose();
  // => disposed
}

CompositeDisposable

Represents a group of disposable resources that are disposed together.

import 'package:disposable/disposable.dart';

main() {
  final d1 = new Disposable.create(() {
    print('one');
  });

  final d2 = new Disposable.create(() {
    print('two');
  });

  final disposables = new CompositeDisposable.from([d1, d2]);

  disposables.dispose();
  // => one
  // => two
}

MultiAssignmentDisposable

Represents a disposable whose underlying disposable can be swapped for another disposable.

import 'package:disposable/disposable.dart';

main() {
  final multiDisposable = new MultiAssignmentDisposable();

  final d1 = new Disposable.create(() {
    print('one');
  });

  multiDisposable.disposable = d1;

  final d2 = new Disposable.create(() {
    print('two');
  });

  multiDisposable.disposable = d2;

  d2.dispose();
  // => two

  print(d1.isDisposed);
  // => false

  print(d2.isDisposed);
  // => true
}

RefCountDisposable

Represents a disposable resource that only disposes its underlying disposable resource when all getDisposable dependent disposable objects have been disposed.

import 'package:disposable/disposable.dart';

main() {
  final disposable = new Disposable.create(() {
    print('disposed');
  });
  final refCountDisposable = new RefCountDisposable(disposable);

  final disposable1 = refCountDisposable.getDisposable();
  final disposable2 = refCountDisposable.getDisposable();

  disposable1.dispose();
  print(disposable.isDisposed);
  // => false

  disposable2.dispose();
  print(disposable.isDisposed);
  // => false

  print(refCountDisposable.isDisposed);
  // => false

  refCountDisposable.dispose();
  // => disposed

  print(refCountDisposable.isDisposed);
  // => true
}

SerialDisposable

Represents a disposable resource whose underlying disposable resource can be replaced by another disposable resource, causing automatic disposal of the previous underlying/ disposable resource.

import 'package:disposable/disposable.dart';

main() {
  final serialDisposable = new SerialDisposable();

  final d1 = new Disposable.create(() {
    print('one');
  });

  serialDisposable.disposable = d1;

  final d2 = new Disposable.create(() {
    print('two');
  });

  serialDisposable.disposable = d2;
  // => one

  serialDisposable.dispose();
  // => two
}

SingleAssignmentDisposable

Represents a disposable resource which only allows a single assignment of its underlying disposable resource. If an underlying disposable resource has already been set, future attempts to set the underlying disposable resource will throw an StateError.

import 'package:disposable/disposable.dart';

main() {
  final singleDisposable = new SingleAssignmentDisposable();

  final d1 = new Disposable.create(() {
    print('one');
  });

  singleDisposable.disposable = d1;

  final d2 = new Disposable.create(() {
    print('two');
  });

  try {
    singleDisposable.disposable = d2;
  } on StateError catch (e) {
    print(e.message);
    // => Disposable has already been assigned
  }
}

Collection Classes

DisposableList

Provides a container that automatically disposes its elements when removed.

import 'package:disposable/collection.dart';
import 'package:disposable/disposable.dart';

class MyResource implements Disposable {
  bool _isDisposed = false;

  @override
  bool get isDisposed => _isDisposed;

  @override
  void dispose() {
    _isDisposed = true;
  }
}

main() {
  final r0 = new MyResource();
  final r1 = new MyResource();
  final r2 = new MyResource();
  final r3 = new MyResource();
  final list = new DisposableList<MyResource>()..addAll([r0, r1, r2]);

  list[0] = r3;
  print(r0.isDisposed);
  // => true

  list.dispose();
  print(r1.isDisposed);
  // => true
  print(r2.isDisposed);
  // => true
  print(r3.isDisposed);
  // => true
}

Utility Functions

using

Provides a method of encapsulating a series of actions which ensure proper disposal of the disposable instance prior to exiting.

using(new MyThing(), (myThing) {
	... do stuff with myThing
});

Libraries

disposable
disposable.async
disposable.collection