Packages

sealed abstract class IO[+E, +A] extends Serializable

An IO[E, A] ("Eye-Oh of Eeh Aye") is an immutable data structure that describes an effectful action that may fail with an E, run forever, or produce a single A at some point in the future.

Conceptually, this structure is equivalent to EitherT[F, E, A] for some infallible effect monad F, but because monad transformers perform poorly in Scala, this structure bakes in the EitherT without runtime overhead.

IO values are ordinary immutable values, and may be used like any other values in purely functional code. Because IO values just *describe* effects, which must be interpreted by a separate runtime system, they are entirely pure and do not violate referential transparency.

IO values can efficiently describe the following classes of effects:

  • Pure Values — IO.point
  • Synchronous Effects — IO.sync
  • Asynchronous Effects — IO.async
  • Concurrent Effects — io.fork
  • Resource Effects — io.bracket

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.

IO values compose with other IO values in a variety of ways to build complex, rich, interactive applications. See the methods on IO for more details about how to compose IO values.

In order to integrate with Scala, IO values must be interpreted into the Scala runtime. This process of interpretation executes the effects described by a given immutable IO value. For more information on interpreting IO values, see the default interpreter in RTS or the safe main function in App.

Self Type
IO[E, A]
Linear Supertypes
Serializable, Serializable, AnyRef, Any
Known Subclasses
AsyncEffect, Descriptor, Ensuring, Fail, FlatMap, Fork, Lock, Point, Redeem, Strict, Supervise, SyncEffect, Uninterruptible, Yield
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. IO
  2. Serializable
  3. Serializable
  4. AnyRef
  5. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Abstract Value Members

  1. abstract def tag: Int

    An integer that identifies the term in the IO sum type to which this instance belongs (e.g.

    An integer that identifies the term in the IO sum type to which this instance belongs (e.g. IO.Tags.Point).

Concrete Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. final def *>[E1 >: E, B](io: ⇒ IO[E1, B]): IO[E1, B]

    A variant of flatMap that ignores the value produced by this action.

  4. final def <*[E1 >: E, B](io: ⇒ IO[E1, B]): IO[E1, A]

    Sequences the specified action after this action, but ignores the value produced by the action.

  5. final def <>[E2, A1 >: A](that: ⇒ IO[E2, A1]): IO[E2, A1]

    Alias for orElse.

    Alias for orElse.

    Executes this action and returns its value, if it succeeds, but otherwise executes the specified action.

  6. final def <||>[E2, B](that: ⇒ IO[E2, B]): IO[E2, Either[A, B]]

    Alias for orElseEither.

    Alias for orElseEither.

    Executes this action and returns its value, if it succeeds, but otherwise executes the specified action.

  7. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  8. final def absolve[E1, B](implicit ev1: <:<[IO[E, A], IO[E1, Either[E1, B]]]): IO[E1, B]

    Submerges the error case of an Either into the IO.

    Submerges the error case of an Either into the IO. The inverse operation of IO.attempt.

  9. final def as[A1 >: A]: IO[E, A1]

    Widens the action type to any supertype.

    Widens the action type to any supertype. While map suffices for this purpose, this method is significantly faster for this purpose.

  10. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  11. final def attempt: IO[Nothing, Either[E, A]]

    Executes this action, capturing both failure and success and returning the result in an Either.

    Executes this action, capturing both failure and success and returning the result in an Either. This method is useful for recovering from IO actions that may fail.

    The error parameter of the returned IO is Nothing, since it is guaranteed the IO action does not raise any errors.

  12. final def bimap[E2, B](f: (E) ⇒ E2, g: (A) ⇒ B): IO[E2, B]

    Maps an IO[E, A] into an IO[E2, B] by applying the specified E => E2 and A => B functions to the output of this action.

    Maps an IO[E, A] into an IO[E2, B] by applying the specified E => E2 and A => B functions to the output of this action. Repeated applications of bimap (io.bimap(f1, g1).bimap(f2, g2)...bimap(f10000, g20000)) are guaranteed stack safe to a depth of at least 10,000.

  13. final def bracket[E1 >: E, B](release: (A) ⇒ IO[Nothing, _])(use: (A) ⇒ IO[E1, B]): IO[E1, B]

    When this action represents acquisition of a resource (for example, opening a file, launching a thread, etc.), bracket can be used to ensure the acquisition is not interrupted and the resource is released.

    When this action represents acquisition of a resource (for example, opening a file, launching a thread, etc.), bracket can be used to ensure the acquisition is not interrupted and the resource is released.

    The function does two things:

    1. Ensures this action, which acquires the resource, will not be interrupted. Of course, acquisition may fail for internal reasons (an uncaught exception). 2. Ensures the release action will not be interrupted, and will be executed so long as this action successfully acquires the resource.

    In between acquisition and release of the resource, the use action is executed.

    If the release action fails, then the entire action will fail even if the use action succeeds. If this fail-fast behavior is not desired, errors produced by the release action can be caught and ignored.

    openFile("data.json").bracket(closeFile) { file =>
  for {
    header <- readHeader(file)
    ...
  } yield result
}
  14. final def bracket0[E1 >: E, B](release: (A, Exit[E1, B]) ⇒ IO[Nothing, _])(use: (A) ⇒ IO[E1, B]): IO[E1, B]

    A more powerful version of bracket that provides information on whether or not use succeeded to the release action.

  15. final def bracketOnError[E1 >: E, B](release: (A) ⇒ IO[Nothing, _])(use: (A) ⇒ IO[E1, B]): IO[E1, B]

    Executes the release action only if there was an error.

  16. final def bracket_[E1 >: E, B](release: IO[Nothing, _])(use: IO[E1, B]): IO[E1, B]

    A less powerful variant of bracket where the value produced by this action is not needed.

  17. final def catchAll[E2, A1 >: A](h: (E) ⇒ IO[E2, A1]): IO[E2, A1]

    Recovers from all errors.

    Recovers from all errors.

    openFile("config.json").catchAll(_ => IO.succeed(defaultConfig))
  18. final def catchSome[E1 >: E, A1 >: A](pf: PartialFunction[E, IO[E1, A1]]): IO[E1, A1]

    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")
}
  19. def clone(): AnyRef
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @native() @throws( ... )
  20. final def const[B](b: ⇒ B): IO[E, B]

    Maps this action to the specified constant while preserving the effects of this action.

  21. final def delay(duration: Duration): IO[E, A]

    Delays this action by the specified amount of time.

  22. final def ensuring(finalizer: IO[Nothing, _]): IO[E, A]

    Executes the specified finalizer, whether this action succeeds, fails, or is interrupted.

    Executes the specified finalizer, whether this action succeeds, fails, or is interrupted. This method should not be used for cleaning up resources, because it's possible the fiber will be interrupted after acquisition but before the finalizer is added.

  23. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  24. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  25. def finalize(): Unit
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  26. final def flatMap[E1 >: E, B](f0: (A) ⇒ IO[E1, B]): IO[E1, B]

    Creates a composite action that represents this action followed by another one that may depend on the value produced by this one.

    Creates a composite action that represents this action followed by another one that may depend on the value produced by this one.

    val parsed = readFile("foo.txt").flatMap(file => parseFile(file))
  27. final def flatMapError[E2](f: (E) ⇒ IO[Nothing, E2]): IO[E2, A]

    Creates a composite action that represents this action followed by another one that may depend on the error produced by this one.

    Creates a composite action that represents this action followed by another one that may depend on the error produced by this one.

    val parsed = readFile("foo.txt").flatMapError(error => logErrorToFile(error))
  28. final def flatten[E1 >: E, B](implicit ev1: <:<[A, IO[E1, B]]): IO[E1, B]
  29. final def flip: IO[A, E]

    Swaps the error/value around, making it easier to handle errors.

  30. final def flipWith[A1, E1](f: (IO[A, E]) ⇒ IO[A1, E1]): IO[E1, A1]

    Swaps the error/value parameters, applies the function f and flips the parameters back

  31. final def fold[B](err: (E) ⇒ B, succ: (A) ⇒ B): IO[Nothing, B]

    Less powerful version of redeem which always returns a successful IO[Nothing, B] after applying one of the given mapping functions depending on the result of this IO

  32. final def forever: IO[E, Nothing]

    Repeats this action forever (until the first error).

    Repeats this action forever (until the first error). For more sophisticated schedules, see the repeat method.

  33. final def fork: IO[Nothing, Fiber[E, A]]

    Forks this action into its own separate fiber, returning immediately without the value produced by this action.

    Forks this action into its own separate fiber, returning immediately without the value produced by this action.

    The Fiber[E, A] returned by this action can be used to interrupt the forked fiber with some exception, or to join the fiber to "await" its computed value.

    for {
  fiber <- subtask.fork
  // Do stuff...
  a <- fiber.join
} yield a
  34. final def forkOn(ec: ExecutionContext): IO[E, Fiber[E, A]]

    Forks an action that will be executed on the specified ExecutionContext.

  35. final def forkWith(handler: (Cause[Any]) ⇒ IO[Nothing, _]): IO[Nothing, Fiber[E, A]]

    A more powerful version of fork that allows specifying a handler to be invoked on any exceptions that are not handled by the forked fiber.

  36. final def get[E1 >: E, B](implicit ev1: =:=[E1, Nothing], ev2: <:<[A, Option[B]]): IO[Unit, B]

    Unwraps the optional success of this effect, but can fail with unit value.

  37. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  38. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  39. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  40. final def lock(executor: Executor): IO[E, A]

    Locks the execution of this action to the specified executor.

  41. final def managed(release: (A) ⇒ IO[Nothing, _]): Managed[E, A]
  42. final def map[B](f: (A) ⇒ B): IO[E, B]

    Maps an IO[E, A] into an IO[E, B] by applying the specified A => B function to the output of this action.

    Maps an IO[E, A] into an IO[E, B] by applying the specified A => B function to the output of this action. Repeated applications of map (io.map(f1).map(f2)...map(f10000)) are guaranteed stack safe to a depth of at least 10,000.

  43. final def mapError[E2](f: (E) ⇒ E2): IO[E2, A]

    Maps over the error type.

    Maps over the error type. This can be used to lift a "smaller" error into a "larger" error.

  44. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  45. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  46. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  47. final def on(ec: ExecutionContext): IO[E, A]

    Executes the action on the specified ExecutionContext and then shifts back to the default one.

  48. final def onError(cleanup: (Cause[E]) ⇒ IO[Nothing, _]): IO[E, A]

    Runs the specified action if this action fails, providing the error to the action if it exists.

    Runs the specified action if this action fails, providing the error to the action if it exists. The provided action will not be interrupted.

  49. final def onInterrupt(cleanup: IO[Nothing, _]): IO[E, A]

    Runs the specified action if this action is interrupted.

  50. final def onTermination(cleanup: (Cause[Nothing]) ⇒ IO[Nothing, _]): IO[E, A]

    Runs the specified action if this action is terminated, either because of a defect or because of interruption.

  51. final def option: IO[Nothing, Option[A]]

    Executes this action, skipping the error but returning optionally the success.

  52. final def orDie[E1 >: E](implicit ev: =:=[E1, Throwable]): IO[Nothing, A]

    Translates the checked error (if present) into termination.

  53. final def orDieWith(f: (E) ⇒ Throwable): IO[Nothing, A]
  54. final def orElse[E2, A1 >: A](that: ⇒ IO[E2, A1]): IO[E2, A1]

    Executes this action and returns its value, if it succeeds, but otherwise executes the specified action.

  55. final def orElseEither[E2, B](that: ⇒ IO[E2, B]): IO[E2, Either[A, B]]

    Executes this action and returns its value, if it succeeds, but otherwise executes the specified action.

  56. final def peek[E1 >: E, B](f: (A) ⇒ IO[E1, B]): IO[E1, A]

    Calls the provided function with the result of this action, and sequences the resulting action after this action, but ignores the value produced by the action.

    Calls the provided function with the result of this action, and sequences the resulting action after this action, but ignores the value produced by the action.

    readFile("data.json").peek(putStrLn)
  57. final def race[E1 >: E, A1 >: A](that: IO[E1, A1]): IO[E1, A1]

    Races this action with the specified action, returning the first result to produce an A, whichever it is.

    Races this action with the specified action, returning the first result to produce an A, whichever it is. If neither action succeeds, then the action will fail with some error.

  58. def raceAll[E1 >: E, A1 >: A](ios: Iterable[IO[E1, A1]]): IO[E1, A1]
  59. final def raceAttempt[E1 >: E, A1 >: A](that: IO[E1, A1]): IO[E1, A1]

    Races this action with the specified action, returning the first result to *finish*, whether it is by producing a value or by failing with an error.

    Races this action with the specified action, returning the first result to *finish*, whether it is by producing a value or by failing with an error. If either of two actions fails before the other succeeds, the entire race will fail with that error.

  60. final def raceEither[E1 >: E, B](that: IO[E1, B]): IO[E1, Either[A, B]]

    Races this action with the specified action, returning the first result to produce a value, whichever it is.

    Races this action with the specified action, returning the first result to produce a value, whichever it is. If neither action succeeds, then the action will fail with some error.

  61. final def raceWith[E1, E2, B, C](that: IO[E1, B])(leftDone: (Exit[E, A], Fiber[E1, B]) ⇒ IO[E2, C], rightDone: (Exit[E1, B], Fiber[E, A]) ⇒ IO[E2, C]): IO[E2, C]

    Races this action with the specified action, invoking the specified finisher as soon as one value or the other has been computed.

  62. final def redeem[E2, B](err: (E) ⇒ IO[E2, B], succ: (A) ⇒ IO[E2, B]): IO[E2, B]

    Recovers from errors by accepting one action to execute for the case of an error, and one action to execute for the case of success.

    Recovers from errors by accepting one action to execute for the case of an error, and one action to execute for the case of success.

    This method has better performance than attempt since no intermediate value is allocated and does not require subsequent calls to flatMap to define the next action.

    The error parameter of the returned IO may be chosen arbitrarily, since it will depend on the IOs returned by the given continuations.

  63. final def redeem0[E2, B](err: (Cause[E]) ⇒ IO[E2, B], succ: (A) ⇒ IO[E2, B]): IO[E2, B]

    A more powerful version of redeem that allows recovering from any kind of failure except interruptions.

  64. final def repeat[B](schedule: Schedule[A, B], clock: Clock = Clock.Live): IO[E, B]

    Repeats this action with the specified schedule until the schedule completes, or until the first failure.

    Repeats this action 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".

  65. final def repeatOrElse[E2, B](schedule: Schedule[A, B], orElse: (E, Option[B]) ⇒ IO[E2, B], clock: Clock = Clock.Live): IO[E2, B]

    Repeats this action with the specified schedule until the schedule completes, or until the first failure.

    Repeats this action 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.

  66. final def repeatOrElse0[B, E2, C](schedule: Schedule[A, B], orElse: (E, Option[B]) ⇒ IO[E2, C], clock: Clock = Clock.Live): IO[E2, Either[C, B]]

    Repeats this action with the specified schedule until the schedule completes, or until the first failure.

    Repeats this action 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.

  67. final def retry[E1 >: E, S](policy: Schedule[E1, S], clock: Clock = Clock.Live): IO[E1, A]

    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".

  68. final def retryOrElse[A2 >: A, E1 >: E, S, E2](policy: Schedule[E1, S], orElse: (E1, S) ⇒ IO[E2, A2], clock: Clock = Clock.Live): IO[E2, A2]

    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.

  69. final def retryOrElse0[E1 >: E, S, E2, B](policy: Schedule[E1, S], orElse: (E1, S) ⇒ IO[E2, B], clock: Clock = Clock.Live): IO[E2, Either[B, A]]

    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.

  70. final def run: IO[Nothing, Exit[E, A]]

    Runs this action in a new fiber, resuming when the fiber terminates.

  71. final def sandbox: IO[Cause[E], A]

    Runs this action in a new fiber, resuming when the fiber terminates.

    Runs this action in a new fiber, resuming when the fiber terminates.

    If the fiber fails with an error it will be captured in Right side of the error Either If the fiber terminates because of defect, list of defects will be captured in the Left side of the Either

    Allows recovery from errors and defects alike, as in:

    case class DomainError()

val veryBadIO: IO[DomainError, Unit] =
  IO.sync(5 / 0) *> IO.fail(DomainError())

val caught: IO[Nothing, Unit] =
  veryBadIO.sandbox.catchAll {
    case Left((_: ArithmeticException) :: Nil) =>
      // Caught defect: divided by zero!
      IO.succeed(0)
    case Left(ts) =>
      // Caught unknown defects, shouldn't recover!
      IO.terminate0(ts)
    case Right(e) =>
      // Caught error: DomainError!
     IO.succeed(0)
  }
  72. final def sandboxWith[E2, B](f: (IO[Cause[E], A]) ⇒ IO[Cause[E2], B]): IO[E2, B]

    Companion helper to sandbox.

    Companion helper to sandbox.

    Has a performance penalty due to forking a new fiber.

    Allows recovery, and partial recovery, from errors and defects alike, as in:

    case class DomainError()

val veryBadIO: IO[DomainError, Unit] =
  IO.sync(5 / 0) *> IO.fail(DomainError())

val caught: IO[DomainError, Unit] =
  veryBadIO.sandboxWith(_.catchSome {
    case Left((_: ArithmeticException) :: Nil) =>
      // 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

  73. final def summarized[E1 >: E, B, C](f: (B, B) ⇒ C)(summary: IO[E1, B]): IO[E1, (C, A)]

    Summarizes a action by computing some value before and after execution, and then combining the values to produce a summary, together with the result of execution.

  74. final def supervise: IO[E, A]

    Supervises this action, which ensures that any fibers that are forked by the action are interrupted when this action completes.

  75. final def superviseWith(supervisor: (Iterable[Fiber[_, _]]) ⇒ IO[Nothing, _]): IO[E, A]

    Supervises this action, which ensures that any fibers that are forked by the action are handled by the provided supervisor.

  76. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  77. final def timed: IO[E, (Duration, A)]

    Returns a new action that executes this one and times the execution.

  78. final def timed0[E1 >: E](nanoTime: IO[E1, Long]): IO[E1, (Duration, A)]

    A more powerful variation of timed that allows specifying the clock.

  79. final def timeout(d: Duration): IO[E, Option[A]]

    Times out an action by the specified duration.

  80. final def timeout0[B](z: B)(f: (A) ⇒ B)(duration: Duration): IO[E, B]

    Times out this action by the specified duration.

    Times out this action by the specified duration.

    IO.point(1).timeout0(Option.empty[Int])(Some(_))(1.second)
  81. final def timeoutFail[E1 >: E](e: E1)(d: Duration): IO[E1, A]

    Flattens a nested action with a specified duration.

  82. final def to[E1 >: E, A1 >: A](p: Promise[E1, A1]): IO[Nothing, Boolean]

    Keep or break a promise based on the result of this action.

  83. def toString(): String
    Definition Classes
    AnyRef → Any
  84. final def uninterruptible: IO[E, A]

    Performs this action non-interruptibly.

    Performs this action non-interruptibly. This will prevent the action from being terminated externally, but the action may fail for internal reasons (e.g. an uncaught error) or terminate due to defect.

  85. final def unsandbox[E1, A1 >: A](implicit ev1: <:<[IO[E, A], IO[Cause[E1], A1]]): IO[E1, A1]

    The inverse operation to sandbox

    The inverse operation to sandbox

    Terminates with exceptions on the Left side of the Either error, if it exists. Otherwise extracts the contained IO[E, A]

  86. final def unyielding: IO[E, A]

    Marks this action as unyielding to the runtime system for better scheduling.

  87. final def void: IO[E, Unit]

    Maps this action to one producing unit, but preserving the effects of this action.

  88. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  89. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  90. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @native() @throws( ... )
  91. final def when[E1 >: E](b: Boolean)(implicit ev1: <:<[IO[E, A], IO[E1, Unit]]): IO[E1, Unit]

    The moral equivalent of if (p) exp

  92. final def whenM[E1 >: E](b: IO[Nothing, Boolean])(implicit ev1: <:<[IO[E, A], IO[E1, Unit]]): IO[E1, Unit]

    The moral equivalent of if (p) exp when p has side-effects

  93. final def zip[E1 >: E, B](that: IO[E1, B]): IO[E1, (A, B)]

    Sequentially zips this effect with the specified effect, combining the results into a tuple.

  94. final def zipPar[E1 >: E, B](that: IO[E1, B]): IO[E1, (A, B)]

    Executes both this action and the specified action in parallel, returning a tuple of their results.

    Executes both this action and the specified action in parallel, returning a tuple of their results. If either individual action fails, then the returned action will fail.

  95. final def zipWith[E1 >: E, B, C](that: IO[E1, B])(f: (A, B) ⇒ C): IO[E1, C]

    Sequentially zips this effect with the specified effect using the specified combiner function.

  96. final def zipWithPar[E1 >: E, B, C](that: IO[E1, B])(f: (A, B) ⇒ C): IO[E1, C]

    Executes both this action and the specified action in parallel, combining their results using given function f.

    Executes both this action and the specified action in parallel, combining their results using given function f. If either individual action fails, then the returned action will fail.

    TODO: Replace with optimized primitive.

Inherited from Serializable

Inherited from Serializable

Inherited from AnyRef

Inherited from Any

Ungrouped