- Companion
- class
Type members
Inherited classlikes
Types
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
.
Helpers are provided for converting back and forth in Par.apply
for wrapping any IO
value and Par.unwrap
for unwrapping.
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
Concrete methods
Suspends a synchronous side effect in IO
.
Suspends a synchronous side effect in IO
.
Alias for IO.delay(body)
.
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 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
This is a low-level API which is meant for implementors,
please use background
, start
, async
, or Deferred
instead,
depending on the use case
This is a low-level API which is meant for implementors,
please use background
, start
, async
, or Deferred
instead,
depending on the use case
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
.
Suspends a synchronous side effect in IO
.
Suspends a synchronous side effect in IO
.
Any exceptions thrown by the effect will be caught and sequenced
into the IO
.
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.
Lifts an Either[Throwable, A]
into the IO[A]
context, raising
the throwable if it exists.
Lifts an Either[Throwable, A]
into the IO[A]
context, raising
the throwable if it exists.
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
Lifts an Option[A]
into the IO[A]
context, raising the throwable if the option is empty.
Lifts an Option[A]
into the IO[A]
context, raising the throwable if the option is empty.
Lifts an Try[A]
into the IO[A]
context, raising the throwable if it
exists.
Lifts an Try[A]
into the IO[A]
context, raising the throwable if it
exists.
An IO that contains an empty Option.
An IO that contains an empty Option.
- See also
some for the non-empty Option variant
Like Parallel.parSequence
, but limits the degree of parallelism.
Like Parallel.parSequence
, but limits the degree of parallelism.
Like Parallel.parTraverse
, but limits the degree of parallelism.
Like Parallel.parTraverse
, but limits the degree of parallelism.
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.
- Value Params
- a
value to be printed to the standard output
- See also
cats.effect.std.Console
for more standard input, output and error operations
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.
- Value Params
- a
value to be printed to the standard output
- See also
cats.effect.std.Console
for more standard input, output and error operations
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.
Run two IO tasks concurrently, and return the first to finish, either in success or error. The loser of the race is canceled.
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.
- Value Params
- lh
is the "left" task participating in the race
- rh
is the "right" task participating in the race
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.
If the first task completes in error, then the result will complete in error, the other task being canceled.
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.map(_ => a)
case Right((fiberA, b)) =>
fiberA.cancel.map(_ => b)
}
See race for a simpler version that cancels the loser immediately.
- Value Params
- lh
is the "left" task participating in the race
- rh
is the "right" task participating in the race
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
Returns raiseError
when cond
is false, otherwise IO.unit
Returns raiseError
when cond
is false, otherwise IO.unit
- Example
val tooMany = 5 val x: Int = ??? IO.raiseUnless(x < tooMany)(new IllegalArgumentException("Too many"))
Returns raiseError
when the cond
is true, otherwise IO.unit
Returns raiseError
when the cond
is true, otherwise IO.unit
- Example
val tooMany = 5 val x: Int = ??? IO.raiseWhen(x >= tooMany)(new IllegalArgumentException("Too many"))
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
- See also
cats.effect.std.Console#readLineWithCharset
for reading using a customjava.nio.charset.Charset
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.
- Value Params
- duration
is 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
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
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
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