kotlinx-coroutines-core/kotlinx.coroutines.sync/Semaphore

Semaphore

A counting semaphore for coroutines that logically maintains a number of available permits. Each acquire takes a single permit or suspends until it is available. Each release adds a permit, potentially releasing a suspended acquirer. Semaphore is fair and maintains a FIFO order of acquirers.

Semaphores are mostly used to limit the number of coroutines that have access to particular resource. Semaphore with permits = 1 is essentially a Mutex.

Properties

availablePermits

abstract val availablePermits: Int

Returns the current number of permits available in this semaphore.

Functions

acquire

abstract suspend fun acquire()

Acquires a permit from this semaphore, suspending until one is available. All suspending acquirers are processed in first-in-first-out (FIFO) order.

release

abstract fun release()

Releases a permit, returning it into this semaphore. Resumes the first suspending acquirer if there is one at the point of invocation. Throws IllegalStateException if the number of release invocations is greater than the number of preceding acquire.

tryAcquire

abstract fun tryAcquire(): Boolean

Tries to acquire a permit from this semaphore without suspension.

withPermit

inline suspend fun <T> Semaphore.withPermit(action: () -> T): T

Executes the given action, acquiring a permit from this semaphore at the beginning and releasing it after the action is completed.