std

package std

Ordering

Alphabetic

Visibility

Public
Protected

Package Members

package syntax

Type Members

abstract class AtomicCell[F[_], A] extends AnyRef

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 except get 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)
      }
    }
}

See also: cats.effect.kernel.Ref for a non-blocking alternative.

trait Backpressure[F[_]] extends AnyRef
Utility to apply backpressure semantics to the execution of an Effect.
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

trait Console[F[_]] extends ConsoleCrossPlatform[F]

Effect type agnostic Console with common methods to write to and read from the standard console.

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 in trivial applications.

Examples:

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 ()

abstract class CountDownLatch[F[_]] extends AnyRef
Concurrency abstraction that supports fiber blocking until n latches are released.
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
abstract class CyclicBarrier[F[_]] extends AnyRef
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.
trait Dequeue[F[_], A] extends Queue[F, A] with DequeueSource[F, A] with DequeueSink[F, A]
trait DequeueSink[F[_], A] extends QueueSink[F, A]
trait DequeueSource[F[_], A] extends QueueSource[F, A]
trait Dispatcher[F[_]] extends DispatcherPlatform[F]
A fiber-based supervisor utility for evaluating effects across an impure boundary.
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.
trait Env[F[_]] extends AnyRef
Effect type agnostic Env with common methods to read environment variables
sealed trait Hotswap[F[_], R] extends AnyRef
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.
trait MapRef[F[_], K, V] extends (K) => kernel.Ref[F, V]
This is a total map from K to Ref[F, V].
This is a total map from K to Ref[F, V].
It is conceptually similar to a Ref[F, Map[K, V]], but with better ergonomics when working on a per key basis. Note, however, that it does not support atomic updates to multiple keys.
Additionally, some implementations also provide less contention: since all operations are performed on individual key-value pairs, the pairs can be sharded by key. Thus, multiple concurrent updates may be executed independently to each other, as long as their keys belong to different shards.
abstract class Mutex[F[_]] extends AnyRef
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.
See also
cats.effect.std.AtomicCell
abstract class PQueue[F[_], A] extends PQueueSource[F, A] with PQueueSink[F, A]
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
trait PQueueSink[F[_], A] extends AnyRef
trait PQueueSource[F[_], A] extends AnyRef
abstract class Queue[F[_], A] extends QueueSource[F, A] with QueueSink[F, 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.
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.
trait QueueSink[F[_], A] extends AnyRef
trait QueueSource[F[_], A] extends AnyRef
trait Random[F[_]] extends AnyRef
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.
trait SecureRandom[F[_]] extends Random[F]
SecureRandom is the ability to get cryptographically strong random information.
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.
abstract class Semaphore[F[_]] extends AnyRef
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.
trait Supervisor[F[_]] extends AnyRef
A fiber-based supervisor that monitors the lifecycle of all fibers that are started via its interface.
A fiber-based supervisor that monitors the lifecycle of all fibers that are started via its interface. The lifecycles of all these spawned fibers are bound to the lifecycle of the Supervisor itself.
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 is terminated. When a supervisor is finalized, 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.
trait UUIDGen[F[_]] extends AnyRef
A purely functional UUID Generator

Value Members

object AtomicCell
object Backpressure
object Console extends ConsoleCompanionCrossPlatform with ConsoleCompanionPlatform
object CountDownLatch
object CyclicBarrier
object Dequeue
object DequeueSink
object DequeueSource
object Dispatcher
object Env extends EnvCompanionPlatform
object Hotswap
object MapRef extends MapRefCompanionPlatform
object Mutex
object PQueue
object PQueueSink
object PQueueSource
object Queue
object QueueSink
object QueueSource
object Random extends RandomCompanionPlatform
object SecureRandom extends SecureRandomCompanionPlatform
object Semaphore
object Supervisor
object UUIDGen extends UUIDGenCompanionPlatform

Packages

std

package std

Package Members

Type Members

Value Members

Ungrouped

Packages

std

package std

Package Members

Type Members

Value Members

Ungrouped

std