#include <WaitableEvent.h>

Public Types
enum class	WaitStatus

Public Member Functions
	~WaitableEvent ()=default

nonvirtual void	Reset ()

nonvirtual bool	GetIsSet () const noexcept

nonvirtual bool	PeekIsSet () const noexcept

nonvirtual void	Set ()

nonvirtual void	Wait (Time::DurationSeconds timeout=Time::kInfinity)

nonvirtual WaitStatus	WaitQuietly (Time::DurationSeconds timeout=Time::kInfinity)

nonvirtual void	WaitUntil (Time::TimePointSeconds timeoutAt)

nonvirtual WaitStatus	WaitUntilQuietly (Time::TimePointSeconds timeoutAt)

nonvirtual void	WaitAndReset (Time::Duration timeout=Time::kInfinity)

Detailed Description

AutoReset Waitable Event (like Windows' CreateEvent (resetType==eManualReset, false)).

Note: Thread-Safety Internally-Synchronized-Thread-Safety; async-signal-safety - this is NOT safe to use from signals (from http://pubs.opengroup.org/onlinepubs/009695399/functions/pthread_cond_broadcast.html - It is not safe to use the pthread_cond_signal() function in a signal handler that is invoked asynchronously Use POSIX sem_init/sem_post (); Design Note Considered making this copyable, or at least movable, but mutex and other similar classes are not. and you can easily use shared_ptr<> on an WaitableEvent to make it copyable.; Design Note WaitForAny/WaitForAnyUntil and WaitForMultipleEvents

See also: qStroika_Foundation_Execution_WaitableEvent_SupportWaitForMultipleObjects

Definition at line 88 of file WaitableEvent.h.

Member Enumeration Documentation

◆ WaitStatus

enum class Stroika::Foundation::Execution::WaitableEvent::WaitStatus

strong

Intentionally omit case of spurious wakeup we get from condition variables.

Definition at line 174 of file WaitableEvent.h.

Constructor & Destructor Documentation

◆ ~WaitableEvent()

Stroika::Foundation::Execution::WaitableEvent::~WaitableEvent ( )

default

Note: the user of this class must assure all waiters have completed their wait before destroying the event (checked with assertions).

Member Function Documentation

◆ Reset()

void Stroika::Foundation::Execution::WaitableEvent::Reset ( )

Set the event to the non-signaled state

Note: This COULD have been called 'UnSet'.; Not Cancelation Point

Definition at line 51 of file WaitableEvent.inl.

◆ GetIsSet()

bool Stroika::Foundation::Execution::WaitableEvent::GetIsSet ( ) const

noexcept

This checks if the event is currently in a triggered state. Regardless of the type of event (auto-reset or not) - this does not change the trigger state.

Note: Not Cancelation Point

Definition at line 56 of file WaitableEvent.inl.

◆ PeekIsSet()

bool Stroika::Foundation::Execution::WaitableEvent::PeekIsSet ( ) const

noexcept

This checks if the event is currently in a triggered state. Regardless of the type of event (auto-reset or not) - this does not change the trigger state.

Note: NOT THREADSAFE - same as GetIsSet() except avoids the lock, so will be reported by TSAN (for example) as a race (cuz it is). JUST INTENDED for debug trace messages (so used in ToString).

Because of this - if testing with TSAN (thread sanitizer) - probably best to prefix functions calling this with Stroika_Foundation_Debug_ATTRIBUTE_NO_SANITIZE_THREAD

Note: Not Cancelation Point

Definition at line 60 of file WaitableEvent.inl.

◆ Set()

void WaitableEvent::Set ( )

Set the event to the signaled state.

Note: This COULD have been called 'Signal', or 'SetSignaled'.; Not Cancelation Point, but can throw (cuz uses mutex lock which can throw)

Definition at line 95 of file WaitableEvent.cpp.

◆ Wait()

void Stroika::Foundation::Execution::WaitableEvent::Wait ( Time::DurationSeconds timeout = Time::kInfinity )

Simple wait. Can use operator HANDLE() to do fancier waits. timeout can be negative (which triggers an immediate exception).

Throws a timeout (

See also: Execution::ThrowError (errc::timed_out)) if the timeout is exceeded.

Note: Wait (0) will always throw a timeout regardless of the state of the event/trigger

See also: WaitQuietly (); PeekIsSet ()

Note: Cancelation Point

Definition at line 64 of file WaitableEvent.inl.

◆ WaitQuietly()

auto Stroika::Foundation::Execution::WaitableEvent::WaitQuietly ( Time::DurationSeconds timeout = Time::kInfinity )

Wait the given period of time, and return true if event occurred (Set called), and false on timeout. This is mostly useful if we want a wait, for advisory purposes (say to avoid races), but don't want an exception as its not an issue to handle specially.

Returns: true (kWaitQuietlySetResult) if event signaled/occurred, and false (kWaitQuietlyTimeoutResult) if timeout

Note: WaitQuietly (0) will always return false regardless of the state of the event/trigger; WaitQuietly() can raise exceptions, but only Thread::AborttException

See also: Wait (); WaitUntil (); WaitUntilQuietly (); WaitQuietlyAndReset (); PeekIsSet ()

Note: Cancelation Point

Definition at line 68 of file WaitableEvent.inl.

◆ WaitUntil()

void Stroika::Foundation::Execution::WaitableEvent::WaitUntil ( Time::TimePointSeconds timeoutAt )

Throws a timeout (

See also: Execution::ThrowError (errc::timed_out)) if the event is not signaled before timeoutAt is exceeded (includes when reached).; Wait (); WaitQuietly (); WaitUntilQuietly (); WaitUntilAndReset ()

Note: Cancelation Point

Definition at line 72 of file WaitableEvent.inl.

◆ WaitUntilQuietly()

auto Stroika::Foundation::Execution::WaitableEvent::WaitUntilQuietly ( Time::TimePointSeconds timeoutAt )

Note: WaitUntilQuietly() can raise exceptions, but only Thread::AbortException

Returns: true (kWaitQuietlySetResult) if event signaled/occurred, and false (kWaitQuietlyTimeoutResult) if timeout

Note - unlike condition variable - will not return with spurious wakeup. So a return of triggered means it definitely was triggered!

See also: Wait (); WaitQuietly (); WaitUntil (); WaitUntilQuietlyAndReset ()

Note: Cancelation Point

Definition at line 76 of file WaitableEvent.inl.

◆ WaitAndReset()

void Stroika::Foundation::Execution::WaitableEvent::WaitAndReset ( Time::Duration timeout = Time::kInfinity )

See also: Wait (); WaitUntil (); WaitQuietly (); WaitUntilQuietly (); Reset ()

Note: Cancelation Point

Unclear if this is a good idea. Its a preplacement for 'auto-reset' events in Stroika v2.1.

Definition at line 80 of file WaitableEvent.inl.

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

Public Types

Public Member Functions