IO

Runs this IO and the parameter in parallel.

Failure in either of the IOs will cancel the other one. If the whole computation is canceled, both actions are also canceled.

Runs the current IO, then runs the parameter, keeping its result. The result of the first action is ignored. If the source fails, the other action won't run. Not suitable for use when the parameter is a recursive reference to the current expression.

Like &>, but keeps the result of the source

Like *>, but keeps the result of the source.

For a similar method that also runs the parameter in case of failure or interruption, see guarantee.

Runs the current IO, then runs the parameter, keeping its result. The result of the first action is ignored. If the source fails, the other action won't run. Evaluation of the parameter is done lazily, making this suitable for recursion.

Replaces the result of this IO with the given value.

Materializes any sequenced exceptions into value space, where they may be handled.

This is analogous to the catch clause in try/catch, being the inverse of IO.raiseError. Thus:

IO.raiseError(ex).attempt.unsafeRunAsync === Left(ex)

Returns a resource that will start execution of this IO in the background.

In case the resource is closed while this IO is still running (e.g. due to a failure in use), the background action will be canceled.

Runs the current and given IO in parallel, producing the pair of the results. If either fails with an error, the result of the whole will be that error and the other will be canceled.

Runs the current and given IO in parallel, producing the pair of the outcomes. Both outcomes are produced, regardless of whether they complete successfully.

Returns an IO action that treats the source task as the acquisition of a resource, which is then exploited by the use function and then released.

The bracket operation is the equivalent of the try {} catch {} finally {} statements from mainstream languages.

The bracket operation installs the necessary exception handler to release the resource in the event of an exception being raised during the computation, or in case of cancelation.

If an exception is raised, then bracket will re-raise the exception ''after'' performing the release. If the resulting task gets canceled, then bracket will still perform the release, but the yielded task will be non-terminating (equivalent with IO.never).

Example:

 import java.io._

 def readFile(file: File): IO[String] = {
   // Opening a file handle for reading text
   val acquire = IO(new BufferedReader(
     new InputStreamReader(new FileInputStream(file), "utf-8")
   ))

   acquire.bracket { in =>
     // Usage part
     IO {
       // Yes, ugly Java, non-FP loop;
       // side-effects are suspended though
       var line: String = null
       val buff = new StringBuilder()
       do {
         line = in.readLine()
         if (line != null) buff.append(line)
       } while (line != null)
       buff.toString()
     }
   } { in =>
     // The release part
     IO(in.close())
   }
 }

Note that in case of cancelation the underlying implementation cannot guarantee that the computation described by use doesn't end up executed concurrently with the computation from release. In the example above that ugly Java loop might end up reading from a BufferedReader that is already closed due to the task being canceled, thus triggering an error in the background with nowhere to get signaled.

In this particular example, given that we are just reading from a file, it doesn't matter. But in other cases it might matter, as concurrency on top of the JVM when dealing with I/O might lead to corrupted data.

For those cases you might want to do synchronization (e.g. usage of locks and semaphores) and you might want to use bracketCase, the version that allows you to differentiate between normal termination and cancelation.

'''NOTE on error handling''': in case both the release function and the use function throws, the error raised by release gets signaled.

For example:

 val foo = new RuntimeException("Foo")
 val bar = new RuntimeException("Bar")
 IO("resource").bracket { _ =>
   // use
   IO.raiseError(foo)
 } { _ =>
   // release
   IO.raiseError(bar)
 }

In this case the resulting IO will raise error foo, while the bar error gets reported on a side-channel. This is consistent with the behavior of Java's "Try with resources" except that no involved exceptions are mutated (i.e., in contrast to Java, bar isn't added as a suppressed exception to foo).

Returns a new IO task that treats the source task as the acquisition of a resource, which is then exploited by the use function and then released, with the possibility of distinguishing between normal termination and cancelation, such that an appropriate release of resources can be executed.

The bracketCase operation is the equivalent of try {} catch {} finally {} statements from mainstream languages when used for the acquisition and release of resources.

The bracketCase operation installs the necessary exception handler to release the resource in the event of an exception being raised during the computation, or in case of cancelation.

In comparison with the simpler bracket version, this one allows the caller to differentiate between normal termination, termination in error and cancelation via an Outcome parameter.

Returns an IO that will delay the execution of the source by the given duration.

Shifts the execution of the current IO to the specified ExecutionContext. All stages of the execution will default to the pool in question, and any asynchronous callbacks will shift back to the pool upon completion. Any nested use of evalOn will override the specified pool. Once the execution fully completes, default control will be shifted back to the enclosing (inherited) pool.

Monadic bind on IO, used for sequentially composing two IO actions, where the value produced by the first IO is passed as input to a function producing the second IO action.

Due to this operation's signature, flatMap forces a data dependency between two IO actions, thus ensuring sequencing (e.g. one action to be executed before another one).

Any exceptions thrown within the function will be caught and sequenced into the IO, because due to the nature of asynchronous processes, without catching and handling exceptions, failures would be completely silent and IO references would never terminate on evaluation.

Evaluates the current IO in an infinite loop, terminating only on error or cancelation.

 IO.println("Hello, World!").foreverM    // continues printing forever

Executes the given finalizer when the source is finished, either in success or in error, or if canceled.

This variant of guaranteeCase evaluates the given finalizer regardless of how the source gets terminated:

• normal completion
• completion in error
• cancelation

This equivalence always holds:

 io.guarantee(f) <-> IO.unit.bracket(_ => io)(_ => f)

Executes the given finalizer when the source is finished, either in success or in error, or if canceled, allowing for differentiating between exit conditions.

This variant of guarantee injects an Outcome in the provided function, allowing one to make a difference between:

• normal completion
• completion in error
• cancelation

This equivalence always holds:

 io.guaranteeCase(f) <-> IO.unit.bracketCase(_ => io)((_, e) => f(e))

Handle any error, potentially recovering from it, by mapping it to another IO value.

Implements ApplicativeError.handleErrorWith.

Functor map on IO. Given a mapping function, it transforms the value produced by the source, while keeping the IO context.

Any exceptions thrown within the function will be caught and sequenced into the IO. Due to the nature of asynchronous processes, without catching and handling exceptions, failures would be completely silent and IO references would never terminate on evaluation.

Replaces failures in this IO with an empty Option.

Returns a new value that transforms the result of the source, given the recover or map functions, which get executed depending on whether the result ends in error or if it is successful.

This is an optimization on usage of attempt and map, this equivalence being true:

 io.redeem(recover, map) <-> io.attempt.map(_.fold(recover, map))

Usage of redeem subsumes handleError because:

 io.redeem(fe, id) <-> io.handleError(fe)

Returns a new value that transforms the result of the source, given the recover or bind functions, which get executed depending on whether the result ends in error or if it is successful.

This is an optimization on usage of attempt and flatMap, this equivalence being available:

 io.redeemWith(recover, bind) <-> io.attempt.flatMap(_.fold(recover, bind))

Usage of redeemWith subsumes handleErrorWith because:

 io.redeemWith(fe, F.pure) <-> io.handleErrorWith(fe)

Usage of redeemWith also subsumes flatMap because:

 io.redeemWith(F.raiseError, fs) <-> io.flatMap(fs)

Start execution of the source suspended in the IO context.

This can be used for non-deterministic / concurrent execution. The following code is more or less equivalent with parMap2 (minus the behavior on error handling and cancelation):

 def par2[A, B](ioa: IO[A], iob: IO[B]): IO[(A, B)] =
   for {
     fa <- ioa.start
     fb <- iob.start
      a <- fa.join
      b <- fb.join
   } yield (a, b)

Note in such a case usage of parMapN (via cats.Parallel) is still recommended because of behavior on error and cancelation — consider in the example above what would happen if the first task finishes in error. In that case the second task doesn't get canceled, which creates a potential memory leak.

Also see background for a safer alternative.

Translates this IO[A] into a SyncIO value which, when evaluated, runs the original IO to its completion, or until the first asynchronous, boundary, whichever is encountered first.

Returns an IO that either completes with the result of the source within the specified time duration or otherwise raises a TimeoutException.

The source is canceled in the event that it takes longer than the specified time duration to complete.

Returns an IO that either completes with the result of the source within the specified time duration or otherwise evaluates the fallback.

The source is canceled in the event that it takes longer than the FiniteDuration to complete, the evaluation of the fallback happening immediately after that.

Converts the source IO into any F type that implements the LiftIO type class.

Makes the source IO uninterruptible such that a cats.effect.kernel.Fiber#cancel signal is ignored until completion.

Triggers the evaluation of the source and any suspended side effects therein, but ignores the result.

This operation is similar to unsafeRunAsync, in that the evaluation can happen asynchronously, except no callback is required and therefore the result is ignored.

Note that errors still get logged (via IO's internal logger), because errors being thrown should never be totally silent.

Passes the result of the encapsulated effects to the given callback by running them as impure side effects.

Any exceptions raised within the effect will be passed to the callback in the Either. The callback will be invoked at most once. Note that it is very possible to construct an IO which never returns while still never blocking a thread, and attempting to evaluate that IO with this method will result in a situation where the callback is never invoked.

As the name says, this is an UNSAFE function as it is impure and performs side effects. You should ideally only call this function ''once'', at the very end of your program.

Evaluates the effect, returning a cancelation token that can be used to cancel it.

This is similar to unsafeRunAsync in that it evaluates the IO as a side effect in a non-blocking fashion, but uses a Future rather than an explicit callback. This function should really only be used if interoperating with code which uses Scala futures.

Evaluates the effect and produces the result in a Future.

This is similar to unsafeRunAsync in that it evaluates the IO as a side effect in a non-blocking fashion, but uses a Future rather than an explicit callback. This function should really only be used if interoperating with code which uses Scala futures.

Evaluates the effect and produces the result in a Future, along with a cancelation token that can be used to cancel the original effect.

This is similar to unsafeRunAsync in that it evaluates the IO as a side effect in a non-blocking fashion, but uses a Future rather than an explicit callback. This function should really only be used if interoperating with code which uses Scala futures.

Ignores the result of this IO.