engine::CancellableSemaphore Class Reference

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

Public Types
using	Counter = std::size_t

Public Member Functions
	CancellableSemaphore (Counter capacity)
	CancellableSemaphore (CancellableSemaphore &&)=delete
	CancellableSemaphore (const CancellableSemaphore &)=delete
CancellableSemaphore &	operator= (CancellableSemaphore &&)=delete
CancellableSemaphore &	operator= (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 47 of file semaphore.hpp.

Constructor & Destructor Documentation

CancellableSemaphore()

engine::CancellableSemaphore::CancellableSemaphore ( 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::CancellableSemaphore::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 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.

Exceptions

UnreachableSemaphoreLockError	if capacity == 0
SemaphoreLockCancelledError	if 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 274 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 280 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.

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