capture<T> static method
If when is true, runs callback in a Zone in which the current
stack chain is tracked and automatically associated with (most) errors.
If when is false, this does not track stack chains. Instead, it's
identical to runZoned, except that it wraps any errors in
Chain.forTrace—which will only wrap the trace unless there's a different
Chain.capture active. This makes it easy for the caller to only capture
stack chains in debug mode or during development.
If onError is passed, any error in the zone that would otherwise go
unhandled is passed to it, along with the Chain associated with that
error. Note that if callback produces multiple unhandled errors,
onError may be called more than once. If onError isn't passed, the
parent Zone's unhandledErrorHandler will be called with the error and
its chain.
The zone this creates will be an error zone if either onError is
not null and when is false,
or if both when and errorZone are true.
If errorZone is false, onError must be null.
If callback returns a value, it will be returned by capture as well.
zoneValues is added to the runZoned calls.
Implementation
static T capture<T>(T Function() callback,
{void Function(Object error, Chain)? onError,
bool when = true,
bool errorZone = true,
Map<Object?, Object?>? zoneValues}) {
if (!errorZone && onError != null) {
throw ArgumentError.value(
onError, 'onError', 'must be null if errorZone is false');
}
if (!when) {
if (onError == null) return runZoned(callback, zoneValues: zoneValues);
return runZonedGuarded(callback, (error, stackTrace) {
onError(error, Chain.forTrace(stackTrace));
}, zoneValues: zoneValues) as T;
}
var spec = StackZoneSpecification(onError, errorZone: errorZone);
return runZoned(() {
try {
return callback();
} on Object catch (error, stackTrace) {
// Forward synchronous errors through the async error path to match the
// behavior of `runZonedGuarded`.
Zone.current.handleUncaughtError(error, stackTrace);
// If the expected return type of capture() is not nullable, this will
// throw a cast exception. But the only other alternative is to throw
// some other exception. Casting null to T at least lets existing uses
// where T is a nullable type continue to work.
return null as T;
}
}, zoneSpecification: spec.toSpec(), zoneValues: {
...?zoneValues,
_specKey: spec,
StackZoneSpecification.disableKey: false
});
}