ctmanager

Description:

ctmanager

A helper capable of managing multiple cancellation tokens with ease. Useful for operations like http requests, image processing, etc, that can be cancelled by user.
Note #
This package does not actually cancel executed operations, it just prevents hanging await processes when cancelled. In case of http requests or image processing, you might need to add extra mechanisms in the event of cancellation.
Usage #
CTManager can be used either as a singleton or as a new instance. Let's take a look at this example.
with singleton #
final newCancelToken = CTManager.I.create(
token: 'ct1',
operation: Future.delayed(
const Duration(seconds: 5),
() => 'done',
),
// optional
onCancel: () => print('cancelled'),
);
...
copied to clipboard
without singleton #
final ctManager = CTManager();
final newCancelToken = ctManager.create(
token: 'ct1',
operation: Future.delayed(
const Duration(seconds: 5),
() => 'done',
),
// optional
onCancel: () => print('cancelled'),
);
...
copied to clipboard
note: the token field can be anything except null.
Here both result have a new instance of CancellationToken<String, String?> since the token is a String and the return value of operation will be a String.
You might be wondering why it's CancellationToken<String, String?> and not CancellationToken<String, String>. Let's take a look at the following.
example 1 #
...
// the operation will be cancelled after 3 seconds.
Future.delayed(
const Duration(seconds: 3),
newCancelToken.cancel,
);

final result = await newCancelToken.result;

// since the operation will never return `null`,
// we just need to check if it's `null` or not.
// if it is then it was cancelled.
if(result == null) {
print('operation was cancelled after 3 seconds');
}else{
print('operation succeeded');
}
copied to clipboard
However if the operation can also return null, then you have to check whether it's completed or not.
example 2 #
final nullableValueCancelToken = CTManager.I.create(
token: 'ct1',
operation: Future.delayed(
const Duration(seconds: 5),
() => 1 < 2 ? null : 'done',
),
);
// the operation will be cancelled after 3 seconds.
Future.delayed(
const Duration(seconds: 3),
nullableValueCancelToken.cancel,
);

final result = await nullableValueCancelToken.result;
copied to clipboard
Here we have to check isCompleted first, before checking the value.

if(nullableValueCancelToken.isCompleted) {
if(result == null) {
print('operation suceeded with null value');
}else{
print('operation succeeded with a value');
}
}else{
print('operation was cancelled after 3 seconds.');
}
copied to clipboard
Now you might say CancelabeOperation from async can also do all these things in a more simple way. That's correct since this package uses it, but CTManager is able find those CancellationTokens via
final findToken = CTManager.I.of<String, String?>('ct1');
// note: before checking the token,
// make sure to check [findToken] is null or not.
// if it is then the token you're finding can be
// either had ben cancelled, had completed, or never created.
copied to clipboard
but if you just want to check if a CancellationToken still exists or not
final bool isStillRuning = CTManager.I.hasTokenOf('ct1');
// or
// final bool isNotRunning = CTManager.I.noTokenOf('ct1');
copied to clipboard
and to cancel it
CTManager.I.cancel('ct1');
copied to clipboard
Regarding example 1, if you already know that the operation will never return null, instead of creating it, you can directly run it.
final result = await CTManager.I.run(
token: 'ct1',
operation: Future.delayed(
const Duration(seconds: 5),
() => print('done'),
),
);
// and to cancel it, just call
//
// CTManager.I.cancel('ct1');
//
// somewhere before the operation completes.
//
// here you might notice that the `print('done')`
// still gets executed even after getting cancelled, don't worry that's normal.
copied to clipboard