userver: engine::Semaphore Class Reference
Loading...
Searching...
No Matches
engine::Semaphore Class Referencefinal

#include <userver/engine/semaphore.hpp>

Detailed Description

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

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 141 of file semaphore.hpp.

Public Types

using Counter = std::size_t
 

Public Member Functions

 Semaphore (Counter capacity)
 
 Semaphore (Semaphore &&)=delete
 
 Semaphore (const Semaphore &)=delete
 
Semaphoreoperator= (Semaphore &&)=delete
 
Semaphoreoperator= (const Semaphore &)=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::Semaphore::Counter = std::size_t

Definition at line 143 of file semaphore.hpp.

Constructor & Destructor Documentation

◆ Semaphore()

engine::Semaphore::Semaphore ( Counter capacity)
explicit

Creates a semaphore with predefined number of available locks

Parameters
capacityinitial number of available locks

Member Function Documentation

◆ lock_shared()

void engine::Semaphore::lock_shared ( )

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

Note
the user must eventually call unlock_shared() to increment the lock counter.
the method waits for the semaphore even if the current task is cancelled.
Exceptions
UnreachableSemaphoreLockErrorif capacity == 0

◆ SetCapacity()

void engine::Semaphore::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()

bool engine::Semaphore::try_lock_shared ( )

Decrements internal semaphore lock counter if current counter is not zero.

Note
unlock_shared() should be called later to increment the lock counter.

◆ try_lock_shared_for()

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

Definition at line 262 of file semaphore.hpp.

◆ try_lock_shared_until()

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

Definition at line 268 of file semaphore.hpp.

◆ unlock_shared()

void engine::Semaphore::unlock_shared ( )

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

Note
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: