cats.effect.std

A synchronized, concurrent, mutable reference.

Provides safe concurrent access and modification of its contents, by ensuring only one fiber can operate on them at the time. Thus, '''all''' operations may semantically block the calling fiber.

 final class ParkingLot(data: AtomicCell[IO, ArraySeq[Boolean]], rnd: Random[IO]) {
   def getSpot: IO[Option[Int]] =
     data.evalModify { spots =>
       val availableSpots = spots.zipWithIndex.collect { case (true, idx) => idx }
       rnd.shuffleList(availableSpots).map { shuffled =>
         val acquired = shuffled.headOption
         val next = acquired.fold(spots)(a => spots.updated(a, false)) // mark the chosen spot as taken
         (next, shuffled.headOption)
       }
     }
 }

Utility to apply backpressure semantics to the execution of an Effect. Backpressure instances will apply a Backpressure.Strategy to the execution where each strategy works as follows:

Backpressure.Strategy.Lossy will mean that effects will not be run in the presence of backpressure, meaning the result will be None

Backpressure.Strategy.Lossless will mean that effects will run in the presence of backpressure, meaning the effect will semantically block until backpressure is alleviated

Effect type agnostic Console with common methods to write to and read from the standard console. Suited only for extremely simple console input and output.

Concurrency abstraction that supports fiber blocking until n latches are released. Note that this has 'one-shot' semantics - once the counter reaches 0 then release and await will forever be no-ops

See https://typelevel.org/blog/2020/10/30/concurrency-in-ce3.html for a walkthrough of building something like this

A synchronization abstraction that allows a set of fibers 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.

At this point all the fibers are unblocked and the cyclic barrier is reset, allowing it to be used again.

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 F must be performed (like inserting each value into a queue).

Dispatcher is a kind of Supervisor and accordingly follows the same 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, so they can be allocated on-demand if necessary.

Notably, Dispatcher replaces Effect and ConcurrentEffect from Cats Effect 2 while only requiring an cats.effect.kernel.Async constraint.

Effect type agnostic Env with common methods to read environment variables

A concurrent data structure that exposes a linear sequence of R resources as 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 Resource[F, R] can 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.

The following diagram illustrates the linear allocation and release of three 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.

Ported from https://github.com/typelevel/fs2.

This is a total map from K to Ref[F, V]. This allows us to use the Ref API backed by a ConcurrentHashMap or similar.

A purely functional mutex.

A mutex is a concurrency primitive that can be used to give access to a resource to only one fiber at a time; e.g. a cats.effect.kernel.Ref.

// Assuming some resource r that should not be used concurrently.

Mutex[IO].flatMap { mutex =>
 mutex.lock.surround {
   // Here you can use r safely.
   IO(r.mutate(...))
 }
}

'''Note''': This lock is not reentrant, thus this mutex.lock.surround(mutex.lock.use_) will deadlock.

A purely functional Priority Queue implementation based on a binomial heap (Okasaki)

Assumes an Order instance is in scope for A

A purely functional, concurrent data structure which allows insertion and retrieval of elements of type A in a first-in-first-out (FIFO) manner.

Depending on the type of queue constructed, the Queue#offer operation can block semantically until sufficient capacity in the queue becomes available.

The Queue#take operation semantically blocks when the queue is empty.

The Queue#tryOffer and Queue#tryTake allow for usecases which want to avoid fiber blocking a fiber.

Random is the ability to get random information, each time getting a different result.

Alumnus of the Davenverse.

SecureRandom is the ability to get cryptographically strong random information. It is an extension of the Random interface, but is used where weaker implementations must be precluded.

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 fiber blocking until a permit becomes available.

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.

Whereas cats.effect.kernel.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 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 following diagrams illustrate the lifecycle of a fiber spawned via cats.effect.kernel.GenSpawn.start, cats.effect.kernel.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 |
+-----------------|---+
|                 +   |
+---------------------+

background:

Fiber A lifecycle
+------------------------+
|                    |   |
| Fiber B lifecycle  |A starts B
| +------------------|-+ |
| |                  | | |
| +--------------------+ |
+------------------------+

Supervisor:

Supervisor lifecycle
+---------------------+
| Fiber B lifecycle   |
| +-----------------+ |
| |               + | |
| +---------------|-+ |
+-----------------|---+
                 |
                 | A starts B
Fiber A lifecycle |
+-----------------|---+
|                 |   |
+---------------------+

Supervisor should be used when fire-and-forget semantics are desired.

A purely functional UUID Generator