Packages

object IO extends IOCompanionPlatform with IOLowPriorityImplicits with Serializable

Source
IO.scala
Linear Supertypes
Serializable, IOLowPriorityImplicits, IOCompanionPlatform, AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. IO
  2. Serializable
  3. IOLowPriorityImplicits
  4. IOCompanionPlatform
  5. AnyRef
  6. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Type Members

  1. class IOMonoid[A] extends IOSemigroup[A] with Monoid[IO[A]]
    Attributes
    protected
  2. class IOSemigroup[A] extends Semigroup[IO[A]]
    Attributes
    protected
    Definition Classes
    IOLowPriorityImplicits
  3. class IOSemigroupK extends SemigroupK[IO]
    Attributes
    protected
  4. type Par[A] = T[IO, A]

    Newtype encoding for an IO datatype that has a cats.Applicative capable of doing parallel processing in ap and map2, needed for implementing cats.Parallel.

    Newtype encoding for an IO datatype that has a cats.Applicative capable of doing parallel processing in ap and map2, needed for implementing cats.Parallel.

    For converting back and forth you can use either the Parallel[IO] instance or the methods cats.effect.kernel.Par.ParallelF.apply for wrapping any IO value and cats.effect.kernel.Par.ParallelF.value for unwrapping it.

    The encoding is based on the "newtypes" project by Alexander Konovalov, chosen because it's devoid of boxing issues and a good choice until opaque types will land in Scala.

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##: Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. implicit def alignForIO: Align[IO]
  5. implicit def alignForIOPar: Align[Par]
  6. def apply[A](thunk: => A): IO[A]

    Suspends a synchronous side effect in IO.

    Suspends a synchronous side effect in IO. Use IO.apply if your side effect is not thread-blocking; otherwise you should use IO.blocking (uncancelable) or IO.interruptible (cancelable).

    Alias for IO.delay.

  7. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  8. def async[A](k: ((Either[Throwable, A]) => Unit) => IO[Option[IO[Unit]]]): IO[A]

    Suspends an asynchronous side effect in IO.

    Suspends an asynchronous side effect in IO.

    The given function will be invoked during evaluation of the IO to "schedule" the asynchronous callback, where the callback of type Either[Throwable, A] => Unit is the parameter passed to that function. Only the first invocation of the callback will be effective! All subsequent invocations will be silently dropped.

    The process of registering the callback itself is suspended in IO (the outer IO of IO[Option[IO[Unit]]]).

    The effect returns Option[IO[Unit]] which is an optional finalizer to be run in the event that the fiber running async(k) is canceled.

    For example, here is a simplified version of IO.fromCompletableFuture:

    def fromCompletableFuture[A](fut: IO[CompletableFuture[A]]): IO[A] = {
      fut.flatMap { cf =>
        IO.async { cb =>
          IO {
            //Invoke the callback with the result of the completable future
            val stage = cf.handle[Unit] {
              case (a, null) => cb(Right(a))
              case (_, e) => cb(Left(e))
            }
    
            //Cancel the completable future if the fiber is canceled
            Some(IO(stage.cancel(false)).void)
          }
        }
      }
    }
    See also

    async_ for a simplified variant without a finalizer

  9. implicit def asyncForIO: kernel.Async[IO]
  10. def async_[A](k: ((Either[Throwable, A]) => Unit) => Unit): IO[A]

    Suspends an asynchronous side effect in IO.

    Suspends an asynchronous side effect in IO.

    The given function will be invoked during evaluation of the IO to "schedule" the asynchronous callback, where the callback is the parameter passed to that function. Only the first invocation of the callback will be effective! All subsequent invocations will be silently dropped.

    As a quick example, you can use this function to perform a parallel computation given an ExecutorService:

    def fork[A](body: => A, exc: ExecutorService): IO[A] =
      IO async_ { cb =>
        exc.execute(new Runnable {
          def run() =
            try cb(Right(body)) catch { case t if NonFatal(t) => cb(Left(t)) }
        })
      }

    The fork function will do exactly what it sounds like: take a thunk and an ExecutorService and run that thunk on the thread pool. Or rather, it will produce an IO which will do those things when run; it does *not* schedule the thunk until the resulting IO is run! Note that there is no thread blocking in this implementation; the resulting IO encapsulates the callback in a pure and monadic fashion without using threads.

    This function can be thought of as a safer, lexically-constrained version of Promise, where IO is like a safer, lazy version of Future.

    See also

    async

  11. def blocking[A](thunk: => A): IO[A]

    Intended for thread blocking operations.

    Intended for thread blocking operations. blocking will shift the execution of the blocking operation to a separate threadpool to avoid blocking on the main execution context. See the thread-model documentation for more information on why this is necessary. Note that the created effect will be uncancelable; if you need cancelation then you should use interruptible[A](thunk:=>A):* or interruptibleMany.

    IO.blocking(scala.io.Source.fromFile("path").mkString)
    thunk

    The side effect which is to be suspended in IO and evaluated on a blocking execution context Implements cats.effect.kernel.Sync.blocking.

    Definition Classes
    IOCompanionPlatform
  12. def both[A, B](left: IO[A], right: IO[B]): IO[(A, B)]
  13. def bothOutcome[A, B](left: IO[A], right: IO[B]): IO[(OutcomeIO[A], OutcomeIO[B])]
  14. def bracketFull[A, B](acquire: (Poll[IO]) => IO[A])(use: (A) => IO[B])(release: (A, OutcomeIO[B]) => IO[Unit]): IO[B]
  15. def canceled: IO[Unit]
  16. def cede: IO[Unit]

    Introduces a fairness boundary that yields control back to the scheduler of the runtime system.

    Introduces a fairness boundary that yields control back to the scheduler of the runtime system. This allows the carrier thread to resume execution of another waiting fiber.

    This function is primarily useful when performing long-running computation that is outside of the monadic context. For example:

    fa.map(data => expensiveWork(data))

    In the above, we're assuming that expensiveWork is a function which is entirely compute-bound but very long-running. A good rule of thumb is to consider a function "expensive" when its runtime is around three or more orders of magnitude higher than the overhead of the map function itself (which runs in around 5 nanoseconds on modern hardware). Thus, any expensiveWork function which requires around 10 microseconds or longer to execute should be considered "long-running".

    The danger is that these types of long-running actions outside of the monadic context can result in degraded fairness properties. The solution is to add an explicit cede both before and after the expensive operation:

    (fa <* IO.cede).map(data => expensiveWork(data)).guarantee(IO.cede)

    Note that extremely long-running expensiveWork functions can still cause fairness issues, even when used with cede. This problem is somewhat fundamental to the nature of scheduling such computation on carrier threads. Whenever possible, it is best to break apart any such functions into multiple pieces invoked independently (e.g. via chained map calls) whenever the execution time exceeds five or six orders of magnitude beyond the overhead of map itself (around 1 millisecond on most hardware).

    This operation is not required in most applications, particularly those which are primarily I/O bound, as IO itself will automatically introduce fairness boundaries without requiring user input. These automatic boundaries are controlled by the cats.effect.unsafe.IORuntimeConfig.autoYieldThreshold configuration parameter, which in turn may be adjusted by overriding IOApp.runtimeConfig.

  17. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @native()
  18. implicit def commutativeApplicativeForIOPar: CommutativeApplicative[Par]
  19. implicit val consoleForIO: Console[IO]
  20. def cont[K, R](body: Cont[IO, K, R]): IO[R]

    This is a low-level API which is meant for implementors, please use background, start, async, or Deferred instead, depending on the use case

  21. def defer[A](thunk: => IO[A]): IO[A]

    Suspends a synchronous side effect which produces an IO in IO.

    Suspends a synchronous side effect which produces an IO in IO.

    This is useful for trampolining (i.e. when the side effect is conceptually the allocation of a stack frame). Any exceptions thrown by the side effect will be caught and sequenced into the IO.

  22. def deferred[A]: IO[Deferred[IO, A]]
  23. def delay[A](thunk: => A): IO[A]

    Suspends a synchronous side effect in IO.

    Suspends a synchronous side effect in IO. Use IO.delay if your side effect is not thread-blocking; otherwise you should use IO.blocking (uncancelable) or IO.interruptible (cancelable).

    Any exceptions thrown by the effect will be caught and sequenced into the IO.

  24. implicit val envForIO: Env[IO]
  25. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  26. def equals(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef → Any
  27. def eval[A](fa: Eval[A]): IO[A]

    Lifts an Eval into IO.

    Lifts an Eval into IO.

    This function will preserve the evaluation semantics of any actions that are lifted into the pure IO. Eager Eval instances will be converted into thunk-less IO (i.e. eager IO), while lazy eval and memoized will be executed as such.

  28. def executionContext: IO[ExecutionContext]
  29. def executor: IO[Executor]
  30. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable])
  31. def fromCompletableFuture[A](fut: IO[CompletableFuture[A]]): IO[A]
    Definition Classes
    IOCompanionPlatform
  32. def fromCompletionStage[A](completionStage: IO[CompletionStage[A]]): IO[A]
    Definition Classes
    IOCompanionPlatform
  33. def fromEither[A](e: Either[Throwable, A]): IO[A]

    Lifts an Either[Throwable, A] into the IO[A] context, raising the throwable if it exists.

  34. def fromFuture[A](fut: IO[Future[A]]): IO[A]

    Constructs an IO which evaluates the given Future and produces the result (or failure).

    Constructs an IO which evaluates the given Future and produces the result (or failure).

    Because Future eagerly evaluates, as well as because it memoizes, this function takes its parameter as an IO, which could be lazily evaluated. If this laziness is appropriately threaded back to the definition site of the Future, it ensures that the computation is fully managed by IO and thus referentially transparent.

    Example:

    // Lazy evaluation, equivalent with by-name params
    IO.fromFuture(IO(f))
    
    // Eager evaluation, for pure futures
    IO.fromFuture(IO.pure(f))

    Roughly speaking, the following identities hold:

    IO.fromFuture(IO(f)).unsafeToFuture() === f // true-ish (except for memoization)
    IO.fromFuture(IO(ioa.unsafeToFuture())) === ioa // true
    See also

    IO#unsafeToFuture

  35. def fromOption[A](o: Option[A])(orElse: => Throwable): IO[A]

    Lifts an Option[A] into the IO[A] context, raising the throwable if the option is empty.

  36. def fromTry[A](t: Try[A]): IO[A]

    Lifts an Try[A] into the IO[A] context, raising the throwable if it exists.

  37. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  38. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  39. def interruptible[A](thunk: => A): IO[A]

    Like blocking but will attempt to abort the blocking operation using thread interrupts in the event of cancelation.

    Like blocking but will attempt to abort the blocking operation using thread interrupts in the event of cancelation. The interrupt will be attempted only once.

    Note the following tradeoffs:

    • this has slightly more overhead than blocking due to the machinery necessary for the interrupt coordination,
    • thread interrupts are very often poorly considered by Java (and Scala!) library authors, and it is possible for interrupts to result in resource leaks or invalid states. It is important to be certain that this will not be the case before using this mechanism.
    thunk

    The side effect which is to be suspended in IO and evaluated on a blocking execution context Implements cats.effect.kernel.Sync.interruptible[A](thunk:=>A):*

    Definition Classes
    IOCompanionPlatform
  40. def interruptibleMany[A](thunk: => A): IO[A]

    Like blocking but will attempt to abort the blocking operation using thread interrupts in the event of cancelation.

    Like blocking but will attempt to abort the blocking operation using thread interrupts in the event of cancelation. The interrupt will be attempted repeatedly until the blocking operation completes or exits.

    Note the following tradeoffs:

    • this has slightly more overhead than blocking due to the machinery necessary for the interrupt coordination,
    • thread interrupts are very often poorly considered by Java (and Scala!) library authors, and it is possible for interrupts to result in resource leaks or invalid states. It is important to be certain that this will not be the case before using this mechanism.
    thunk

    The side effect which is to be suspended in IO and evaluated on a blocking execution context Implements cats.effect.kernel.Sync!.interruptibleMany

    Definition Classes
    IOCompanionPlatform
  41. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  42. implicit def monoidForIO[A](implicit arg0: Monoid[A]): Monoid[IO[A]]
  43. def monotonic: IO[FiniteDuration]
  44. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  45. def never[A]: IO[A]

    A non-terminating IO, alias for async(_ => ()).

  46. def none[A]: IO[Option[A]]

    An IO that contains an empty Option.

    An IO that contains an empty Option.

    See also

    some for the non-empty Option variant

  47. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  48. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  49. def parReplicateAN[A](n: Int)(replicas: Int, ma: IO[A]): IO[List[A]]

    Like Parallel.parReplicateA, but limits the degree of parallelism.

  50. def parSequenceN[T[_], A](n: Int)(tma: T[IO[A]])(implicit arg0: Traverse[T]): IO[T[A]]

    Like Parallel.parSequence, but limits the degree of parallelism.

  51. def parTraverseN[T[_], A, B](n: Int)(ta: T[A])(f: (A) => IO[B])(implicit arg0: Traverse[T]): IO[T[B]]

    Like Parallel.parTraverse, but limits the degree of parallelism.

  52. implicit def parallelForIO: Aux[IO, Par]
  53. def print[A](a: A)(implicit S: Show[A] = Show.fromToString[A]): IO[Unit]

    Prints a value to the standard output using the implicit cats.Show instance.

    Prints a value to the standard output using the implicit cats.Show instance.

    a

    value to be printed to the standard output

    See also

    cats.effect.std.Console for more standard input, output and error operations

  54. def println[A](a: A)(implicit S: Show[A] = Show.fromToString[A]): IO[Unit]

    Prints a value to the standard output followed by a new line using the implicit cats.Show instance.

    Prints a value to the standard output followed by a new line using the implicit cats.Show instance.

    a

    value to be printed to the standard output

    See also

    cats.effect.std.Console for more standard input, output and error operations

  55. def pure[A](value: A): IO[A]

    Lifts a pure value into IO.

    Lifts a pure value into IO.

    This should only be used if the value in question has "already" been computed! In other words, something like IO.pure(readLine) is most definitely not the right thing to do! However, IO.pure(42) is correct and will be more efficient (when evaluated) than IO(42), due to avoiding the allocation of extra thunks.

  56. def race[A, B](left: IO[A], right: IO[B]): IO[Either[A, B]]

    Run two IO tasks concurrently, and return the first to finish, either in success or error.

    Run two IO tasks concurrently, and return the first to finish, either in success or error. The loser of the race is canceled.

    The two tasks are executed in parallel, the winner being the first that signals a result.

    As an example see IO.timeout and IO.timeoutTo

    Also see racePair for a version that does not cancel the loser automatically on successful results.

    left

    is the "left" task participating in the race

    right

    is the "right" task participating in the race

  57. def racePair[A, B](left: IO[A], right: IO[B]): IO[Either[(OutcomeIO[A], FiberIO[B]), (FiberIO[A], OutcomeIO[B])]]

    Run two IO tasks concurrently, and returns a pair containing both the winner's successful value and the loser represented as a still-unfinished task.

    Run two IO tasks concurrently, and returns a pair containing both the winner's successful value and the loser represented as a still-unfinished task.

    On usage the user has the option of canceling the losing task, this being equivalent with plain race:

    val ioA: IO[A] = ???
    val ioB: IO[B] = ???
    
    IO.racePair(ioA, ioB).flatMap {
      case Left((a, fiberB)) =>
        fiberB.cancel.as(a)
      case Right((fiberA, b)) =>
        fiberA.cancel.as(b)
    }

    See race for a simpler version that cancels the loser immediately.

    left

    is the "left" task participating in the race

    right

    is the "right" task participating in the race

  58. def raiseError[A](t: Throwable): IO[A]

    Constructs an IO which sequences the specified exception.

    Constructs an IO which sequences the specified exception.

    If this IO is run using unsafeRunSync or unsafeRunTimed, the exception will be thrown. This exception can be "caught" (or rather, materialized into value-space) using the attempt method.

    See also

    IO#attempt

  59. def raiseUnless(cond: Boolean)(e: => Throwable): IO[Unit]

    Returns raiseError when cond is false, otherwise IO.unit

    Returns raiseError when cond is false, otherwise IO.unit

    Example:
    1. val tooMany = 5
      val x: Int = ???
      IO.raiseUnless(x < tooMany)(new IllegalArgumentException("Too many"))
  60. def raiseWhen(cond: Boolean)(e: => Throwable): IO[Unit]

    Returns raiseError when the cond is true, otherwise IO.unit

    Returns raiseError when the cond is true, otherwise IO.unit

    Example:
    1. val tooMany = 5
      val x: Int = ???
      IO.raiseWhen(x >= tooMany)(new IllegalArgumentException("Too many"))
  61. def randomUUID: IO[UUID]

    returns

    a randomly-generated UUID This is equivalent to UUIDGen[IO].randomUUID, just provided as a method for convenience

  62. def readLine: IO[String]

    Reads a line as a string from the standard input using the platform's default charset, as per java.nio.charset.Charset.defaultCharset().

    Reads a line as a string from the standard input using the platform's default charset, as per java.nio.charset.Charset.defaultCharset().

    The effect can raise a java.io.EOFException if no input has been consumed before the EOF is observed. This should never happen with the standard input, unless it has been replaced with a finite java.io.InputStream through java.lang.System#setIn or similar.

    returns

    an IO effect that describes reading the user's input from the standard input as a string

    Definition Classes
    IOCompanionPlatform
    See also

    cats.effect.std.Console#readLineWithCharset for reading using a custom java.nio.charset.Charset

  63. def realTime: IO[FiniteDuration]
  64. def realTimeInstant: IO[Instant]
    Definition Classes
    IOCompanionPlatform
  65. def ref[A](a: A): IO[Ref[IO, A]]
  66. implicit def semigroupForIO[A](implicit arg0: Semigroup[A]): Semigroup[IO[A]]
    Definition Classes
    IOLowPriorityImplicits
  67. implicit val semigroupKForIO: SemigroupK[IO]
  68. implicit def showForIO[A](implicit arg0: Show[A]): Show[IO[A]]
  69. implicit def showForIONoPure[A]: Show[IO[A]]
    Definition Classes
    IOLowPriorityImplicits
  70. def sleep(finiteDelay: FiniteDuration): IO[Unit]
  71. def sleep(delay: Duration): IO[Unit]

    Creates an asynchronous task that on evaluation sleeps for the specified duration, emitting a notification on completion.

    Creates an asynchronous task that on evaluation sleeps for the specified duration, emitting a notification on completion.

    This is the pure, non-blocking equivalent to:

    • Thread.sleep (JVM)
    • ScheduledExecutorService.schedule (JVM)
    • setTimeout (JavaScript)

    You can combine it with flatMap to create delayed tasks:

    val timeout = IO.sleep(10.seconds).flatMap { _ =>
      IO.raiseError(new TimeoutException)
    }

    The created task is cancelable and so it can be used safely in race conditions without resource leakage.

    delay

    the time span to wait before emitting the tick

    returns

    a new asynchronous and cancelable IO that will sleep for the specified duration and then finally emit a tick

  72. def some[A](a: A): IO[Option[A]]

    An IO that contains some Option of the given value.

    An IO that contains some Option of the given value.

    See also

    none for the empty Option variant

  73. def stub: IO[Nothing]
  74. def suspend[A](hint: Type)(thunk: => A): IO[A]
    Definition Classes
    IOCompanionPlatform
  75. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  76. def toString(): String
    Definition Classes
    AnyRef → Any
  77. def trace: IO[Trace]
  78. def uncancelable[A](body: (Poll[IO]) => IO[A]): IO[A]
  79. def unique: IO[Token]
  80. def unit: IO[Unit]

    Alias for IO.pure(()).

  81. def unlessA(cond: Boolean)(action: => IO[Unit]): IO[Unit]

    Returns the given argument if cond is false, otherwise IO.Unit

    Returns the given argument if cond is false, otherwise IO.Unit

    See also

    IO.whenA for the inverse

    IO.raiseWhen for conditionally raising an error

  82. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  83. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  84. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException]) @native()
  85. def whenA(cond: Boolean)(action: => IO[Unit]): IO[Unit]

    Returns the given argument if cond is true, otherwise IO.Unit

    Returns the given argument if cond is true, otherwise IO.Unit

    See also

    IO.unlessA for the inverse

    IO.raiseWhen for conditionally raising an error

Deprecated Value Members

  1. def interruptible[A](many: Boolean, thunk: => A): IO[A]
    Definition Classes
    IOCompanionPlatform
    Annotations
    @deprecated
    Deprecated

    (Since version 3.3.0) use interruptible / interruptibleMany instead

Inherited from Serializable

Inherited from IOLowPriorityImplicits

Inherited from IOCompanionPlatform

Inherited from AnyRef

Inherited from Any

Ungrouped