https://github.com/hoc081098/cancellation_token_hoc081098
Dart Cancellation Token. Inspired by CancellationToken in C#. A Dart utility package for easy async task cancellation.
https://github.com/hoc081098/cancellation_token_hoc081098
Last synced: 8 months ago
JSON representation
Dart Cancellation Token. Inspired by CancellationToken in C#. A Dart utility package for easy async task cancellation.
- Host: GitHub
- URL: https://github.com/hoc081098/cancellation_token_hoc081098
- Owner: hoc081098
- License: mit
- Created: 2022-09-03T12:38:42.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2025-02-27T00:37:00.000Z (9 months ago)
- Last Synced: 2025-03-27T16:51:14.336Z (8 months ago)
- Language: Dart
- Homepage: https://pub.dev/packages/cancellation_token_hoc081098
- Size: 48.8 KB
- Stars: 6
- Watchers: 2
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# cancellation_token_hoc081098
## Author: [Petrus Nguyễn Thái Học](https://github.com/hoc081098)
[](https://github.com/hoc081098/cancellation_token_hoc081098/actions/workflows/dart.yml)
[](https://pub.dev/packages/cancellation_token_hoc081098)
[](https://pub.dev/packages/cancellation_token_hoc081098)
[](https://codecov.io/gh/hoc081098/cancellation_token_hoc081098)
[](https://opensource.org/licenses/MIT)
[](https://pub.dev/packages/lints)
[](https://hits.seeyoufarm.com)
Dart Cancellation Token.
Inspired by CancellationToken in C#.
A Dart utility package for easy async task cancellation.
## Features
- [x] **Reuse** a single `CancellationToken` for multiple tasks, and **cancel all** of them with a single call to `CancellationToken.cancel()`.
- [x] **Cancel futures** and clean-up resources with `token.guardFuture(block)`.
- [x] **Cancel streams** and clean-up resources with `token.guardStream(stream)`/`Stream.guardedBy(token)`.
- [x] Integrate with **[rxdart](https://pub.dev/packages/rxdart)/[rxdart_ext](https://pub.dev/packages/rxdart_ext)** with `useCancellationToken`.
- [x] Very **simple**, **lightweight**, **performant**, and **easy** to use.
## Getting started
### 1. Add dependency
```yaml
dependencies:
cancellation_token_hoc081098:
```
### 2. Import
```dart
import 'package:cancellation_token_hoc081098/cancellation_token_hoc081098.dart';
```
## Usage
### 1. `guardFuture`
```dart
void main() async {
// Create a CancellationToken
final token = CancellationToken();
// Simulate a long-running task
Future doWork(int number) async {
print('doWork($number) started');
await Future.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((e, st) => print('Error: $e'));
// Cancel the token after 300ms
await Future.delayed(const Duration(milliseconds: 300));
// Cancel the token
token.cancel();
// Wait a little longer to ensure that the Future is cancelled
await Future.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`
```dart
void main() async {
// Create a CancellationToken
final token = CancellationToken();
// Simulate a long-running task
Future doWork(int number) async {
print('doWork($number) started');
await Future.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.delayed(const Duration(milliseconds: 300));
// Cancel the token
token.cancel();
// Wait a little longer to ensure that the stream is cancelled
await Future.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`
```dart
import 'package:rxdart_ext/rxdart_ext.dart';
void main() async {
// Simulate a long-running task
Future doWork(int number) async {
print('doWork($number) started');
await Future.delayed(const Duration(milliseconds: 100));
print('doWork($number) finished');
}
// useCancellationToken
final Single 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.delayed(const Duration(milliseconds: 300));
// Cancel the subscription
await subscription.cancel();
// Wait a little longer to ensure that the stream is cancelled
await Future.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](https://github.com/hoc081098/cancellation_token_hoc081098/issues).
## License
```
MIT License
Copyright (c) 2022 Petrus Nguyễn Thái Học
```