IO<A> sealed

sealed class IO<A> with Functor<A>, Applicative<A>, Monad<A>

IO is a datatype that can be used to control side-effects within synchronous and asynchronous code.

Mixed-in types

• Functor<A>
• Applicative<A>
• Monad<A>

Available Extensions

• IOBoolOps
• IOExceptionOps<A>
• IONestedOps<A>
• IOTickedOps<A>
• IOTracingOps<A>
• IOTuple2Ops<T1, T2>
• IOTuple3Ops<T1, T2, T3>
• IOTuple4Ops<T1, T2, T3, T4>
• IOTuple5Ops<T1, T2, T3, T4, T5>
• IOUnitOps<A>
• RetryOps<A>

Properties

hashCode no setter inherited

int get hashCode

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Inherited from Object.

Implementation

external int get hashCode;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

external Type get runtimeType;

Extension Properties

ticked extension no setter

Ticker<A> get ticked

Creates a Ticker for this IO, starting it on a TestIORuntime.

Available on IO<A>, provided by the IOTickedOps<A> extension

Implementation

Ticker<A> get ticked => Ticker.ticked(this);

Methods

andWait()

IO<A> andWait(Duration duration)

Return an IO that will wait the specified duration after evaluating and then return the result.

Implementation

IO<A> andWait(Duration duration) => _andWait(duration).traced('andWait');

ap() override

IO<B> ap<B>(IO<B Function(A)> f)

Apply f to the value of this Applicative.

Implementation

@override
IO<B> ap<B>(IO<Function1<A, B>> f) => _flatMap((a) => f._map((f) => f(a)));

as()

IO<B> as<B>(B b)

Replaces the result of this IO with the given value.

Implementation

IO<B> as<B>(B b) => _as(b).traced('as');

attempt()

IO<Either<Object, A>> attempt()

Extracts any exceptions encountered during evaluation into an Either value.

Implementation

IO<Either<Object, A>> attempt() => _attempt().traced('attempt');

attemptTap()

IO<A> attemptTap<B>(IO<B> Function(Either<Object, A>) f)

Runs f with the Either result of this IO (success or error) as a side-effect, then re-raises any error so the error is not swallowed.

Implementation

IO<A> attemptTap<B>(Function1<Either<Object, A>, IO<B>> f) => _attemptTap(f).traced('attemptTap');

background()

Resource<IO<Outcome<A>>> background()

Creates a new Resource that will start the execution of this fiber and cancel the execution when the Resource is finalized.

Implementation

Resource<IO<Outcome<A>>> background() =>
    Resource.make(_start(), (fiber) => fiber.cancel()).map((f) => f.join());

bracket()

IO<B> bracket<B>(IO<B> Function(A) use, IO<Unit> Function(A) release)

Returns an IO that uses this IO as the resource acquisition, use as the IO action that action that uses the resource, and release as the finalizer that will clean up the resource.

Implementation

IO<B> bracket<B>(Function1<A, IO<B>> use, Function1<A, IO<Unit>> release) =>
    _bracket(use, release).traced('bracket');

bracketCase()

IO<B> bracketCase<B>(
  IO<B> Function(A) use,
  IO<Unit> Function(A, Outcome<B>) release,
)

Returns an IO that uses this IO as the resource acquisition, use as the IO action that action that uses the resource, and release as the finalizer that will clean up the resource. Both result of this IO and the Outcome of use are provided to release.

Implementation

IO<B> bracketCase<B>(
  Function1<A, IO<B>> use,
  Function2<A, Outcome<B>, IO<Unit>> release,
) => _bracketCase(use, release).traced('bracketCase');

cancelable()

IO<A> cancelable(IO<Unit> fin)

Starts this IO as a fiber and joins it, attaching fin as a finalizer that is run when the outer IO is canceled. This allows a background fiber to be canceled with a custom cleanup action rather than the default cooperative cancellation.

Implementation

IO<A> cancelable(IO<Unit> fin) => _cancelable(fin).traced('cancelable');

debug()

IO<A> debug({String prefix = 'DEBUG'})

Prints the result of this IO (value, error or canceled) to stdout

Implementation

IO<A> debug({String prefix = 'DEBUG'}) => _guaranteeCase(
  (outcome) => outcome.fold(
    () => _platformImpl.print('$prefix: Canceled'),
    (err, _) => _platformImpl.print('$prefix: Errored: $err'),
    (a) => _platformImpl.print('$prefix: Succeeded: $a'),
  ),
).traced('debug');

delayBy()

IO<A> delayBy(Duration duration)

Return an IO that will wait the specified duration before evaluating and then return the result.

Implementation

IO<A> delayBy(Duration duration) => _delayBy(duration).traced('delayBy');

flatMap() override

IO<B> flatMap<B>(IO<B> Function(A) f)

Sequences the evaluation of this IO and the provided function f that will create the next IO to be evaluated.

Implementation

@override
IO<B> flatMap<B>(Function1<A, IO<B>> f) => _flatMap(f).traced('flatMap');

flatTap()

IO<A> flatTap<B>(IO<B> Function(A) f)

Performs the side-effect encoded in f using the value created by this IO, then returning the original value.

Implementation

IO<A> flatTap<B>(Function1<A, IO<B>> f) => _flatTap(f).traced('flatTap');

foreverM()

IO<Never> foreverM()

Continually re-evaluate this IO forever, until an error or cancelation.

Implementation

IO<Never> foreverM() => _foreverM().traced('foreverM');

guarantee()

IO<A> guarantee(IO<Unit> fin)

Executes the provided finalizer fin regardless of the Outcome of evaluating this IO.

Implementation

IO<A> guarantee(IO<Unit> fin) => _guarantee(fin).traced('guarantee');

guaranteeCase()

IO<A> guaranteeCase(IO<Unit> Function(Outcome<A>) fin)

Executes the provided finalizer fin which can decide what action to take depending on the Outcome of this IO.

Implementation

IO<A> guaranteeCase(Function1<Outcome<A>, IO<Unit>> fin) =>
    _guaranteeCase(fin).traced('guaranteeCase');

handleError()

IO<A> handleError(A Function(Object) f)

Intercepts any upstream Exception, returning the value generated by f.

Implementation

IO<A> handleError(Function1<Object, A> f) => _handleError(f).traced('handleError');

handleErrorWith()

IO<A> handleErrorWith(IO<A> Function(Object) f)

Intercepts any upstream Exception, sequencing in the IO generated by f.

Implementation

IO<A> handleErrorWith(Function1<Object, IO<A>> f) =>
    _handleErrorWith(f).traced('handleErrorWith');

isolate()

IO<A> isolate({String? debugName})

Runs this IO in a separate Dart isolate, returning the result when the isolate finishes. The optional debugName is used to label the isolate.

Implementation

IO<A> isolate({String? debugName}) => _platformImpl.isolate(this, debugName: debugName);

iterateUntil()

IO<A> iterateUntil(bool Function(A) p)

Continually re-evaluates this IO until the computed value satisfies the given predicate p. The first computed value that satisfies p will be the final result.

Implementation

IO<A> iterateUntil(Function1<A, bool> p) => _iterateUntil(p).traced('iterateUntil');

iterateWhile()

IO<A> iterateWhile(bool Function(A) p)

Continually re-evaluates this IO while the computed value satisfies the given predicate p. The first computed value that does not satisfy p will be the final result.

Implementation

IO<A> iterateWhile(Function1<A, bool> p) => _iterateWhile(p).traced('iterateWhile');

iterateWhileM()

IO<A> iterateWhileM(IO<bool> Function(A) p)

Continually re-evaluates this IO while the effectful predicate p returns true. The first computed value for which p returns false will be the final result.

Implementation

IO<A> iterateWhileM(Function1<A, IO<bool>> p) => _iterateWhileM(p).traced('iterateWhileM');

map() override

IO<B> map<B>(B Function(A) f)

Applies f to the value of this IO, returning the result.

Implementation

@override
IO<B> map<B>(Function1<A, B> f) => _map(f).traced('map');

noSuchMethod() inherited

dynamic noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

Implementation

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

onCancel()

IO<A> onCancel(IO<Unit> fin)

Attaches a finalizer to this IO that will be evaluated if this IO is canceled.

Implementation

IO<A> onCancel(IO<Unit> fin) => _onCancel(fin).traced('onCancel');

onError()

IO<A> onError(IO<Unit> Function(Object) f)

Performs the given side-effect if this IO results in a error.

Implementation

IO<A> onError(Function1<Object, IO<Unit>> f) => _onError(f).traced('onError');

option()

IO<Option<A>> option()

Replaces any failures from this IO with None. A successful value is wrapped in Some.

Implementation

IO<Option<A>> option() => _option().traced('option');

orElse()

IO<A> orElse(IO<A> Function() that)

If the evaluation of this IO results in an error, run that as an attempt to recover.

Implementation

IO<A> orElse(Function0<IO<A>> that) => _orElse(that).traced('orElse');

parReplicate()

IO<IList<A>> parReplicate(int n)

Runs this IO n times, accumulating the result from each evaluation into an IList. All replications will be run asynchronously.

Implementation

IO<IList<A>> parReplicate(int n) => _parReplicate(n).traced('parReplicate');

parReplicate_()

IO<Unit> parReplicate_(int n)

Runs this IO n times, discarding any resulting values. All replications will be run asynchronously.

Implementation

IO<Unit> parReplicate_(int n) => _parReplicate_(n).traced('parReplicate_');

product()

IO<Record> product<B>(IO<B> that)

Sequentially evaluate this IO, then that, and return the product (i.e. tuple) of each value.

Implementation

IO<(A, B)> product<B>(IO<B> that) => _product(that).traced('product');

productL()

IO<A> productL<B>(IO<B> that)

Sequentially evaluate this IO, then that, returning the value producted by this, discarding that value from that.

Implementation

IO<A> productL<B>(IO<B> that) => _productL(that).traced('productL');

productR()

IO<B> productR<B>(IO<B> that)

Sequentially evaluate this IO, then that, returning the value producted by that, discarding the value from this.

Implementation

IO<B> productR<B>(IO<B> that) => _productR(that).traced('productR');

redeem()

IO<B> redeem<B>(B Function(Object) recover, B Function(A) map)

Returns the value created from recover or map, depending on whether this IO results in an error or is successful.

Implementation

IO<B> redeem<B>(Function1<Object, B> recover, Function1<A, B> map) =>
    _redeem(recover, map).traced('redeem');

redeemWith()

IO<B> redeemWith<B>(IO<B> Function(Object) recover, IO<B> Function(A) bind)

Returns the value created from recover or map, depending on whether this IO results in an error or is successful.

Implementation

IO<B> redeemWith<B>(
  Function1<Object, IO<B>> recover,
  Function1<A, IO<B>> bind,
) => _redeemWith(recover, bind).traced('redeemWith');

replicate()

IO<IList<A>> replicate(int n)

Runs this IO n times, accumulating the result from each evaluation into an IList.

Implementation

IO<IList<A>> replicate(int n) => _replicate(n).traced('replicate');

replicate_()

IO<Unit> replicate_(int n)

Runs this IO n times, discarding any resulting values.

Implementation

IO<Unit> replicate_(int n) => _replicate_(n).traced('replicate_');

start()

IO<IOFiber<A>> start()

Starts the execution of this IO, returning a handle to the running IO in the form of an IOFiber. The fiber can be used to wait for a result or cancel it's execution.

Implementation

IO<IOFiber<A>> start() => _start().traced('start');

timed()

IO<Record> timed()

Times how long this IO takes to evaluate, and returns the Duration and the value as a tuple.

Implementation

IO<(Duration, A)> timed() => _timed().traced('timed');

timeout()

IO<A> timeout(Duration duration)

Creates an IO that returns the value of this IO, or raises an error if the evaluation take longer than duration.

Implementation

IO<A> timeout(Duration duration) => _timeout(duration).traced('timeout');

timeoutAndForget()

IO<A> timeoutAndForget(Duration duration)

Like timeout, but does not cancel the original IO when the deadline is exceeded — the original fiber is left running in the background. Raises a TimeoutException if duration elapses before this IO completes.

Implementation

IO<A> timeoutAndForget(Duration duration) =>
    _timeoutAndForget(duration).traced('timeoutAndForget');

timeoutTo()

IO<A> timeoutTo(Duration duration, IO<A> fallback)

Creates an IO that will return the value of this IO, or the value of fallback if the evaluation of this IO exceeds duration.

Implementation

IO<A> timeoutTo(Duration duration, IO<A> fallback) =>
    _timeoutTo(duration, fallback).traced('timeoutTo');

toResource()

Resource<A> toResource()

Lifts this IO to a Resource

Implementation

Resource<A> toResource() => Resource.eval(this);

toString() inherited

String toString()

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.

Inherited from Object.

Implementation

external String toString();

tupleLeft()

IO<Record> tupleLeft<B>(B b)

Creates an IO that will return the value of this IO tupled with b, with b taking the first element of the tuple.

Implementation

IO<(B, A)> tupleLeft<B>(B b) => _tupleLeft(b).traced('tupleLeft');

tupleRight()

IO<Record> tupleRight<B>(B b)

Creates an IO that will return the value of this IO tupled with b, with b taking the second element of the tuple.

Implementation

IO<(A, B)> tupleRight<B>(B b) => _tupleRight(b).traced('tupleRight');

unsafeRunAndForget()

void unsafeRunAndForget({IORuntime? runtime})

Starts the evaluation of this IO and discards any results.

Implementation

void unsafeRunAndForget({
  IORuntime? runtime,
}) => _unsafeRunFiber(() {}, (_, _) {}, (_) {}, runtime: runtime);

unsafeRunAsync()

void unsafeRunAsync(void Function(Outcome<A>) cb, {IORuntime? runtime})

Starts the evaluation this IO and invokes the given callback cb with the Outcome.

Implementation

void unsafeRunAsync(
  Function1<Outcome<A>, void> cb, {
  IORuntime? runtime,
}) {
  _unsafeRunFiber(
    () => cb(Canceled()),
    (err, stackTrace) => cb(Errored(err, stackTrace)),
    (a) => cb(Succeeded(a)),
    runtime: runtime,
  );
}

unsafeRunCancelable()

Future<Unit> Function() unsafeRunCancelable({IORuntime? runtime})

Starts the evaluation of this IO and returns a function that can be called to cancel the evaluation. If the evaluation has already finished, the cancelation function is a no-op.

Implementation

Function0<Future<Unit>> unsafeRunCancelable({
  IORuntime? runtime,
}) => unsafeRunFutureCancelable(runtime: runtime).$2;

unsafeRunFuture()

Future<A> unsafeRunFuture({IORuntime? runtime})

Starts the evaluation of this IO and returns a Future that will complete with the Outcome of the evaluation. The Future may complete with an error if the evaluation of the IO encounters and error or is canceled.

Implementation

Future<A> unsafeRunFuture({
  IORuntime? runtime,
}) => unsafeRunFutureCancelable(runtime: runtime).$1;

unsafeRunFutureCancelable()

Record unsafeRunFutureCancelable({IORuntime? runtime})

Starts the evaluation of this IO and returns a Future that will complete with the Outcome of the evaluation as well as a function that can be called to cancel the future. The Future will not complete with an error, since the value itself is capable of conveying an error was encountered. If the evaluation has already finished, the cancelation function is a no-op.

Implementation

(Future<A>, Function0<Future<Unit>>) unsafeRunFutureCancelable({
  IORuntime? runtime,
}) {
  final completer = Completer<A>();

  final fiber = _unsafeRunFiber(
    () => completer.completeError('Fiber canceled'),
    (err, stackTrace) => completer.completeError(err, stackTrace),
    (a) => completer.complete(a),
    runtime: runtime,
  );

  return (completer.future, () => fiber.cancel().unsafeRunFuture());
}

unsafeRunFutureOutcome()

Future<Outcome<A>> unsafeRunFutureOutcome({IORuntime? runtime})

Evaluates this IO and returns a Future that will complete with the Outcome of the evaluation. The Future will not complete with an error, since the value itself is capable of conveying an error was encountered.

Implementation

Future<Outcome<A>> unsafeRunFutureOutcome({
  IORuntime? runtime,
}) {
  final completer = Completer<Outcome<A>>();
  unsafeRunAsync(completer.complete, runtime: runtime);
  return completer.future;
}

untilM()

IO<IList<A>> untilM(IO<bool> cond)

Evaluates this IO repeatedly until evaluating cond results is true. Results from every evaluation is accumulated in the returned IList.

Note that cond is evaluated after evaluating this IO for each repetition.

Implementation

IO<IList<A>> untilM(IO<bool> cond) => _untilM(cond).traced('untilM');

untilM_()

IO<Unit> untilM_(IO<bool> cond)

Evaluates this IO repeatedly until evaluating cond results is true. Results are discarded.

Note that cond is evaluated after evaluating this IO for each repetition.

Implementation

IO<Unit> untilM_(IO<bool> cond) => _untilM_(cond).traced('untilM_');

voided()

IO<Unit> voided()

Discards the value of this IO and replaces it with Unit.

Implementation

IO<Unit> voided() => _voided();

whenA()

IO<Unit> whenA(bool cond)

Evaluates this IO and discards the result when cond is true, otherwise returns IO.unit without evaluating this IO.

Implementation

IO<Unit> whenA(bool cond) => _whenA(cond).traced('whenA');

whilelM()

IO<IList<A>> whilelM(IO<bool> cond)

Evaluates this IO repeatedly until evaluating cond results is false. Results from every evaluation is accumulated in the returned IList.

Note that cond is evaluated before evaluating this IO for each repitition.

Implementation

IO<IList<A>> whilelM(IO<bool> cond) => _whilelM(cond).traced('whileM');

whileM_()

IO<Unit> whileM_(IO<bool> cond)

Evaluates this IO repeatedly until evaluating cond results is false. Results are discarded.

Note that cond is evaluated before evaluating this IO for each repitition.

Implementation

IO<Unit> whileM_(IO<bool> cond) => _whileM_(cond).traced('whileM_');

Extension Methods

flatMapN() extension

IO<T3> flatMapN<T3>(IO<T3> Function(T1, T2) f)

Available on IO<A>, provided by the IOTuple2Ops<T1, T2> extension

Implementation

IO<T3> flatMapN<T3>(Function2<T1, T2, IO<T3>> f) => flatMap(f.tupled);

flatMapN() extension

IO<T6> flatMapN<T6>(IO<T6> Function(T1, T2, T3, T4, T5) f)

Available on IO<A>, provided by the IOTuple5Ops<T1, T2, T3, T4, T5> extension

Implementation

IO<T6> flatMapN<T6>(Function5<T1, T2, T3, T4, T5, IO<T6>> f) => flatMap(f.tupled);

flatMapN() extension

IO<T5> flatMapN<T5>(IO<T5> Function(T1, T2, T3, T4) f)

Available on IO<A>, provided by the IOTuple4Ops<T1, T2, T3, T4> extension

Implementation

IO<T5> flatMapN<T5>(Function4<T1, T2, T3, T4, IO<T5>> f) => flatMap(f.tupled);

flatMapN() extension

IO<T4> flatMapN<T4>(IO<T4> Function(T1, T2, T3) f)

Available on IO<A>, provided by the IOTuple3Ops<T1, T2, T3> extension

Implementation

IO<T4> flatMapN<T4>(Function3<T1, T2, T3, IO<T4>> f) => flatMap(f.tupled);

flatTapN() extension

IO<Record> flatTapN<T3>(IO<T3> Function(T1, T2) f)

Available on IO<A>, provided by the IOTuple2Ops<T1, T2> extension

Implementation

IO<(T1, T2)> flatTapN<T3>(Function2<T1, T2, IO<T3>> f) => flatTap(f.tupled);

flatTapN() extension

IO<Record> flatTapN<T4>(IO<T4> Function(T1, T2, T3) f)

Available on IO<A>, provided by the IOTuple3Ops<T1, T2, T3> extension

Implementation

IO<(T1, T2, T3)> flatTapN<T4>(Function3<T1, T2, T3, IO<T4>> f) => flatTap(f.tupled);

flatTapN() extension

IO<Record> flatTapN<T6>(IO<T6> Function(T1, T2, T3, T4, T5) f)

Available on IO<A>, provided by the IOTuple5Ops<T1, T2, T3, T4, T5> extension

Implementation

IO<(T1, T2, T3, T4, T5)> flatTapN<T6>(Function5<T1, T2, T3, T4, T5, IO<T6>> f) =>
    flatTap(f.tupled);

flatTapN() extension

IO<Record> flatTapN<T5>(IO<T5> Function(T1, T2, T3, T4) f)

Available on IO<A>, provided by the IOTuple4Ops<T1, T2, T3, T4> extension

Implementation

IO<(T1, T2, T3, T4)> flatTapN<T5>(Function4<T1, T2, T3, T4, IO<T5>> f) => flatTap(f.tupled);

flatten() extension

IO<A> flatten()

Returns an IO that will complete with the value of the inner IO.

Available on IO<A>, provided by the IONestedOps<A> extension

Implementation

IO<A> flatten() => _flatten().traced('flatten');

ifM() extension

IO<B> ifM<B>(IO<B> Function() ifTrue, IO<B> Function() ifFalse)

Evaluates this IO to a boolean. If true, evaluating ifTrue. Otherwise evaluates ifFalse.

Available on IO<A>, provided by the IOBoolOps extension

Implementation

IO<B> ifM<B>(Function0<IO<B>> ifTrue, Function0<IO<B>> ifFalse) =>
    _ifM(ifTrue, ifFalse).traced('ifM');

mapN() extension

IO<T3> mapN<T3>(T3 Function(T1, T2) f)

Available on IO<A>, provided by the IOTuple2Ops<T1, T2> extension

Implementation

IO<T3> mapN<T3>(Function2<T1, T2, T3> f) => map(f.tupled);

mapN() extension

IO<T5> mapN<T5>(T5 Function(T1, T2, T3, T4) f)

Available on IO<A>, provided by the IOTuple4Ops<T1, T2, T3, T4> extension

Implementation

IO<T5> mapN<T5>(Function4<T1, T2, T3, T4, T5> f) => map(f.tupled);

mapN() extension

IO<T4> mapN<T4>(T4 Function(T1, T2, T3) f)

Available on IO<A>, provided by the IOTuple3Ops<T1, T2, T3> extension

Implementation

IO<T4> mapN<T4>(Function3<T1, T2, T3, T4> f) => map(f.tupled);

mapN() extension

IO<T6> mapN<T6>(T6 Function(T1, T2, T3, T4, T5) f)

Available on IO<A>, provided by the IOTuple5Ops<T1, T2, T3, T4, T5> extension

Implementation

IO<T6> mapN<T6>(Function5<T1, T2, T3, T4, T5, T6> f) => map(f.tupled);

rethrowError() extension

IO<A> rethrowError()

Inverse of IO.attempt.

Available on IO<A>, provided by the IOExceptionOps<A> extension

Implementation

IO<A> rethrowError() => _rethrowError().traced('rethrowError');

retrying() extension

IO<A> retrying(
  RetryPolicy policy, {
  (bool Function(A))? wasSuccessful,
  (bool Function(Object))? isWorthRetrying,
  (IO<Unit> Function(Object, RetryDetails))? onError,
  (IO<Unit> Function(A, RetryDetails))? onFailure,
})

Applies the given policy to this IO and will attempt to retry any failed attempts according to the policy.

wasSuccessful can be provided to further filter any successful evalations with undesirable results, so they may be retried.

isWorthRetrying can be provided to short-circuit any attempt to retry if some kind of error is encountered that may eliminate any need to retry.

onError can be provided to perform the given side-effect for each error eencounted.

onFailure can be provided in conjunction with wasSuccessful to perform the given side-effect when a successful evaluation fails to satisfy the wasSuccessful predicate.

Available on IO<A>, provided by the RetryOps<A> extension

Implementation

IO<A> retrying(
  RetryPolicy policy, {
  Function1<A, bool>? wasSuccessful,
  Function1<Object, bool>? isWorthRetrying,
  Function2<Object, RetryDetails, IO<Unit>>? onError,
  Function2<A, RetryDetails, IO<Unit>>? onFailure,
}) => _retryingImpl(
  policy,
  wasSuccessful ?? (_) => true,
  isWorthRetrying ?? (_) => true,
  onError ?? (_, _) => IO.unit,
  onFailure ?? (_, _) => IO.unit,
  RetryStatus.initial(),
  this,
);

traced() extension

IO<A> traced(String label, [int? depth])

Annotates this IO with a label for tracing purposes.

When IOTracingConfig.tracingEnabled is true, the label is recorded in the fiber's trace ring buffer. When tracing is disabled, this is a no-op that returns the original IO unchanged.

depth optionally limits how many frames of the captured StackTrace are stored.

Available on IO<A>, provided by the IOTracingOps<A> extension

Implementation

IO<A> traced(String label, [int? depth]) {
  if (!IOTracingConfig.tracingEnabled) {
    return this;
  } else {
    return _Traced(this, label, depth);
  }
}

voidError() extension

IO<Unit> voidError()

Ignores any errors that occur during evaluation, turning them into a successful Unit result.

Available on IO<A>, provided by the IOUnitOps<A> extension

Implementation

IO<Unit> voidError() => _voidError().traced('voidError');

Operators

operator ==() inherited

bool operator ==(Object other)

The equality operator.

The default behavior for all Objects is to return true if and only if this object and other are the same object.

Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:

• Total: It must return a boolean for all arguments. It should never throw.

• Reflexive: For all objects o, o == o must be true.

• Symmetric: For all objects o1 and o2, o1 == o2 and o2 == o1 must either both be true, or both be false.

• Transitive: For all objects o1, o2, and o3, if o1 == o2 and o2 == o3 are true, then o1 == o3 must be true.

The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.

If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.

Inherited from Object.

Implementation

external bool operator ==(Object other);

Static Properties

stub no setter

IO<Never> get stub

Alias for IO.delay(() => throw UnimplementedError())

Implementation

static IO<Never> get stub => _stub.traced('stub');

unit final

final IO<Unit> unit

Alias for IO.pure(Unit()).

Implementation

static final IO<Unit> unit = IO.pure(Unit());

Static Methods

async()

IO<A> async<A>(
  IO<Option<IO<Unit>>> Function(void Function(Either<Object, A>)) k,
)

Suspends the asynchronous effect k within IO. When evaluation is completed, the callback will be invoked with the result of the IO. If the newly created IO is canceled, the provided finalizer will be invoked.

Implementation

static IO<A> async<A>(AsyncBodyWithFin<A> k) => _async(k);

async_()

IO<A> async_<A>(void Function(void Function(Either<Object, A>)) k)

Suspends the asynchronous effect k within IO. When evaluation is completed, the callback will be invoked with the result of the IO.

Implementation

static IO<A> async_<A>(AsyncBody<A> k) => _async_(k).traced('async_');

both()

IO<Record> both<A, B>(IO<A> ioa, IO<B> iob)

Runs both ioa and iob together, returning a tuple of both results if both of them are successful. If either of them results in an error or is canceled, that error or cancelation is propogated.

Implementation

static IO<(A, B)> both<A, B>(IO<A> ioa, IO<B> iob) => _both(ioa, iob).traced('both');

bothOutcome()

IO<Record> bothOutcome<A, B>(IO<A> ioa, IO<B> iob)

Runs both ioa and iob, returning a tuple of the Outcome of each.

Implementation

static IO<(Outcome<A>, Outcome<B>)> bothOutcome<A, B>(IO<A> ioa, IO<B> iob) =>
    _bothOutcome(ioa, iob);

bracketFull()

IO<B> bracketFull<A, B>(
  IO<A> Function(Poll) acquire,
  IO<B> Function(A) use,
  IO<Unit> Function(A, Outcome<B>) release,
)

Creates an IO that will evaluate acquire, pass the result to use if successful and then guarantee the evaluation of release.

Implementation

static IO<B> bracketFull<A, B>(
  Function1<Poll, IO<A>> acquire,
  Function1<A, IO<B>> use,
  Function2<A, Outcome<B>, IO<Unit>> release,
) => _bracketFull(acquire, use, release).traced('bracketFull');

catchNonError()

IO<A> catchNonError<A>(A Function() f)

Evaluates f and lifts the result into IO.pure, or lifts any Exception thrown into IO.raiseError. Non-Exception errors (e.g. Error subclasses) are not caught and will propagate normally.

Implementation

static IO<A> catchNonError<A>(Function0<A> f) {
  try {
    return IO.pure(f());
  } on Exception catch (error, stackTrace) {
    return IO.raiseError(error, stackTrace);
  }
}

defer()

IO<A> defer<A>(IO<A> Function() thunk)

Suspends the synchronous evaluation of thunk in IO.

Implementation

static IO<A> defer<A>(Function0<IO<A>> thunk) => _defer(thunk).traced('defer');

deferred()

IO<Deferred<A>> deferred<A>()

Creates a new Deferred of the given generic type.

Implementation

static IO<Deferred<A>> deferred<A>() => Deferred.of<A>();

delay()

IO<A> delay<A>(A Function() thunk)

Suspends the synchronous evaluation of thunk in IO.

Implementation

static IO<A> delay<A>(Function0<A> thunk) => _delay(thunk).traced('delay');

exec()

IO<Unit> exec<A>(A Function() thunk)

Executes the given function, discarding any result.

Implementation

static IO<Unit> exec<A>(Function0<A> thunk) => _exec(thunk).traced('exec');

fromCancelableOperation()

IO<A> fromCancelableOperation<A>(IO<CancelableOperation<A>> op)

Creates an IO that returns the value or error of the underlying CancelableOperation. If new IO is canceled, the cancelation request will be forwarded to the underlying CancelableOperation.

Implementation

static IO<A> fromCancelableOperation<A>(IO<CancelableOperation<A>> op) {
  return op
      ._flatMap((op) {
        return IO._async<A>((cb) {
          return IO._delay(() {
            op.then(
              (a) => cb(a.asRight()),
              onError: (e, s) => cb(e.asLeft()),
            );

            return Some(IO._fromFutureF(() => op.cancel().then((_) => Unit())));
          });
        });
      })
      .traced('fromCancelableOperation');
}

fromEither()

IO<A> fromEither<A>(Either<Object, A> either)

Alias for IO.pure when either is Right, or IO.raiseError with either providing the error when either is Left.

Implementation

static IO<A> fromEither<A>(Either<Object, A> either) => _fromEither(either).traced('fromEither');

fromFuture()

IO<A> fromFuture<A>(IO<Future<A>> fut)

Create an IO that returns the value of the underlying Future or the error fut emits.

Implementation

static IO<A> fromFuture<A>(IO<Future<A>> fut) => _fromFuture(fut).traced('fromFuture');

fromFutureF()

IO<A> fromFutureF<A>(Future<A> Function() futF)

Create an IO that returns the value of the underlying Future function or the error futF emits.

Implementation

static IO<A> fromFutureF<A>(Function0<Future<A>> futF) =>
    _fromFutureF(futF).traced('fromFutureF');

fromOption()

IO<A> fromOption<A>(Option<A> option, Object Function() orElse)

Alias for IO.pure when option is Some, or IO.raiseError with orElse providing the error when option is None.

Implementation

static IO<A> fromOption<A>(Option<A> option, Function0<Object> orElse) =>
    _fromOption(option, orElse).traced('fromOption');

installFiberDumpSignalHandler()

void installFiberDumpSignalHandler()

Installs a platform-specific signal handler that dumps the state of all active fibers to stdout when triggered (e.g. on SIGINFO/SIGQUIT).

Implementation

static void installFiberDumpSignalHandler() => _platformImpl.installFiberDumpSignalHandler();

never()

IO<A> never<A>()

Returns a non-terminating IO, alias for async_((_) {}).

Implementation

static IO<A> never<A>() => _never<A>().traced('never');

none()

IO<Option<A>> none<A>()

Alias for IO.pure(const None()).

Implementation

static IO<Option<A>> none<A>() => _none<A>().traced('none');

print()

IO<Unit> print(String message)

Writes message with a newline to stdout, delaying the effect until evaluation.

Implementation

static IO<Unit> print(String message) => _platformImpl.print(message).traced('println');

pure()

IO<B> pure<A>(A a)

Lifts a pure value into IO.

Implementation

static IO<A> pure<A>(A a) => _Pure(a);

race()

IO<Either<A, B>> race<A, B>(IO<A> ioa, IO<B> iob)

Runs ioa and iob together, returning the first IO to finish after the loser is canceled.

Implementation

static IO<Either<A, B>> race<A, B>(IO<A> ioa, IO<B> iob) => _race(ioa, iob).traced('race');

raceOutcome()

IO<Either<Outcome<A>, Outcome<B>>> raceOutcome<A, B>(IO<A> ioa, IO<B> iob)

Runs ioa and iob together, returning the Outcome of the winner after canceling the loser.

Implementation

static IO<Either<Outcome<A>, Outcome<B>>> raceOutcome<A, B>(IO<A> ioa, IO<B> iob) =>
    _raceOutcome(ioa, iob);

racePair()

IO<Either<AWon<A, B>, BWon<A, B>>> racePair<A, B>(IO<A> ioa, IO<B> iob)

Runs ioa and iob together, returning a pair of the Outcome of the IO that finished first (won) and an IOFiber handle for the loser.

Implementation

static IO<Either<AWon<A, B>, BWon<A, B>>> racePair<A, B>(IO<A> ioa, IO<B> iob) =>
    _racePair(ioa, iob).traced('racePair');

raiseError()

IO<A> raiseError<A>(Object error, [StackTrace? st])

Create an IO that will inject the given error into the IO evaluation.

Implementation

static IO<A> raiseError<A>(Object error, [StackTrace? st]) =>
    _raiseError<A>(error, st).traced('raiseError');

raiseUnless()

IO<Unit> raiseUnless(bool cond, Object Function() e)

Returns an IO.raiseError when cond is false, otherwice IO.unit.

Implementation

static IO<Unit> raiseUnless(bool cond, Function0<Object> e) =>
    _raiseUnless(cond, e).traced('raiseUnless');

raiseWhen()

IO<Unit> raiseWhen(bool cond, Object Function() e)

Returns an IO.raiseError when cond is true, otherwice IO.unit.

Implementation

static IO<Unit> raiseWhen(bool cond, Function0<Object> e) =>
    _raiseWhen(cond, e).traced('raiseWhen');

readLine()

IO<String> readLine()

Reads a line from stdin. This is a blocking operation and will not finish until a full line of input is available from the console.

Implementation

static IO<String> readLine() => _platformImpl.readLine();

ref()

IO<Ref<A>> ref<A>(A a)

Creates a new Ref of the given generic type.

Implementation

static IO<Ref<A>> ref<A>(A a) => Ref.of(a);

sleep()

IO<Unit> sleep(Duration duration)

Creates an ansynchronous IO that will sleep for the given duration and resume when finished.

Implementation

static IO<Unit> sleep(Duration duration) => _sleep(duration).traced('sleep');

some()

IO<Option<A>> some<A>(A a)

Alias for IO.pure(Some(a)).

Implementation

static IO<Option<A>> some<A>(A a) => _some(a).traced('some');

uncancelable()

IO<A> uncancelable<A>(IO<A> Function(Poll) body)

Creates an uncancelable region within the IO run loop. The Poll provided can be used to create unmasked cancelable regions within the uncancelable region.

Implementation

static IO<A> uncancelable<A>(Function1<Poll, IO<A>> body) =>
    _uncancelable(body).traced('uncancelable');

unlessA()

IO<Unit> unlessA<A>(bool cond, IO<A> Function() action)

Returns the action argument when cond is false, otherwise returns IO.unit.

Implementation

static IO<Unit> unlessA<A>(bool cond, Function0<IO<A>> action) =>
    _unlessA(cond, action).traced('unlessA');

Constants

canceled

const IO<Unit> canceled

Creates an IO that immediately results in an Outcome of Canceled.

Implementation

static const IO<Unit> canceled = _Canceled();

cede

const IO<Unit> cede

Introduces an asynchronous boundary in the IO runtime loop that can be used for cancelation checking and fairness, among other things.

Implementation

static const IO<Unit> cede = _Cede();

now

const IO<DateTime> now

Returns the current DateTime when evaluation occurs.

Implementation

static const IO<DateTime> now = _Now();