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.

Suspends an asynchronous side effect in IO.

The given function k 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)
      }
    }
  }
}

Suspends an asynchronous side effect with optional immediate result in IO.

The given function k will be invoked during evaluation of the IO to:

• check if result is already available;
• "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[Either[Option[IO[Unit]], A]]).

The effect returns Either[Option[IO[Unit]], A] where:

• right side A is an immediate result of computation (callback invocation will be dropped);
• left side Option[IO[Unit]] is an optional finalizer to be run in the event that the fiber running asyncCheckAttempt(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.asyncCheckAttempt { cb =>
      if (cf.isDone) {
        //Register immediately available result of the completable future or handle an error
        IO(cf.get)
          .map(Right(_))
          .handleError { e =>
            cb(Left(e))
            Left(None)
          }
      } else {
        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
          Left(Some(IO(stage.cancel(false)).void))
        }
      }
    }
  }
}

Note that asyncCheckAttempt is uncancelable during its registration.

Suspends an asynchronous side effect in IO.

The given function k 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.

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)

An effect that requests self-cancelation on the current fiber.

canceled has a return type of IO[Unit] instead of IO[Nothing] due to execution continuing in a masked region. In the following example, the fiber requests self-cancelation in a masked region, so cancelation is suppressed until the fiber is completely unmasked. fa will run but fb will not. If canceled had a return type of IO[Nothing], then it would not be possible to continue execution to fa (there would be no Nothing value to pass to the flatMap).

IO.uncancelable { _ =>
  IO.canceled *> fa
} *> fb

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.

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.

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.

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.

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

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.

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.

An IO that contains an empty Option.

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

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

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.

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.

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.

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.

Returns raiseError when cond is false, otherwise IO.unit

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

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.

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.

An IO that contains some Option of the given value.

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

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