An integer that identifies the term in the ZIO
sum type to which this
instance belongs (e.g.
An integer that identifies the term in the ZIO
sum type to which this
instance belongs (e.g. IO.Tags.Succeed
).
Sequentially zips this effect with the specified effect, combining the results into a tuple.
Returns an effect that executes both this effect and the specified effect, in parallel, specified effect result returned.
Returns an effect that executes both this effect and the specified effect, in parallel, specified effect result returned. If either side fails, then the other side will be interrupted, interrupted the result.
A variant of flatMap
that ignores the value produced by this effect.
Returns an effect that executes both this effect and the specified effect, in parallel, this effect result returned.
Returns an effect that executes both this effect and the specified effect, in parallel, this effect result returned. If either side fails, then the other side will be interrupted, interrupted the result.
Returns an effect that executes both this effect and the specified effect, in parallel, combining their results into a tuple.
Returns an effect that executes both this effect and the specified effect, in parallel, combining their results into a tuple. If either side fails, then the other side will be interrupted, interrupted the result.
Sequences the specified effect after this effect, but ignores the value produced by the effect.
Alias for &&&
.
Operator alias for orElse
.
Alias for flatMap
.
Alias for flatMap
.
val parsed = readFile("foo.txt") >>= parseFile
Returns an effect that submerges the error case of an Either
into the
ZIO
.
Returns an effect that submerges the error case of an Either
into the
ZIO
. The inverse operation of ZIO.either
.
Attempts to convert defects into a failure, throwing away all information about the cause of the failure.
Attempts to convert defects into a failure, throwing away all information about the cause of the failure.
Returns an effect whose failure and success channels have been mapped by
the specified pair of functions, f
and g
.
Shorthand for the uncurried version of ZIO.bracketExit
.
Shorthand for the curried version of ZIO.bracketExit
.
Executes the release effect only if there was an error.
Uncurried version.
Uncurried version. Doesn't offer curried syntax and has worse type-inference characteristics, but it doesn't allocate intermediate zio.ZIO.BracketAcquire_ and zio.ZIO.BracketRelease_ objects.
A less powerful variant of bracket
where the resource acquired by this
effect is not needed.
Recovers from all errors.
Recovers from all errors.
openFile("config.json").catchAll(_ => IO.succeed(defaultConfig))
Recovers from some or all of the error cases.
Recovers from some or all of the error cases.
openFile("data.json").catchSome { case FileNotFoundException(_) => openFile("backup.json") }
Maps this effect to the specified constant while preserving the effects of this effect.
Returns an effect that is delayed from this effect by the specified zio.duration.Duration.
Returns an effect whose failure and success have been lifted into an
Either
.The resulting effect cannot fail, because the failure case has
been exposed as part of the Either
success case.
Returns an effect whose failure and success have been lifted into an
Either
.The resulting effect cannot fail, because the failure case has
been exposed as part of the Either
success case.
This method is useful for recovering from ZIO
effects that may fail.
The error parameter of the returned ZIO
is Nothing
, since it is
guaranteed the ZIO
effect does not model failure.
Returns an effect that, if this effect _starts_ execution, then the
specified finalizer
is guaranteed to begin execution, whether this effect
succeeds, fails, or is interrupted.
Returns an effect that, if this effect _starts_ execution, then the
specified finalizer
is guaranteed to begin execution, whether this effect
succeeds, fails, or is interrupted.
Finalizers offer very powerful guarantees, but they are low-level, and
should generally not be used for releasing resources. For higher-level
logic built on ensuring
, see ZIO#bracket
.
Returns an effect that models the execution of this effect, followed by
the passing of its value to the specified continuation function k
,
followed by the effect that it returns.
Returns an effect that models the execution of this effect, followed by
the passing of its value to the specified continuation function k
,
followed by the effect that it returns.
val parsed = readFile("foo.txt").flatMap(file => parseFile(file))
Creates a composite effect that represents this effect followed by another one that may depend on the error produced by this one.
Creates a composite effect that represents this effect followed by another one that may depend on the error produced by this one.
val parsed = readFile("foo.txt").flatMapError(error => logErrorToFile(error))
Returns an effect that performs the outer effect first, followed by the inner effect, yielding the value of the inner effect.
Returns an effect that performs the outer effect first, followed by the inner effect, yielding the value of the inner effect.
This method can be used to "flatten" nested effects.
Returns an effect that swaps the error/success cases.
Returns an effect that swaps the error/success cases. This allows you to use all methods on the error channel, possibly before flipping back.
Swaps the error/value parameters, applies the function f
and flips the parameters back
Folds over the failure value or the success value to yield an effect that
does not fail, but succeeds with the value returned by the left or right
function passed to fold
.
A more powerful version of foldM
that allows recovering from any kind of failure except interruptions.
Recovers from errors by accepting one effect to execute for the case of an error, and one effect to execute for the case of success.
Recovers from errors by accepting one effect to execute for the case of an error, and one effect to execute for the case of success.
This method has better performance than either
since no intermediate
value is allocated and does not require subsequent calls to flatMap
to
define the next effect.
The error parameter of the returned IO
may be chosen arbitrarily, since
it will depend on the IO
s returned by the given continuations.
Repeats this effect forever (until the first error).
Repeats this effect forever (until the first error). For more sophisticated
schedules, see the repeat
method.
Returns an effect that forks this effect into its own separate fiber, returning the fiber immediately, without waiting for it to compute its value.
Returns an effect that forks this effect into its own separate fiber, returning the fiber immediately, without waiting for it to compute its value.
The returned fiber can be used to interrupt the forked fiber, await its result, or join the fiber. See zio.Fiber for more information.
for { fiber <- subtask.fork // Do stuff... a <- fiber.join } yield a
Forks an effect that will be executed on the specified ExecutionContext
.
Unwraps the optional success of this effect, but can fail with unit value.
Supervises this effect, which ensures that any fibers that are forked by the effect are handled by the provided supervisor.
Returns a new effect that ensures that any fibers that are forked by the effect are interrupted when this effect completes.
Switches the interrupt status for this effect.
Switches the interrupt status for this effect. If true
is used, then the
effect becomes interruptible (the default), while if false
is used, then
the effect becomes uninterruptible. These changes are compositional, so
they only affect regions of the effect.
Performs this effect interruptibly.
Performs this effect interruptibly. Because this is the default, this operation only has additional meaning if the effect is located within an uninterruptible section.
Returns an effect whose execution is locked to the specified executor.
Returns an effect whose execution is locked to the specified executor. This is useful when an effect must be executued somewhere, for example: on a UI thread, inside a client library's thread pool, inside a blocking thread pool, inside a low-latency thread pool, or elsewhere.
Use of this method does not alter the execution semantics of other effects composed with this one, making it easy to compositionally reason about where effects are running.
Returns an effect whose success is mapped by the specified f
function.
Returns an effect with its error channel mapped using the specified function.
Returns an effect with its error channel mapped using the specified function. This can be used to lift a "smaller" error into a "larger" error.
Returns an effect that, if evaluated, will return the lazily computed result of this effect.
Executes the effect on the specified ExecutionContext
and then shifts back
to the default one.
Runs the specified effect if this effect fails, providing the error to the effect if it exists.
Runs the specified effect if this effect fails, providing the error to the effect if it exists. The provided effect will not be interrupted.
Runs the specified effect if this effect is interrupted.
Runs the specified effect if this effect is terminated, either because of a defect or because of interruption.
Executes this effect, skipping the error but returning optionally the success.
Translates effect failure into death of the fiber, making all failures unchecked and not a part of the type of the effect.
Keeps none of the errors, and terminates the fiber with them, using
the specified function to convert the E
into a Throwable
.
Executes this effect and returns its value, if it succeeds, but otherwise executes the specified effect.
Returns an effect that will produce the value of this effect, unless it fails, in which case, it will produce the value of the specified effect.
Provides the ZIO
effect with its required environment, which eliminates
its dependency on R
.
Provides some of the environment required to run this effect,
leaving the remainder R0
.
Provides some of the environment required to run this effect,
leaving the remainder R0
.
val effect: ZIO[Console with Logging, Nothing, Unit] = ??? effect.provideSome[Console](console => new Console with Logging { val console = console val logging = new Logging { def log(line: String) = console.putStrLn(line) } } )
An effectful version of provideSome
, useful when the act of partial
provision requires an effect.
An effectful version of provideSome
, useful when the act of partial
provision requires an effect.
val effect: ZIO[Console with Logging, Nothing, Unit] = ??? val r0: ZIO[Console, Nothing, Console with Logging] = ??? effect.provideSomeM(r0)
Returns an effect that races this effect with the specified effect,
returning the first successful A
from the faster side.
Returns an effect that races this effect with the specified effect,
returning the first successful A
from the faster side. If one effect
succeeds, the other will be interrupted. If neither succeeds, then the
effect will fail with some error.
Returns an effect that races this effect with all the specified effects, yielding the value of the first effect to succeed with a value.
Returns an effect that races this effect with all the specified effects, yielding the value of the first effect to succeed with a value. Losers of the race will be interrupted immediately
Returns an effect that races this effect with the specified effect, yielding the first result to complete, whether by success or failure.
Returns an effect that races this effect with the specified effect, yielding the first result to complete, whether by success or failure. If neither effect completes, then the composed effect will not complete.
Returns an effect that races this effect with the specified effect, yielding the first result to succeed.
Returns an effect that races this effect with the specified effect, yielding the first result to succeed. If neither effect succeeds, then the composed effect will fail with some error.
Returns an effect that races this effect with the specified effect, calling the specified finisher as soon as one result or the other has been computed.
Attach a wrapping trace pointing to this location in case of error.
Attach a wrapping trace pointing to this location in case of error.
Useful when joining fibers to make the resulting trace mention
the join
point, otherwise only the traces of joined fibers are
included.
for { badFiber <- UIO(1 / 0).fork _ <- badFiber.join.refailWithTrace } yield ()
Keeps some of the errors, and terminates the fiber with the rest.
Keeps some of the errors, and terminates the fiber with the rest, using
the specified function to convert the E
into a Throwable
.
Keeps some of the errors, and terminates the fiber with the rest.
Repeats this effect with the specified schedule until the schedule completes, or until the first failure.
Repeats this effect with the specified schedule until the schedule
completes, or until the first failure.
Repeats are done in addition to the first execution so that
io.repeat(Schedule.once)
means "execute io and in case of success repeat io
once".
Repeats this effect with the specified schedule until the schedule completes, or until the first failure.
Repeats this effect with the specified schedule until the schedule completes, or until the first failure. In the event of failure the progress to date, together with the error, will be passed to the specified handler.
Repeats this effect with the specified schedule until the schedule completes, or until the first failure.
Repeats this effect with the specified schedule until the schedule completes, or until the first failure. In the event of failure the progress to date, together with the error, will be passed to the specified handler.
Retries with the specified retry policy.
Retries with the specified retry policy.
Retries are done following the failure of the original io
(up to a fixed maximum with
once
or recurs
for example), so that that io.retry(Schedule.once)
means
"execute io
and in case of failure, try again once".
Retries with the specified schedule, until it fails, and then both the value produced by the schedule together with the last error are passed to the recovery function.
Retries with the specified schedule, until it fails, and then both the value produced by the schedule together with the last error are passed to the recovery function.
Returns an effect that semantically runs the effect on a fiber, producing an zio.Exit for the completion value of the fiber.
Exposes the full cause of failure of this effect.
Exposes the full cause of failure of this effect.
case class DomainError() val veryBadIO: IO[DomainError, Unit] = IO.effectTotal(5 / 0) *> IO.fail(DomainError()) val caught: UIO[Unit] = veryBadIO.sandbox.catchAll { case Cause.Die(_: ArithmeticException) => // Caught defect: divided by zero! IO.succeed(0) case Cause.Fail(e) => // Caught error: DomainError! IO.succeed(0) case cause => // Caught unknown defects, shouldn't recover! IO.halt(cause) * }
Companion helper to sandbox
.
Companion helper to sandbox
. Allows recovery, and partial recovery, from
errors and defects alike, as in:
case class DomainError() val veryBadIO: IO[DomainError, Unit] = IO.effectTotal(5 / 0) *> IO.fail(DomainError()) val caught: IO[DomainError, Unit] = veryBadIO.sandboxWith(_.catchSome { case Cause.Die(_: ArithmeticException)=> // Caught defect: divided by zero! IO.succeed(0) })
Using sandboxWith
with catchSome
is better than using
io.sandbox.catchAll
with a partial match, because in
the latter, if the match fails, the original defects will
be lost and replaced by a MatchError
Summarizes a effect by computing some value before and after execution, and then combining the values to produce a summary, together with the result of execution.
Enables supervision for this effect.
Enables supervision for this effect. This will cause fibers forked by this effect to be tracked and will enable their inspection via ZIO.children.
Returns an effect that effectfully "peeks" at the success of this effect.
Returns an effect that effectfully "peeks" at the success of this effect.
readFile("data.json").tap(putStrLn)
Returns an effect that effectfully "peeks" at the failure or success of this effect.
Returns an effect that effectfully "peeks" at the failure or success of this effect.
readFile("data.json").tapBoth(logError(_), logData(_))
Returns an effect that effectfully "peeks" at the failure of this effect.
Returns an effect that effectfully "peeks" at the failure of this effect.
readFile("data.json").tapError(logError(_))
Returns a new effect that executes this one and times the execution.
A more powerful variation of timed
that allows specifying the clock.
Returns an effect that will timeout this effect, returning None
if the
timeout elapses before the effect has produced a value; and returning
Some
of the produced value otherwise.
Returns an effect that will timeout this effect, returning None
if the
timeout elapses before the effect has produced a value; and returning
Some
of the produced value otherwise.
If the timeout elapses without producing a value, the running effect will be safely interrupted
The same as timeout, but instead of producing a None
in the event
of timeout, it will produce the specified error.
Returns an effect that will timeout this effect, returning either the
default value if the timeout elapses before the effect has produced a
value; and or returning the result of applying the function f
to the
success value of the effect.
Returns an effect that will timeout this effect, returning either the
default value if the timeout elapses before the effect has produced a
value; and or returning the result of applying the function f
to the
success value of the effect.
If the timeout elapses without producing a value, the running effect will be safely interrupted
IO.succeed(1).timeoutTo(None)(Some(_))(1.second)
Returns an effect that keeps or breaks a promise based on the result of this effect.
Returns an effect that keeps or breaks a promise based on the result of this effect. Synchronizes interruption, so if this effect is interrupted, the specified promise will be interrupted, too.
Converts the effect into a scala.concurrent.Future.
Converts the effect into a scala.concurrent.Future.
Converts this ZIO to zio.Managed.
Converts this ZIO to zio.ZManaged with no release action.
Enables ZIO tracing for this effect.
Enables ZIO tracing for this effect. Because this is the default, this
operation only has an additional meaning if the effect is located within
an untraced
section, or the current fiber has been spawned by a parent
inside an untraced
section.
Toggles ZIO tracing support for this effect.
Toggles ZIO tracing support for this effect. If true
is used, then the
effect will accumulate traces, while if false
is used, then tracing
is disabled. These changes are compositional, so they only affect regions
of the effect.
Performs this effect uninterruptibly.
Performs this effect uninterruptibly. This will prevent the effect from being terminated externally, but the effect may fail for internal reasons (e.g. an uncaught error) or terminate due to defect.
Uninterruptible effects may recover from all failure causes (including interruption of an inner effect that has been made interruptible).
Returns the effect resulting from mapping the success of this effect to unit.
The inverse operation to sandbox
.
The inverse operation to sandbox
. Submerges the full cause of failure.
Disables supervision for this effect.
Disables supervision for this effect. This will cause fibers forked by this effect to not be tracked or appear in the list returned by ZIO.children.
Disables ZIO tracing facilities for the duration of the effect.
Disables ZIO tracing facilities for the duration of the effect.
Note: ZIO tracing is cached, as such after the first iteration
it has a negligible effect on performance of hot-spots (Additional
hash map lookup per flatMap). As such, using untraced
sections
is not guaranteed to result in a noticeable performance increase.
The moral equivalent of if (p) exp
The moral equivalent of if (p) exp
when p
has side-effects
A named alias for &&&
or <*>
.
A named alias for <*
.
A named alias for <&>
.
A named alias for <&
.
A named alias for &>
.
A named alias for *>
.
Sequentially zips this effect with the specified effect using the specified combiner function.
Returns an effect that executes both this effect and the specified effect,
in parallel, combining their results with the specified f
function.
Returns an effect that executes both this effect and the specified effect,
in parallel, combining their results with the specified f
function. If
either side fails, then the other side will be interrupted.
A
ZIO[R, E, A]
("Zee-Oh of Are Eeh Aye") is an immutable data structure that models an effectful program. The effect requires an environmentR
, and the effect may fail with an errorE
or produce a singleA
.Conceptually, this structure is equivalent to
ReaderT[R, EitherT[UIO, E, ?]]
for some infallible effect monadUIO
, but because monad transformers perform poorly in Scala, this data structure bakes in the reader effect ofReaderT
with the recoverable error effect ofEitherT
without runtime overhead.ZIO
values are ordinary immutable values, and may be used like any other value in purely functional code. BecauseZIO
values just *model* effects (like input / output), which must be interpreted by a separate runtime system,ZIO
values are entirely pure and do not violate referential transparency.ZIO
values can efficiently describe the following classes of effects:ZIO.succeed
—Error Effects
ZIO.fail
IO.effect
IO.effectAsync
IO#fork
IO#bracket
—Contextual Effects
ZIO.access
The concurrency model is based on fibers, a user-land lightweight thread, which permit cooperative multitasking, fine-grained interruption, and very high performance with large numbers of concurrently executing fibers.
ZIO
values compose with otherZIO
values in a variety of ways to build complex, rich, interactive applications. See the methods onZIO
for more details about how to composeZIO
values.In order to integrate with Scala,
ZIO
values must be interpreted into the Scala runtime. This process of interpretation executes the effects described by a given immutableZIO
value. For more information on interpretingZIO
values, see the default interpreter inDefaultRuntime
or the safe main function inApp
.