#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

Semaphore &	operator= (Semaphore &&)=delete

Semaphore &	operator= (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

capacity initial 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

UnreachableSemaphoreLockError if 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:

userver/engine/semaphore.hpp