Packages

package std

Ordering
  1. Alphabetic
Visibility
  1. Public
  2. Protected

Package Members

  1. package syntax

Type Members

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

    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, 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)
          }
        }
    }
    See also

    cats.effect.kernel.Ref for a non-blocking alternative.

  2. 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

  3. 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. Due to issues around cancellation in readLine, suited only for extremely simple console input and output in trivial applications.

    Examples:
    1. 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 ()
    2. ,
    3. 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 ()
  4. 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

  5. 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.

  6. trait Dequeue[F[_], A] extends Queue[F, A] with DequeueSource[F, A] with DequeueSink[F, A]
  7. trait DequeueSink[F[_], A] extends QueueSink[F, A]
  8. trait DequeueSource[F[_], A] extends QueueSource[F, A]
  9. 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.

  10. trait Env[F[_]] extends AnyRef

    Effect type agnostic Env with common methods to read environment variables

  11. 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.

  12. 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]. This allows us to use the Ref API backed by a ConcurrentHashMap or similar.

  13. 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

  14. 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

  15. trait PQueueSink[F[_], A] extends AnyRef
  16. trait PQueueSource[F[_], A] extends AnyRef
  17. 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.

  18. trait QueueSink[F[_], A] extends AnyRef
  19. trait QueueSource[F[_], A] extends AnyRef
  20. 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.

  21. 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.

  22. 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.

  23. 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 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.

  24. trait UUIDGen[F[_]] extends AnyRef

    A purely functional UUID Generator

Value Members

  1. object AtomicCell
  2. object Backpressure
  3. object Console extends ConsoleCompanionCrossPlatform
  4. object CountDownLatch
  5. object CyclicBarrier
  6. object Dequeue
  7. object DequeueSink
  8. object DequeueSource
  9. object Dispatcher
  10. object Env extends EnvCompanionPlatform
  11. object Hotswap
  12. object MapRef extends MapRefCompanionPlatform
  13. object Mutex
  14. object PQueue
  15. object PQueueSink
  16. object PQueueSource
  17. object Queue
  18. object QueueSink
  19. object QueueSource
  20. object Random extends RandomCompanionPlatform
  21. object SecureRandom extends SecureRandomCompanionPlatform
  22. object Semaphore
  23. object Supervisor
  24. object UUIDGen extends UUIDGenCompanionPlatform

Ungrouped