cats.effect.std
Members list
Type members
Classlikes
A synchronized, concurrent, mutable reference.
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, Vector[Boolean]], rnd: Random[IO]) {
def getSpot: IO[Option[Int]] =
data.evalModify { spots =>
val availableSpots = spots.zipWithIndex.collect { case (true, idx) => idx }
rnd.shuffleVector(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)
}
}
}
Attributes
- See also:
cats.effect.kernel.Ref for a non-blocking alternative.
- Companion:
- object
- Source:
- AtomicCell.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
Attributes
- Companion:
- class
- Source:
- AtomicCell.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- AtomicCell.type
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:
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
Attributes
- Companion:
- object
- Source:
- Backpressure.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
Attributes
- Companion:
- trait
- Source:
- Backpressure.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- Backpressure.type
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.
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.
Attributes
- Note:
readLine
is not implemented for Scala.js. On Node.js consider usingfs2.io.stdin
.- Example:
import cats.effect.IO import cats.effect.std.Console def myProgram: IO[Unit] = for { _ <- Console[IO].println("Please enter your name: ") n <- Console[IO].readLine _ <- if (n.nonEmpty) Console[IO].println("Hello, " + n) else Console[IO].errorln("Name is empty!") } yield ()
import cats.Monad import cats.effect.std.Console import cats.syntax.all._ def myProgram[F[_]: Console: Monad]: F[Unit] = for { _ <- Console[F].println("Please enter your name: ") n <- Console[F].readLine _ <- if (n.nonEmpty) Console[F].println("Hello, " + n) else Console[F].errorln("Name is empty!") } yield ()
- Companion:
- object
- Source:
- Console.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
Attributes
- Companion:
- trait
- Source:
- Console.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- Console.type
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
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
Attributes
- Companion:
- object
- Source:
- CountDownLatch.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
Attributes
- Companion:
- class
- Source:
- CountDownLatch.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- CountDownLatch.type
A synchronization abstraction that allows a set of fibers to wait until they all reach a certain point.
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.
Attributes
- Companion:
- object
- Source:
- CyclicBarrier.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
Attributes
- Companion:
- class
- Source:
- CyclicBarrier.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- CyclicBarrier.type
Attributes
- Companion:
- object
- Source:
- Dequeue.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
Attributes
- Companion:
- trait
- Source:
- Dequeue.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- Dequeue.type
Attributes
- Companion:
- object
- Source:
- Dequeue.scala
- Graph
- Supertypes
- Known subtypes
Attributes
- Companion:
- trait
- Source:
- Dequeue.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- DequeueSink.type
Attributes
- Companion:
- object
- Source:
- Dequeue.scala
- Graph
- Supertypes
- Known subtypes
Attributes
- Companion:
- trait
- Source:
- Dequeue.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- DequeueSource.type
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).
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.
Attributes
- Companion:
- object
- Source:
- Dispatcher.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
Attributes
- Companion:
- trait
- Source:
- Dispatcher.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- Dispatcher.type
A concurrent data structure that exposes a linear sequence of R
resources as a single
cats.effect.kernel.Resource in F
without accumulation.
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.
Attributes
- Companion:
- object
- Source:
- Hotswap.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
Attributes
- Companion:
- trait
- Source:
- Hotswap.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- Hotswap.type
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.
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.
Attributes
- Companion:
- object
- Source:
- MapRef.scala
- Graph
- Supertypes
Attributes
- Companion:
- trait
- Source:
- MapRef.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- MapRef.type
A purely functional mutex.
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.
Attributes
- See also:
- Companion:
- object
- Source:
- Mutex.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
Attributes
- Companion:
- class
- Source:
- Mutex.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- Mutex.type
A purely functional Priority Queue implementation based on a binomial heap (Okasaki)
A purely functional Priority Queue implementation based on a binomial heap (Okasaki)
Assumes an Order
instance is in scope for A
Attributes
- Companion:
- object
- Source:
- PQueue.scala
- Graph
- Supertypes
- Self type
Attributes
- Companion:
- class
- Source:
- PQueue.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- PQueue.type
Attributes
- Companion:
- object
- Source:
- PQueue.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Known subtypes
Attributes
- Companion:
- trait
- Source:
- PQueue.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- PQueueSink.type
Attributes
- Companion:
- object
- Source:
- PQueue.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Known subtypes
Attributes
- Companion:
- trait
- Source:
- PQueue.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- PQueueSource.type
A purely functional, concurrent data structure which allows insertion and retrieval of
elements of type A
in a first-in-first-out (FIFO) manner.
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.
Attributes
- Companion:
- object
- Source:
- Queue.scala
- Graph
- Supertypes
- Known subtypes
- Self type
Attributes
- Companion:
- class
- Source:
- Queue.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- Queue.type
Attributes
- Companion:
- object
- Source:
- Queue.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Known subtypes
Attributes
- Companion:
- trait
- Source:
- Queue.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- QueueSink.type
Attributes
- Companion:
- object
- Source:
- Queue.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Known subtypes
Attributes
- Companion:
- trait
- Source:
- Queue.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- QueueSource.type
Random is the ability to get random information, each time getting a different result.
Random is the ability to get random information, each time getting a different result.
Alumnus of the Davenverse.
Attributes
- Companion:
- object
- Source:
- Random.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Known subtypes
- trait SecureRandom[F]
- Self type
- Random[F]
Attributes
- Companion:
- trait
- Source:
- Random.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- Random.type
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.
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.
Attributes
- Companion:
- object
- Source:
- SecureRandom.scala
- Graph
- Supertypes
- Self type
- SecureRandom[F]
Attributes
- Companion:
- trait
- Source:
- SecureRandom.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- SecureRandom.type
A purely functional semaphore.
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.
Attributes
- Companion:
- object
- Source:
- Semaphore.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
Attributes
- Companion:
- class
- Source:
- Semaphore.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- Semaphore.type
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.
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.
Attributes
- Companion:
- object
- Source:
- Supervisor.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
Attributes
- Companion:
- trait
- Source:
- Supervisor.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- Supervisor.type
A purely functional UUID Generator
A purely functional UUID Generator
Attributes
- Companion:
- object
- Source:
- UUIDGen.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
Attributes
- Companion:
- trait
- Source:
- UUIDGen.scala
- Graph
- Supertypes
- class Objecttrait Matchableclass Any
- Self type
- UUIDGen.type