cancellation_token_hoc081098
Author: Petrus Nguyễn Thái Học
Dart Cancellation Token. Inspired by CancellationToken in C#. A Dart utility package for easy async task cancellation.
Features
- Reuse a single
CancellationTokenfor multiple tasks, and cancel all of them with a single call toCancellationToken.cancel(). - Cancel futures and clean-up resources with
token.guardFuture(block). - Cancel streams and clean-up resources with
token.guardStream(stream)/Stream.guardedBy(token). - Integration with
rxdart/rxdart_extwithuseCancellationToken. - Very simple, lightweight, and easy to use.
Getting started
1. Add dependency
dependencies:
cancellation_token_hoc081098:
2. Import
import 'package:cancellation_token_hoc081098/cancellation_token_hoc081098.dart';
Usage
1. guardFuture
void main() async {
// Create a CancellationToken
final token = CancellationToken();
// Simulate a long-running task
Future<void> doWork(int number) async {
print('doWork($number) started');
await Future<void>.delayed(const Duration(milliseconds: 100));
print('doWork($number) finished');
}
// Guard a Future
final future = token.guardFuture(() async {
for (var i = 0; i < 10; i++) {
token.guard(); // Throws if token is cancelled
await doWork(i);
token.guard(); // Throws if token is cancelled
}
return 42;
});
future
.then((v) => print('Result: $v'))
.onError<Object>((e, st) => print('Error: $e'));
// Cancel the token after 300ms
await Future<void>.delayed(const Duration(milliseconds: 300));
// Cancel the token
token.cancel();
// Wait a little longer to ensure that the Future is cancelled
await Future<void>.delayed(const Duration(seconds: 2));
// Output:
// doWork(0) started
// doWork(0) finished
// doWork(1) started
// doWork(1) finished
// doWork(2) started
// Error: CancellationException
// doWork(2) finished
}
2. guardStream
void main() async {
// Create a CancellationToken
final token = CancellationToken();
// Simulate a long-running task
Future<void> doWork(int number) async {
print('doWork($number) started');
await Future<void>.delayed(const Duration(milliseconds: 100));
print('doWork($number) finished');
}
// Guard a Stream
final stream = Rx.fromCallable(() async {
for (var i = 0; i < 10; i++) {
token.guard(); // Throws if token is cancelled
await doWork(i);
token.guard(); // Throws if token is cancelled
}
return 42;
}).guardedBy(token);
stream
.doOnData((v) => print('Result: $v'))
.doOnError((e, st) => print('Error: $e'))
.listen(null);
// Cancel the token after 300ms
await Future<void>.delayed(const Duration(milliseconds: 300));
// Cancel the token
token.cancel();
// Wait a little longer to ensure that the stream is cancelled
await Future<void>.delayed(const Duration(seconds: 2));
// Output:
// doWork(0) started
// doWork(0) finished
// doWork(1) started
// doWork(1) finished
// doWork(2) started
// Error: CancellationException
// doWork(2) finished
}
3. useCancellationToken
import 'package:rxdart_ext/rxdart_ext.dart';
void main() async {
// Simulate a long-running task
Future<void> doWork(int number) async {
print('doWork($number) started');
await Future<void>.delayed(const Duration(milliseconds: 100));
print('doWork($number) finished');
}
// useCancellationToken
final Single<int> single = useCancellationToken((cancelToken) async {
for (var i = 0; i < 10; i++) {
cancelToken.guard(); // Throws if token is cancelled
await doWork(i);
cancelToken.guard(); // Throws if token is cancelled
}
return 42;
});
final subscription = single
.doOnData((v) => print('Result: $v'))
.doOnError((e, st) => print('Error: $e'))
.listen(null);
// Cancel the subscription after 300ms
await Future<void>.delayed(const Duration(milliseconds: 300));
// Cancel the subscription
await subscription.cancel();
// Wait a little longer to ensure that the stream is cancelled
await Future<void>.delayed(const Duration(seconds: 2));
// Output:
// doWork(0) started
// doWork(0) finished
// doWork(1) started
// doWork(1) finished
// doWork(2) started
// doWork(2) finished
}
Features and bugs
Please file feature requests and bugs at the issue tracker.
License
MIT License
Copyright (c) 2022 Petrus Nguyễn Thái Học
59 Dec 24, 2022
46 Dec 19, 2021
11.2k Jan 3, 2023
1 May 10, 2022
21 Dec 22, 2022
1 May 9, 2022
0 May 10, 2022
0 Sep 22, 2022
4 Nov 15, 2022
258 Nov 22, 2022