userver: engine::CancellableSemaphore Class Reference
No Matches
engine::CancellableSemaphore Class Referencefinal

#include <userver/engine/semaphore.hpp>

Detailed Description

Class that allows up to max_simultaneous_locks concurrent accesses to the critical section. It honours task cancellation, unlike Semaphore.

Example usage:

constexpr auto kMaxSimultaneousLocks = 3;
engine::Semaphore sema(kMaxSimultaneousLocks);
// ...
std::shared_lock lock(sema);
// There may be no more than 3 users
// in the critical section at the same time
See also
Synchronization Primitives

Definition at line 41 of file semaphore.hpp.

Public Types

using Counter = std::size_t

Public Member Functions

 CancellableSemaphore (Counter capacity)
 CancellableSemaphore (CancellableSemaphore &&)=delete
 CancellableSemaphore (const CancellableSemaphore &)=delete
CancellableSemaphoreoperator= (CancellableSemaphore &&)=delete
CancellableSemaphoreoperator= (const CancellableSemaphore &)=delete
void SetCapacity (Counter capacity)
Counter GetCapacity () const noexcept
 Gets the total number of available locks.
std::size_t RemainingApprox () const
 Returns an approximate number of available locks, use only for statistics.
std::size_t UsedApprox () const
 Returns an approximate number of used locks, use only for statistics.
void lock_shared ()
void unlock_shared ()
bool try_lock_shared ()
template<typename Rep , typename Period >
bool try_lock_shared_for (std::chrono::duration< Rep, Period >)
template<typename Clock , typename Duration >
bool try_lock_shared_until (std::chrono::time_point< Clock, Duration >)
bool try_lock_shared_until (Deadline deadline)
void lock_shared_count (Counter count)
void unlock_shared_count (Counter count)
bool try_lock_shared_count (Counter count)
bool try_lock_shared_until_count (Deadline deadline, Counter count)

Member Typedef Documentation

◆ Counter

using engine::CancellableSemaphore::Counter = std::size_t

Definition at line 43 of file semaphore.hpp.

Constructor & Destructor Documentation

◆ CancellableSemaphore()

engine::CancellableSemaphore::CancellableSemaphore ( Counter capacity)

Creates a semaphore with predefined number of available locks

capacityinitial number of available locks

Member Function Documentation

◆ lock_shared()

void engine::CancellableSemaphore::lock_shared ( )

Decrements internal semaphore lock counter. Blocks if current counter is zero until the subsequent call to unlock_shared() by another coroutine.

the user should eventually call unlock_shared() to increment the lock counter.
the method doesn't wait for the semaphore if the current task is cancelled. If a task waits on CancellableSemaphore and the cancellation is requested, the waiting is aborted with an exception.
UnreachableSemaphoreLockErrorif capacity == 0
SemaphoreLockCancelledErrorif the current task is cancelled

◆ SetCapacity()

void engine::CancellableSemaphore::SetCapacity ( Counter capacity)

Sets the total number of available locks. If the lock count decreases, the current acquired lock count may temporarily go above the limit.

◆ try_lock_shared_for()

template<typename Rep , typename Period >
bool engine::CancellableSemaphore::try_lock_shared_for ( std::chrono::duration< Rep, Period > duration)

Definition at line 270 of file semaphore.hpp.

◆ try_lock_shared_until()

template<typename Clock , typename Duration >
bool engine::CancellableSemaphore::try_lock_shared_until ( std::chrono::time_point< Clock, Duration > until)

Definition at line 276 of file semaphore.hpp.

◆ unlock_shared()

void engine::CancellableSemaphore::unlock_shared ( )

Increments internal semaphore lock counter. If there is a user waiting in lock_shared() on the same semaphore, it is woken up.

the order of coroutines to unblock is unspecified. Any code assuming any specific order (e.g. FIFO) is incorrect and must be fixed.
it is allowed to call lock_shared() in one coroutine and subsequently call unlock_shared() in another coroutine. In particular, it is allowed to pass std::shared_lock<engine::Semaphore> across coroutines.

The documentation for this class was generated from the following file: