#include <userver/engine/single_use_event.hpp>

Detailed Description

A single-producer, single-consumer event.

Once the producer sends the event, it remains in the signaled state forever.

SingleUseEvent can be used as a faster non-allocating alternative to engine::Future. However, it is more low-level and error-prone, see below.

Compatible with engine::WaitAny and friends.

Destroying a SingleUseEvent after waking up

The waiting coroutine is allowed to immediately destroy the SingleUseEvent after waking up; it will not stop a concurrent Send from completing correctly. This is contrary to the properties of other userver synchronization primitives, like engine::Mutex.

However, if the wait operation ends in something other than engine::Future::kReady, then it is the responsibility of the waiter to guarantee that it either prevents the oncoming Send call or awaits it. One way to force waiting until the Send call happens is to use engine::SingleUseEvent::WaitNonCancellable.

Example usage

  engine::TaskWithResult<void> sender;
  {
    engine::SingleUseEvent event;
    sender = utils::Async("sender", [&event] { event.Send(); });
 
    event.WaitNonCancellable();  // will be woken up by 'Send()' above
 
    // 'event' is destroyed here. Note that 'Send' might continue executing, but
    // it will still complete safely.
  }

See also: Synchronization Primitives

Definition at line 45 of file single_use_event.hpp.

Inheritance diagram for engine::SingleUseEvent:

Collaboration diagram for engine::SingleUseEvent:

Public Member Functions
	SingleUseEvent (const SingleUseEvent &)=delete

	SingleUseEvent (SingleUseEvent &&)=delete

SingleUseEvent &	operator= (const SingleUseEvent &)=delete

SingleUseEvent &	operator= (SingleUseEvent &&)=delete

void	Wait ()
	Waits until the event is in a signaled state.

FutureStatus	WaitUntil (Deadline)
	Waits until the event is in a signaled state, or the deadline expires, or the current task is cancelled.

void	WaitNonCancellable () noexcept
	Waits until the event is in a signaled state, ignoring task cancellations.

void	Send () noexcept

bool	IsReady () const noexcept override
	Returns true iff already signaled.

Member Function Documentation

◆ Send()

void engine::SingleUseEvent::Send ( )

noexcept

Sets the signal flag and wakes a coroutine that waits on it, if any. Send must not be called again.

◆ Wait()

void engine::SingleUseEvent::Wait ( )

Waits until the event is in a signaled state.

Exceptions

engine::WaitInterruptedException if the current task is cancelled

◆ WaitNonCancellable()

void engine::SingleUseEvent::WaitNonCancellable ( )

noexcept

Waits until the event is in a signaled state, ignoring task cancellations.

The waiter coroutine can destroy the SingleUseEvent object immediately after waking up, if necessary.

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

userver/engine/single_use_event.hpp