description

# runZoned<R> function

R runZoned<R>(

1. R body(), {
2. Map<Object?, Object?>? zoneValues,
3. ZoneSpecification? zoneSpecification,
4. @Deprecated("Use runZonedGuarded instead") Function? onError,

})

Runs `body` in its own zone.

Creates a new zone using Zone.fork based on `zoneSpecification` and `zoneValues`, then runs `body` in that zone and returns the result.

Example use:

    var secret = "arglebargle"; // Or a random generated string.
    var result = runZoned(
        () async {
          await Future.delayed(Duration(seconds: 5), () {
            print("${Zone.current[#_secret]} glop glyf");
          });
        },
        zoneValues: {#_secret: secret},
        zoneSpecification:
            ZoneSpecification(print: (Zone self, parent, zone, String value) {
          if (value.contains(Zone.current[#_secret] as String)) {
            value = "--censored--";
          }
          parent.print(zone, value);
        }));
    secret = ""; // Erase the evidence.
    await result; // Wait for asynchronous computation to complete.

The new zone intercepts `print` and stores a value under the private symbol `#_secret`. The secret is available from the new Zone object, which is the Zone.current for the body, and is also the first, `self`, parameter to the `print` handler function.

If the ZoneSpecification.handleUncaughtError is set, or the deprecated `onError` callback is passed, the created zone will be an error zone. Asynchronous errors in futures never cross zone boundaries between zones with a different Zone.errorZone. A consequence of that behavior can be that a Future which completes as an error in the created zone will seem to never complete when used from a zone that belongs to a different error zone. Multiple attempts to use the future in a zone where the error is inaccessible will cause the error to be reported again in it's original error zone.

See runZonedGuarded in place of using the deprected `onError` argument. If `onError` is provided this function also tries to catch and handle synchronous errors from `body`, but may throw an error anyway returning `null` if the generic argument `R` is not nullable.

## Implementation

    R runZoned<R>(
      R body(), {
      Map<Object?, Object?>? zoneValues,
      ZoneSpecification? zoneSpecification,
      @Deprecated("Use runZonedGuarded instead") Function? onError,
    }) {
      if (onError != null) {
        // TODO: Remove this when code have been migrated off using [onError].
        if (onError is! void Function(Object, StackTrace)) {
          if (onError is void Function(Object)) {
            var originalOnError = onError;
            onError = (Object error, StackTrace stack) => originalOnError(error);
          } else {
            throw ArgumentError.value(
              onError,
              "onError",
              "Must be Function(Object) or Function(Object, StackTrace)",
            );
          }
        }
        return runZonedGuarded(
              body,
              onError,
              zoneSpecification: zoneSpecification,
              zoneValues: zoneValues,
            )
            as R;
      }
      return _runZoned<R>(body, zoneValues, zoneSpecification);
    }