Packages

final class Semaphore[F[_]] extends cats.effect.concurrent.Semaphore[F]

The Semaphore is an asynchronous semaphore implementation that limits the parallelism on task execution.

The following example instantiates a semaphore with a maximum parallelism of 10:

import cats.implicits._
import cats.effect.IO

// Needed for ContextShift[IO]
import monix.execution.Scheduler
implicit val cs = IO.contextShift(Scheduler.global)

// Dummies for didactic purposes
case class HttpRequest()
case class HttpResponse()
def makeRequest(r: HttpRequest): IO[HttpResponse] = IO(???)

for {
  semaphore <- Semaphore[IO](provisioned = 10)
  tasks = for (_ <- 0 until 1000) yield {
    semaphore.withPermit(makeRequest(???))
  }
  // Execute in parallel; note that due to the `semaphore`
  // no more than 10 tasks will be allowed to execute in parallel
  _ <- tasks.toList.parSequence
} yield ()

Credits

Semaphore is now implementing cats.effect.Semaphore, deprecating the old Monix TaskSemaphore.

The changes to the interface and some implementation details are inspired by the implementation in Cats-Effect, which was ported from FS2.

Source
Semaphore.scala
Linear Supertypes
cats.effect.concurrent.Semaphore[F], AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. Semaphore
  2. Semaphore
  3. AnyRef
  4. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. def acquire: F[Unit]

    Acquires a single permit.

    Acquires a single permit. Alias for acquireN(1).

    Definition Classes
    Semaphore → Semaphore
    See also

    withPermit, the preferred way to acquire and release

    acquireN for a version that can acquire multiple permits

  5. def acquireN(n: Long): F[Unit]

    Acquires n permits.

    Acquires n permits.

    The returned effect semantically blocks until all requested permits are available. Note that acquires are satisfied in strict FIFO order, so given a Semaphore[F] with 2 permits available, an acquireN(3) will always be satisfied before a later call to acquireN(1).

    n

    number of permits to acquire; must be >= 0

    Definition Classes
    Semaphore → Semaphore
    See also

    withPermit, the preferred way to acquire and release

    acquire for a version acquires a single permit

  6. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  7. def available: F[Long]

    Returns the number of permits currently available.

    Returns the number of permits currently available. Always non-negative.

    The protocol is unsafe, the semaphore is used in concurrent settings and thus the value returned isn't stable or reliable. Use with care.

    Definition Classes
    Semaphore → Semaphore
    Annotations
    @UnsafeProtocol()
  8. def awaitAvailable(n: Long): F[Unit]

    Returns a task that will be complete when the specified number of permits are available.

    Returns a task that will be complete when the specified number of permits are available.

    The protocol is unsafe because by the time the returned task completes, some other process might have already acquired the available permits and thus usage of awaitAvailable can lead to fragile concurrent logic. Use with care.

    Can be useful for termination logic, for example to execute a piece of logic once all available permits have been released.

    n

    is the number of permits waited on

    Annotations
    @UnsafeProtocol()
  9. def clone(): AnyRef
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @native()
  10. def count: F[Long]

    Obtains a snapshot of the current count.

    Obtains a snapshot of the current count. Can be negative.

    Like available when permits are available but returns the number of permits callers are waiting for when there are no permits available.

    Definition Classes
    Semaphore → Semaphore
    Annotations
    @UnsafeProtocol()
  11. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  12. def equals(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef → Any
  13. def finalize(): Unit
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable])
  14. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  15. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  16. def imapK[G[_]](f: ~>[F, G], g: ~>[G, F]): cats.effect.concurrent.Semaphore[G]
    Definition Classes
    Semaphore
  17. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  18. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  19. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  20. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  21. def release: F[Unit]

    Releases a permit, returning it to the pool.

    Releases a permit, returning it to the pool.

    If there are consumers waiting on permits being available, then the first in the queue will be selected and given a permit immediately.

    Definition Classes
    Semaphore → Semaphore
    See also

    withPermit, the preferred way to acquire and release

  22. def releaseN(n: Long): F[Unit]

    Releases n permits, potentially unblocking up to n outstanding acquires.

    Releases n permits, potentially unblocking up to n outstanding acquires.

    n

    number of permits to release - must be >= 0

    Definition Classes
    Semaphore → Semaphore
    See also

    withPermit, the preferred way to acquire and release

  23. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  24. def toString(): String
    Definition Classes
    AnyRef → Any
  25. def tryAcquire: F[Boolean]

    Alias for tryAcquireN(1).

    Alias for tryAcquireN(1).

    The protocol is unsafe, because with the "try*" methods the user needs a firm grasp of what race conditions are and how they manifest and usage of such methods can lead to very fragile logic.

    Definition Classes
    Semaphore → Semaphore
    Annotations
    @UnsafeProtocol()
    See also

    tryAcquireN for the version that can acquire multiple permits

    acquire for the version that can wait for acquisition

    withPermit the preferred way to acquire and release

  26. def tryAcquireN(n: Long): F[Boolean]

    Alias for tryAcquireN(1).

    Alias for tryAcquireN(1).

    The protocol is unsafe, because with the "try*" methods the user needs a firm grasp of what race conditions are and how they manifest and usage of such methods can lead to very fragile logic.

    Definition Classes
    Semaphore → Semaphore
    Annotations
    @UnsafeProtocol()
    See also

    tryAcquireN for the version that can acquire multiple permits

    acquire for the version that can wait for acquisition

    withPermit the preferred way to acquire and release

  27. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  28. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  29. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException]) @native()
  30. def withPermit[A](fa: F[A]): F[A]

    Returns a new task, ensuring that the given source acquires an available permit from the semaphore before it is executed.

    Returns a new task, ensuring that the given source acquires an available permit from the semaphore before it is executed.

    The returned task also takes care of resource handling, releasing its permit after being complete.

    fa

    is an effect to execute once the permit has been acquired; regardless of its result, the permit is released to the pool afterwards

    Definition Classes
    Semaphore → Semaphore
  31. def withPermitN[A](n: Long)(fa: F[A]): F[A]

    Returns a new task, ensuring that the given source acquires n available permits from the semaphore before it is executed.

    Returns a new task, ensuring that the given source acquires n available permits from the semaphore before it is executed.

    The returned task also takes care of resource handling, releasing its permits after being complete.

    n

    is the number of permits required for the given function to be executed

    fa

    is an effect to execute once the permits have been acquired; regardless of its result, the permits are released to the pool afterwards

Inherited from cats.effect.concurrent.Semaphore[F]

Inherited from AnyRef

Inherited from Any

Ungrouped