cats.effect.kernel

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.

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.

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:

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.

==Cancellation==

MonadCancel introduces a simple means of cancellation, particularly
self-cancellation, where a fiber can request the abnormal termination of its
own execution. This is achieved by calling
canceled.

GenSpawn expands on the cancellation model described by MonadCancel
by introducing a means of external cancellation. With external cancellation,
a fiber can request the abnormal termination of another fiber by calling
Fiber!.cancel.

The cancellation model dictates that external cancellation behaves
identically to self-cancellation. To guarantee consistent behavior between
the two, the following semantics are shared:

External cancellation contrasts with self-cancellation in one aspect: the
former may require synchronization between multiple threads to communicate
a cancellation request. As a result, cancellation may not be immediately
observed by a fiber. Implementations are free to decide how and when this
synchronization takes place.

==Cancellation safety==

A function or effect is considered to be cancellation-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 cancellation-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:

==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:

Additionally, a fiber may never produce an outcome, in which case it is said
to be non-terminating.

==Cancellation==

Cancellation refers to the act of requesting that the execution of a fiber
be abnormally terminated. MonadCancel exposes a means of
self-cancellation, with which a fiber can request that its own execution
be terminated. Self-cancellation is achieved via
canceled.

Cancellation is vaguely similar to the short-circuiting behavior introduced
by MonadError, but there are several key differences:

==Masking==

Masking allows a fiber to suppress cancellation for a period of time, which
is achieved via uncancelable. If a fiber is
canceled while it is masked, the cancellation is suppressed for as long as
the fiber remains masked. Once the fiber reaches a completely unmasked
state, it responds to the cancellation.

While a fiber is masked, it may optionally unmask by "polling", rendering
itself cancelable again.

{{{

F.uncancelable { poll =>
// can only observe cancellation 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
cancellation. Finalizers are those effects whose evaluation is guaranteed
in the event of cancellation. 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
cancellation. 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.

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.

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.