cats.effect.std
package cats.effect.std
Type members
Classlikes
Effect type agnostic
the standard console. Suited only for extremely simple console input and
output.
Console with common methods to write to and read fromthe standard console. Suited only for extremely simple console input and
output.
- Example
- {{{
import cats.effect.std.Console
import cats.effect.kernel.Sync
import cats.syntax.all._
implicit val console = Console.sync[F]
def myProgram[F[_] : Console]: F[Unit] =
for {
_ <- Console[F] .println("Please enter your name: ")
n <- Console[F] .readLine
_ <- if (n.nonEmpty) Console[F] .println(s"Hello $n!")
else Console[F] .errorln("Name is empty!")
} yield ()
}}} - Companion
- object
See https://typelevel.org/blog/2020/10/30/concurrency-in-ce3.html
for a walkthrough of building something like this
for a walkthrough of building something like this
- Companion
- object
A synchronization abstraction that allows a set of fibers
to wait until they all reach a certain point.
to wait until they all reach a certain point.
A cyclic barrier is initialized with a positive integer capacity n and
a fiber waits by calling await, at which point it is semantically
blocked until a total of n fibers are blocked on the same cyclic barrier.
a fiber waits by calling await, at which point it is semantically
blocked until a total of n fibers are blocked on the same cyclic barrier.
At this point all the fibers are unblocked and the cyclic barrier is reset,
allowing it to be used again.
allowing it to be used again.
- Companion
- object
A fiber-based supervisor utility for evaluating effects across an impure
boundary. This is useful when working with reactive interfaces that produce
potentially many values (as opposed to one), and for each value, some effect
in
boundary. This is useful when working with reactive interfaces that produce
potentially many values (as opposed to one), and for each value, some effect
in
F must be performed (like inserting it into a queue).Dispatcher is a kind of Supervisor and accordingly follows the same
scoping and lifecycle rules with respect to submitted effects.
scoping and lifecycle rules with respect to submitted effects.
Performance note: all clients of a single Dispatcher instance will
contend with each other when submitting effects. However, Dispatcher
instances are cheap to create and have minimal overhead (a single fiber),
so they can be allocated on-demand if necessary.
contend with each other when submitting effects. However, Dispatcher
instances are cheap to create and have minimal overhead (a single fiber),
so they can be allocated on-demand if necessary.
Notably, Dispatcher replaces Effect and ConcurrentEffect from Cats
Effect 2 while only a requiring an Async constraint.
Effect 2 while only a requiring an Async constraint.
- Companion
- object
A concurrent data structure that exposes a linear sequence of
as a single cats.effect.kernel.Resource in
R resourcesas a single cats.effect.kernel.Resource in
F without accumulation.A Hotswap is allocated within a cats.effect.kernel.Resource that
dictates the scope of its lifetime. After creation, a
be swapped in by calling swap. The newly acquired resource is returned
and is released either when the Hotswap is finalized or upon the next
call to swap, whichever occurs first.
dictates the scope of its lifetime. After creation, a
Resource[F, R] canbe swapped in by calling swap. The newly acquired resource is returned
and is released either when the Hotswap is finalized or upon the next
call to swap, whichever occurs first.
The following diagram illustrates the linear allocation and release of three
resources
resources
r1, r2, and r3 cycled through Hotswap:{{{
----- swap(r1) ---- swap(r2) ---- swap(r3) ----X
| | | | |
Creation | | | |
r1 acquired | | |
r2 acquired | |
r1 released r3 acquired |
r2 released |
r3 released
}}}
Hotswap is particularly useful when working with effects that cycle
through resources, like writing bytes to files or rotating files every N
bytes or M seconds. Without Hotswap, such effects leak resources: on
each file rotation, a file handle or some internal resource handle
accumulates. With Hotswap, the only registered resource is the
Hotswap itself, and each file is swapped in only after swapping the
previous one out.
through resources, like writing bytes to files or rotating files every N
bytes or M seconds. Without Hotswap, such effects leak resources: on
each file rotation, a file handle or some internal resource handle
accumulates. With Hotswap, the only registered resource is the
Hotswap itself, and each file is swapped in only after swapping the
previous one out.
Ported from https://github.com/typelevel/fs2.
- Companion
- object
A purely functional Priority Queue implementation based
on a binomial heap (Okasaki)
on a binomial heap (Okasaki)
Assumes an
Order instance is in scope for A- Companion
- object
A purely functional, concurrent data structure which allows insertion and
retrieval of elements of type
retrieval of elements of type
A in a first-in-first-out (FIFO) manner.Random is the ability to get random information, each time getting
a different result.
a different result.
Alumnus of the Davenverse.
- Companion
- object
A purely functional semaphore.
A semaphore has a non-negative number of permits available. Acquiring a permit
decrements the current number of permits and releasing a permit increases
the current number of permits. An acquire that occurs when there are no
permits available results in semantic blocking until a permit becomes available.
decrements the current number of permits and releasing a permit increases
the current number of permits. An acquire that occurs when there are no
permits available results in semantic blocking until a permit becomes available.
- Companion
- object
A fiber-based supervisor that monitors the lifecycle of all fibers
that are started via its interface. The supervisor is managed by a singular
fiber to which the lifecycles of all spawned fibers are bound.
that are started via its interface. The supervisor is managed by a singular
fiber to which the lifecycles of all spawned fibers are bound.
Whereas GenSpawn.background links the lifecycle of the spawned fiber to
the calling fiber, starting a fiber via a Supervisor links the lifecycle
of the spawned fiber to the supervisor fiber. This is useful when the scope
of some fiber must survive the spawner, but should still be confined within
some "larger" scope.
the calling fiber, starting a fiber via a Supervisor links the lifecycle
of the spawned fiber to the supervisor fiber. This is useful when the scope
of some fiber must survive the spawner, but should still be confined within
some "larger" scope.
The fibers started via the supervisor are guaranteed to be terminated when
the supervisor fiber is terminated. When a supervisor fiber is canceled, all
active and queued fibers will be safely finalized before finalization of
the supervisor is complete.
the supervisor fiber is terminated. When a supervisor fiber is canceled, all
active and queued fibers will be safely finalized before finalization of
the supervisor is complete.
The following diagrams illustrate the lifecycle of a fiber spawned via
GenSpawn.start, GenSpawn.background, and Supervisor. In each
example, some fiber A is spawning another fiber B. Each box represents the
lifecycle of a fiber. If a box is enclosed within another box, it means that
the lifecycle of the former is confined within the lifecycle of the latter.
In other words, if an outer fiber terminates, the inner fibers are
guaranteed to be terminated as well.
GenSpawn.start, GenSpawn.background, and Supervisor. In each
example, some fiber A is spawning another fiber B. Each box represents the
lifecycle of a fiber. If a box is enclosed within another box, it means that
the lifecycle of the former is confined within the lifecycle of the latter.
In other words, if an outer fiber terminates, the inner fibers are
guaranteed to be terminated as well.
start:
{{{
Fiber A lifecycle
+---------------------+
| | |
+-----------------|---+
|
|A starts B
Fiber B lifecycle |
+-----------------|---+
| + |
+---------------------+
}}}
{{{
Fiber A lifecycle
+---------------------+
| | |
+-----------------|---+
|
|A starts B
Fiber B lifecycle |
+-----------------|---+
| + |
+---------------------+
}}}
background:
{{{
Fiber A lifecycle
+------------------------+
| | |
| Fiber B lifecycle |A starts B
| +------------------|-+ |
| | | | |
| +--------------------+ |
+------------------------+
}}}
{{{
Fiber A lifecycle
+------------------------+
| | |
| Fiber B lifecycle |A starts B
| +------------------|-+ |
| | | | |
| +--------------------+ |
+------------------------+
}}}
Supervisor:
{{{
Supervisor lifecycle
+---------------------+
| Fiber B lifecycle |
| +-----------------+ |
| | + | |
| +---------------|-+ |
+-----------------|---+
|
| A starts B
Fiber A lifecycle |
+-----------------|---+
| | |
+---------------------+
}}}
{{{
Supervisor lifecycle
+---------------------+
| Fiber B lifecycle |
| +-----------------+ |
| | + | |
| +---------------|-+ |
+-----------------|---+
|
| A starts B
Fiber A lifecycle |
+-----------------|---+
| | |
+---------------------+
}}}
Supervisor should be used when fire-and-forget semantics are desired.
- Companion
- object