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

#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

{
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
 
SingleUseEventoperator= (const SingleUseEvent &)=delete
 
SingleUseEventoperator= (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::WaitInterruptedExceptionif 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: