suspend method

Future<Null> suspend()

Public method to suspend the module.

Suspend indicates to the module that it should go into a low-activity state. For example, by disconnecting from backend services and unloading heavy data structures.

Initiates the suspend process when the module is in the loaded state. If the module is in the suspended or suspending state a warning is logged and the method is a noop. If the module is in any other state, a StateError is thrown.

The Future values of all children suspend calls will be awaited. The first child to return an error value will emit the error on the didSuspend lifecycle stream. The returned Future will also resolve with this exception.

If an Exception is thrown during the call to onSuspend it will be emitted on the didSuspend lifecycle stream. The returned Future will also resolve with this exception.

If an error or exception is thrown during the call to the parent onSuspend lifecycle method it will be emitted on the didSuspend lifecycle stream. The error will also be returned by suspend.

Implementation

Future<Null> suspend() {
  if (isOrWillBeDisposed) {
    return _buildDisposedOrDisposingResponse(methodName: 'suspend');
  }

  if (isSuspended || isSuspending) {
    return _buildNoopResponse(
        isTransitioning: isSuspending,
        methodName: 'suspend',
        currentState: isSuspending
            ? LifecycleState.suspending
            : LifecycleState.suspended);
  }

  if (!(isLoaded || isLoading || isResuming)) {
    return _buildIllegalTransitionResponse(
        targetState: LifecycleState.suspended,
        allowedStates: [
          LifecycleState.loaded,
          LifecycleState.loading,
          LifecycleState.resuming
        ]);
  }

  Future<Null>? pendingTransition;
  if (_transition != null && !_transition!.isCompleted) {
    pendingTransition = _transition!.future.then((_) {
      _activeSpan = _startTransitionSpan('suspend');
    });
  } else {
    _activeSpan = _startTransitionSpan('suspend');
  }

  final transition = Completer<Null>();
  _transition = transition;
  _state = LifecycleState.suspending;

  _suspend(pendingTransition)
      .then(transition.complete)
      .catchError((error, trace) {
    transition.completeError(error, trace);
    _activeSpan?.setTag('error', true);
  }).whenComplete(() {
    _activeSpan?.finish();
    _activeSpan = null;
  });

  return transition.future;
}