cats.effect.kernel
Type members
Classlikes
A typeclass that encodes the notion of suspending asynchronous
side effects in the F[_]
context
A typeclass that encodes the notion of suspending asynchronous
side effects in the F[_]
context
An asynchronous task is one whose results are computed somewhere else (eg by a scala.concurrent.Future running on some other threadpool). We await the results of that execution by giving it a callback to be invoked with the result.
That computation may fail hence the callback is of type
Either[Throwable, A] => ()
. This awaiting is semantic only - no threads are
blocked, the current fiber is simply descheduled until the callback completes.
This leads us directly to the simplest asynchronous FFI
def async_[A](k: (Either[Throwable, A] => Unit) => Unit): F[A]
async(k)
is semantically blocked until the callback is invoked.
async_
is somewhat contrained however. We can't perform any F[_]
effects
in the process of registering the callback and we also can't register
a finalizer to eg cancel the asynchronous task in the event that the fiber
running async_
is canceled.
This leads us directly to the more general asynchronous FFI
def async[A](k: (Either[Throwable, A] => Unit) => F[Option[F[Unit]]]): F[A]
As evidenced by the type signature, k
may perform F[_]
effects and it returns
an Option[F[Unit]]
which is an optional finalizer to be run in the event that
the fiber running
async(k)
is canceled.
async(k) }}}
async(k) }}}
async_
is somewhat contrained however. We can't perform any F[_]
effects
in the process of registering the callback and we also can't register
a finalizer to eg cancel the asynchronous task in the event that the fiber
running async_
is canceled.
This leads us directly to the more general asynchronous FFI
def async[A](k: (Either[Throwable, A] => Unit) => F[Option[F[Unit]]]): F[A]
As evidenced by the type signature, k
may perform F[_]
effects and it returns
an Option[F[Unit]]
which is an optional finalizer to be run in the event that
the fiber running
async(k)
is canceled.
async(k) }}}
- Companion
- object
A typeclass which encodes various notions of time. Analogous to some of the time functions exposed by java.lang.System.
A typeclass which encodes various notions of time. Analogous to some of the time functions exposed by java.lang.System.
- Companion
- object
This construction supports Async.cont
This construction supports Async.cont
trait Async[F[_]] {
...
def cont[A](body: Cont[F, A]): F[A]
}
It's a low level operation meant for implementors, end users
should use async
, start
or Deferred
instead, depending on
the use case.
It can be understood as providing an operation to resume an F
asynchronously, of type Either[Throwable, A] => Unit
, and an
(interruptible) operation to semantically block until resumption,
of type F[A]
. We will refer to the former as resume
, and the
latter as get
.
These two operations capture the essence of semantic blocking, and
can be used to build async
, which in turn can be used to build
Fiber
, start
, Deferred
and so on.
Refer to the default implementation to Async[F].async
for an
example of usage.
The reason for the shape of the Cont
construction in Async[F].cont
,
as opposed to simply:
trait Async[F[_]] {
...
def cont[A]: F[(Either[Throwable, A] => Unit, F[A])]
}
is that it's not safe to use concurrent operations such as get.start
.
The Cont
encoding therefore simulates higher-rank polymorphism
to ensure that you can not call start
on get
, but only use
operations up to MonadCancel
(flatMap
, onCancel
, uncancelable
, etc).
If you are an implementor, and you have an implementation of async
but not cont
,
you can override Async[F].async
with your implementation, and use Async.defaultCont
to implement Async[F].cont
.
A purely functional synchronization primitive which represents a single value which may not yet be available.
A purely functional synchronization primitive which represents a single value which may not yet be available.
When created, a Deferred
is empty. It can then be completed exactly once,
and never be made empty again.
get
on an empty Deferred
will block until the Deferred
is completed.
get
on a completed Deferred
will always immediately return its content.
complete(a)
on an empty Deferred
will set it to a
, and notify any and
all readers currently blocked on a call to get
.
complete(a)
on a Deferred
that has already been completed will not modify
its content, and result in a failed F
.
Albeit simple, Deferred
can be used in conjunction with Ref to build
complex concurrent behaviour and data structures like queues and semaphores.
Finally, the blocking mentioned above is semantic only, no actual threads are blocked by the implementation.
- Companion
- object
A datatype that represents a handle to a fiber and allows for waiting and cancelation against that fiber.
A datatype that represents a handle to a fiber and allows for waiting and cancelation against that fiber.
- See also
GenSpawn documentation for more detailed information on the concurrency of fibers.
A typeclass that characterizes monads which support spawning and racing of fibers. GenSpawn extends the capabilities of MonadCancel, so an instance of this typeclass must also provide a lawful instance for MonadCancel.
A typeclass that characterizes monads which support spawning and racing of fibers. GenSpawn extends the capabilities of MonadCancel, so an instance of this typeclass must also provide a lawful instance for MonadCancel.
This documentation builds upon concepts introduced in the MonadCancel documentation.
==Concurrency==
GenSpawn introduces a notion of concurrency that enables fibers to safely interact with each other via three special functions. start spawns a fiber that executes concurrently with the spawning fiber. join semantically blocks the joining fiber until the joinee fiber terminates, after which the outcome of the joinee is returned. cancel requests a fiber to abnormally terminate, and semantically blocks the canceller until the cancellee has completed finalization.
Just like threads, fibers can execute concurrently with respect to each other. This means that the effects of independent fibers may be interleaved nondeterministically. This mode of concurrency reaps benefits for modular program design; fibers that are described separately can execute simultaneously without requiring programmers to explicitly yield back to the runtime system.
The interleaving of effects is illustrated in the following program:
for {
fa <- (println("A1") *> println("A2")).start
fb <- (println("B1") *> println("B2")).start
} yield ()
In this program, two fibers A and B are spawned concurrently. There are six possible executions, each of which exhibits a different ordering of effects. The observed output of each execution is shown below:
- A1, A2, B1, B2
- A1, B1, A2, B2
- A1, B1, B2, A2
- B1, B2, A1, A2
- B1, A1, B2, A2
- B1, A1, A2, B3
Notice how every execution preserves sequential consistency of the effects
within each fiber: A1
always prints before A2
, and B1
always prints
before B2
. However, there are no guarantees around how the effects of
both fibers will be ordered with respect to each other; it is entirely
nondeterministic.
==Cancelation==
MonadCancel introduces a simple means of cancelation, particularly self-cancelation, where a fiber can request the abnormal termination of its own execution. This is achieved by calling canceled.
GenSpawn expands on the cancelation model described by MonadCancel by introducing a means of external cancelation. With external cancelation, a fiber can request the abnormal termination of another fiber by calling Fiber!.cancel.
The cancelation model dictates that external cancelation behaves identically to self-cancelation. To guarantee consistent behavior between the two, the following semantics are shared:
- Masking: if a fiber is canceled while it is masked, cancelation is suppressed until it reaches a completely unmasked state. See MonadCancel documentation for more details.
- Backpressure: cancel semantically blocks all callers until finalization is complete.
- Idempotency: once a fiber's cancelation has been requested, subsequent cancelations have no effect on cancelation status.
- Terminal: Cancelation of a fiber that has terminated immediately returns.
External cancelation contrasts with self-cancelation in one aspect: the former may require synchronization between multiple threads to communicate a cancelation request. As a result, cancelation may not be immediately observed by a fiber. Implementations are free to decide how and when this synchronization takes place.
==Cancelation safety==
A function or effect is considered to be cancelation-safe if it can be run in the absence of masking without violating effectful lifecycles or leaking resources. These functions require extra attention and care from users to ensure safe usage.
start and racePair are both considered to be cancelation-unsafe effects because they return a Fiber, which is a resource that has a lifecycle.
// Start a fiber that continuously prints "A".
// After 10 seconds, cancel the fiber.
F.start(F.delay(println("A")).foreverM).flatMap { fiber =>
F.sleep(10.seconds) *> fiber.cancel
}
In the above example, imagine the spawning fiber is canceled after it starts the printing fiber, but before the latter is canceled. In this situation, the printing fiber is not canceled and will continue executing forever, contending with other fibers for system resources. Fiber leaks like this typically happen because some fiber that holds a reference to a child fiber is canceled before the child terminates; like threads, fibers will not automatically be cleaned up.
Resource leaks like this are unfavorable when writing applications. In the case of start and racePair, it is recommended not to use these methods; instead, use background and race respectively.
The following example depicts a safer version of the start example above:
// Starts a fiber that continously prints "A".
// After 10 seconds, the resource scope exits so the fiber is canceled.
F.background(F.delay(println("A")).foreverM).use { _ =>
F.sleep(10.seconds)
}
==Scheduling==
Fibers are commonly referred to as ''lightweight threads'' or ''green threads''. This alludes to the nature by which fibers are scheduled by runtime systems: many fibers are multiplexed onto one or more native threads.
For applications running on the JVM, the scheduler typically manages a thread pool onto which fibers are scheduled. These fibers are executed simultaneously by the threads in the pool, achieving both concurrency and parallelism. For applications running on JavaScript platforms, all compute is restricted to a single worker thread, so multiple fibers must share that worker thread (dictated by fairness properties), achieving concurrency without parallelism.
cede is a special function that interacts directly with the underlying scheduler. It is a means of cooperative multitasking by which a fiber signals to the runtime system that it intends to pause execution and resume at some later time at the discretion of the scheduler. This is in contrast to preemptive multitasking, in which threads of control are forcibly yielded after a well-defined time slice.
Preemptive and cooperative multitasking are both features of runtime systems that influence the fairness and throughput properties of an application. These modes of scheduling are not necessarily mutually exclusive: a runtime system may incorporate a blend of the two, where fibers can explicitly yield back to the scheduler, but the runtime preempts a fiber if it has not yielded for some time.
For more details on schedulers, see the following resources:
- Companion
- object
A typeclass that encodes the notion of suspending fibers for
a given duration. Analogous to Thread.sleep
but is
only semantically blocking rather than blocking an underlying
OS pthread.
A typeclass that encodes the notion of suspending fibers for
a given duration. Analogous to Thread.sleep
but is
only semantically blocking rather than blocking an underlying
OS pthread.
- Companion
- object
A typeclass that characterizes monads which support safe cancelation, masking, and finalization. MonadCancel extends the capabilities of cats.MonadError, so an instance of this typeclass must also provide a lawful instance for cats.MonadError.
A typeclass that characterizes monads which support safe cancelation, masking, and finalization. MonadCancel extends the capabilities of cats.MonadError, so an instance of this typeclass must also provide a lawful instance for cats.MonadError.
==Fibers==
A fiber is a sequence of effects which are bound together by flatMap.
The execution of a fiber of an effect F[E, A]
terminates with one of three
outcomes, which are encoded by the datatype Outcome:
- Outcome.Succeeded: indicates success with a value of type
A
- Outcome.Errored: indicates failure with a value of type
E
- Outcome.Canceled: indicates abnormal termination
Additionally, a fiber may never produce an outcome, in which case it is said to be non-terminating.
==Cancelation==
Cancelation refers to the act of requesting that the execution of a fiber be abnormally terminated. MonadCancel exposes a means of self-cancelation, with which a fiber can request that its own execution be terminated. Self-cancelation is achieved via canceled.
Cancelation is vaguely similar to the short-circuiting behavior introduced by cats.MonadError, but there are several key differences:
- Cancelation is effective; if it is observed it must be respected, and it cannot be reversed. In contrast, handleError exposes the ability to catch and recover from errors, and then proceed with normal execution.
- Cancelation can be masked via MonadCancel!.uncancelable. Masking is discussed in the next section.
- GenSpawn introduces external cancelation, another cancelation mechanism by which fibers can be canceled by external parties.
==Masking==
Masking allows a fiber to suppress cancelation for a period of time, which is achieved via uncancelable. If a fiber is canceled while it is masked, the cancelation is suppressed for as long as the fiber remains masked. Once the fiber reaches a completely unmasked state, it responds to the cancelation.
While a fiber is masked, it may optionally unmask by "polling", rendering itself cancelable again.
F.uncancelable { poll =>
// can only observe cancelation within `fb`
fa *> poll(fb) *> fc
}
These semantics allow users to precisely mark what regions of code are cancelable within a larger code block.
==Finalization==
Finalization refers to the act of running finalizers in response to a
cancelation. Finalizers are those effects whose evaluation is guaranteed
in the event of cancelation. After a fiber has completed finalization,
it terminates with an outcome of Canceled
.
Finalizers can be registered to a fiber for the duration of some effect via onCancel. If a fiber is canceled while running that effect, the registered finalizer is guaranteed to be run before terminating.
==Bracket pattern==
The aforementioned concepts work together to unlock a powerful pattern for safely interacting with effectful lifecycles: the bracket pattern. This is analogous to the try-with-resources/finally construct in Java.
A lifecycle refers to a pair of actions, which are called the acquisition action and the release action respectively. The relationship between these two actions is that if the former completes successfully, then the latter is guaranteed to be run eventually, even in the presence of errors and cancelation. While the lifecycle is active, other work can be performed, but this invariant is always respected.
The bracket pattern is an invaluable tool for safely handling resource lifecycles. Imagine an application that opens network connections to a database server to do work. If a task in the application is canceled while it holds an open database connection, the connection would never be released or returned to a pool, causing a resource leak.
To illustrate the compositional nature of MonadCancel and its combinators, the implementation of bracket is shown below:
def bracket[A, B](acquire: F[A])(use: A => F[B])(release: A => F[Unit]): F[B] =
uncancelable { poll =>
flatMap(acquire) { a =>
val finalized = onCancel(poll(use(a)), release(a).uncancelable)
val handled = onError(finalized) { case e => void(attempt(release(a).uncancelable)) }
flatMap(handled)(b => as(attempt(release(a).uncancelable), b))
}
}
See bracketCase and bracketFull for other variants of the bracket pattern. If more specialized behavior is necessary, it is recommended to use uncancelable and onCancel directly.
- Companion
- object
An asynchronous, concurrent mutable reference.
An asynchronous, concurrent mutable reference.
Provides safe concurrent access and modification of its content, but no
functionality for synchronisation, which is instead handled by Deferred.
For this reason, a Ref
is always initialised to a value.
The default implementation is nonblocking and lightweight, consisting essentially
of a purely functional wrapper over an AtomicReference
.
- Companion
- object
Resource
is a data structure which encodes the idea of executing
an action which has an associated finalizer that needs to be run
when the action completes.
Resource
is a data structure which encodes the idea of executing
an action which has an associated finalizer that needs to be run
when the action completes.
Examples include scarce resources like files, which need to be closed after use, or concurrent abstractions like locks, which need to be released after having been acquired.
There are several constructors to allocate a resource, the most common is make:
def open(file: File): Resource[IO, BufferedReader] = {
val openFile = IO(new BufferedReader(new FileReader(file)))
Resource.make(acquire = openFile)(release = f => IO(f.close))
}
and several methods to consume a resource, the most common is use:
def readFile(file: BufferedReader): IO[Content]
open(file1).use(readFile)
Finalisation (in this case file closure) happens when the action
passed to use
terminates. Therefore, the code above is not
equivalent to:
open(file1).use(IO.pure).flatMap(readFile)
which will instead result in an error, since the file gets closed after
pure
, meaning that .readFile
will then fail.
Also note that a new resource is allocated every time use
is called,
so the following code opens and closes the resource twice:
val file: Resource[IO, File]
file.use(read) >> file.use(read)
If you want sharing, pass the result of allocating the resource
around, and call use
once.
file.use { file => read(file) >> read(file) }
The acquire and release actions passed to make
are not
interruptible, and release will run when the action passed to use
succeeds, fails, or is interrupted. You can use makeCase
to specify a different release logic depending on each of the three
outcomes above.
It is also possible to specify an interruptible acquire though makeFull but be warned that this is an advanced concurrency operation, which requires some care.
Resource usage nests:
open(file1).use { in1 =>
open(file2).use { in2 =>
readFiles(in1, in2)
}
}
However, it is more idiomatic to compose multiple resources
together before use
, exploiting the fact that Resource
forms a
Monad
, and therefore that resources can be nested through
flatMap
.
Nested resources are released in reverse order of acquisition.
Outer resources are released even if an inner use or release fails.
def mkResource(s: String) = {
val acquire = IO(println(s"Acquiring $$s")) *> IO.pure(s)
def release(s: String) = IO(println(s"Releasing $$s"))
Resource.make(acquire)(release)
}
val r = for {
outer <- mkResource("outer")
inner <- mkResource("inner")
} yield (outer, inner)
r.use { case (a, b) =>
IO(println(s"Using $$a and $$b"))
}
On evaluation the above prints:
Acquiring outer
Acquiring inner
Using outer and inner
Releasing inner
Releasing outer
A Resource
can also lift arbitrary actions that don't require
finalisation through eval. Actions passed to
eval
preserve their interruptibility.
Finally, Resource
partakes in other abstractions such as
MonadError
, Parallel
, and Monoid
, so make sure to explore
those instances as well as the other methods not covered here.
Resource
is encoded as a data structure, an ADT, described by the
following node types:
Normally users don't need to care about these node types, unless
conversions from Resource
into something else is needed (e.g.
conversion from Resource
into a streaming data type), in which
case they can be interpreted through pattern matching.
- Type Params
- A
the type of resource
- F
the effect type in which the resource is allocated and released
- Companion
- object
A typeclass that encodes the notion of suspending synchronous
side effects in the F[_]
context
A typeclass that encodes the notion of suspending synchronous
side effects in the F[_]
context
- Companion
- object