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
- Alphabetic
- By Inheritance
- Semaphore
- Semaphore
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Value Members
- final def !=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def ##(): Int
- Definition Classes
- AnyRef → Any
- final def ==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- 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
- def acquireN(n: Long): F[Unit]
Acquires
npermits.Acquires
npermits.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, anacquireN(3)will always be satisfied before a later call toacquireN(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
- final def asInstanceOf[T0]: T0
- Definition Classes
- Any
- 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()
- 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
awaitAvailablecan 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()
- def clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.CloneNotSupportedException]) @native() @HotSpotIntrinsicCandidate()
- 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()
- final def eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def equals(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef → Any
- final def getClass(): Class[_ <: AnyRef]
- Definition Classes
- AnyRef → Any
- Annotations
- @native() @HotSpotIntrinsicCandidate()
- def hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @native() @HotSpotIntrinsicCandidate()
- def imapK[G[_]](f: ~>[F, G], g: ~>[G, F]): cats.effect.concurrent.Semaphore[G]
- Definition Classes
- Semaphore
- final def isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- final def ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- final def notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native() @HotSpotIntrinsicCandidate()
- final def notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native() @HotSpotIntrinsicCandidate()
- 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
- def releaseN(n: Long): F[Unit]
Releases
npermits, potentially unblocking up tonoutstanding acquires.Releases
npermits, potentially unblocking up tonoutstanding acquires.- n
number of permits to release - must be >= 0
- Definition Classes
- Semaphore → Semaphore
- See also
withPermit, the preferred way to acquire and release
- final def synchronized[T0](arg0: => T0): T0
- Definition Classes
- AnyRef
- def toString(): String
- Definition Classes
- AnyRef → Any
- 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
- 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
- final def wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException]) @native()
- final def wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- 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
- def withPermitN[A](n: Long)(fa: F[A]): F[A]
Returns a new task, ensuring that the given source acquires
navailable permits from the semaphore before it is executed.Returns a new task, ensuring that the given source acquires
navailable 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
This is the API documentation for the Monix library.
Package Overview
monix.execution exposes lower level primitives for dealing with asynchronous execution:
Atomictypes, as alternative tojava.util.concurrent.atomicmonix.catnap exposes pure abstractions built on top of the Cats-Effect type classes:
monix.eval is for dealing with evaluation of results, thus exposing Task and Coeval.
monix.reactive exposes the
Observablepattern:Observableimplementationsmonix.tail exposes Iterant for purely functional pull based streaming:
BatchandBatchCursor, the alternatives to Scala'sIterableandIteratorrespectively that we are using within Iterant's encodingYou can control evaluation with type you choose - be it Task, Coeval, cats.effect.IO or your own as long as you provide correct cats-effect or cats typeclass instance.