General Utility Library for C++14  2.7
Public Member Functions | List of all members
gul14::Trigger Class Reference

Detailed Description

A class that allows sending triggers and waiting for them across different threads.

A Trigger object is similar to a digital electric trigger signal. Its state is either high (true) or low (false), and actions are triggered when it is at the high level - that is to say, an arbitrary number of threads can wait until the Trigger object becomes true. Internally, a Trigger is little more than a wrapper around a mutex, a condition variable, and a boolean.

There are two ways to use a Trigger:

Using bools

To stay in the picture of a digital electric trigger line, high and low states can be assigned and tested like booleans. This allows for easy communication of state:

// Data shared between threads
...
// Thread 1
trigger.wait(); // wait until trigger becomes true
while (trigger)
{
cout << "high\n";
sleep(10ms);
}
cout << "low\n";
...
// Thread 2
trigger = true;
sleep(100ms);
trigger = false;

Using member functions

Sometimes assignment of boolean values does not fit well to a specific task. The member functions trigger() and reset() are identical to assigning true and false, respectively:

// Data shared between threads
...
// Thread 1
while (true)
{
trigger.wait();
cout << "Triggered!\n";
trigger.reset();
}
...
// Thread 2
trigger.trigger();
sleep(100ms);
trigger.trigger();
sleep(100ms);
trigger.trigger();

The unconditional wait() stops execution until the Trigger becomes true or is destructed. If a timeout is required, wait_for() or wait_until() can be used instead.

Note
Trigger is a thread-safe, self-synchronizing class; it is neither copyable nor movable.

#include <Trigger.h>

Public Member Functions

 Trigger (bool triggered=false) noexcept
 Constructor.
 
GUL_EXPORT ~Trigger () noexcept
 Destructor: Send a final trigger signal so that all threads waiting on this object have a chance to stop.
 
 Trigger (const Trigger &)=delete
 Not copyable and not movable.
 
 Trigger (Trigger &&)=delete
 
Triggeroperator= (const Trigger &)=delete
 
Triggeroperator= (Trigger &&)=delete
 
GUL_EXPORT operator bool () const noexcept
 Return if the trigger is high==true or low==false. More...
 
GUL_EXPORT Triggeroperator= (bool interrupt) noexcept
 Set the trigger to high==true or low==false. More...
 
GUL_EXPORT void reset () noexcept
 Set the trigger to low (false).
 
GUL_EXPORT void trigger () noexcept
 Set the trigger to high (true). More...
 
GUL_EXPORT void wait () const
 Suspend execution of the current thread until the trigger goes high (true). More...
 
template<class Rep , class Period >
bool wait_for (const std::chrono::duration< Rep, Period > &delta_t) const
 Suspend execution of the current thread until the trigger goes high (true) or at least the given time span has passed. More...
 
template<class Clock , class Duration >
bool wait_until (const std::chrono::time_point< Clock, Duration > &t) const
 Suspend execution of the current thread until the trigger goes high (true) or the given time point has been passed. More...
 

Member Function Documentation

◆ operator bool()

gul14::Trigger::operator bool ( ) const
noexcept

Return if the trigger is high==true or low==false.

Example:

if (!t) // t returns false
cout << "Trigger is low\n";
t.trigger();
if (t) // t now returns true
cout << "Trigger is now high\n";

◆ operator=()

Trigger & gul14::Trigger::operator= ( bool  interrupt)
noexcept

Set the trigger to high==true or low==false.

Setting it to true will cause any waiting threads to resume.

◆ trigger()

void gul14::Trigger::trigger ( )
noexcept

Set the trigger to high (true).

This causes any waiting threads to resume.

Referenced by ~Trigger().

◆ wait()

void gul14::Trigger::wait ( ) const

Suspend execution of the current thread until the trigger goes high (true).

Execution is also resumed if the object is destructed.

◆ wait_for()

template<class Rep , class Period >
bool gul14::Trigger::wait_for ( const std::chrono::duration< Rep, Period > &  delta_t) const
inline

Suspend execution of the current thread until the trigger goes high (true) or at least the given time span has passed.

Execution is also resumed if the object is destructed.

Template Parameters
ClockThe type of the underlying clock, e.g. std::chrono::system_clock.
DurationThe duration type to be used, typically Clock::duration.
Parameters
delta_tA time span to wait. If the trigger still has not become true after (at least) this time, the function returns false.
Returns
the state of the trigger at the end of the call. If this is false, the function has exited due to timeout.
Note
For many applications, the free function sleep() is easier to use.

Referenced by gul14::sleep().

◆ wait_until()

template<class Clock , class Duration >
bool gul14::Trigger::wait_until ( const std::chrono::time_point< Clock, Duration > &  t) const
inline

Suspend execution of the current thread until the trigger goes high (true) or the given time point has been passed.

Execution is also resumed if the object is destructed.

Template Parameters
ClockThe type of the underlying clock, e.g. std::chrono::system_clock.
DurationThe duration type to be used, typically Clock::duration.
Parameters
tA time point after which the function should stop waiting.
Returns
the state of the trigger at the end of the call. If this is false, the function has exited due to timeout.
Note
For many applications, the free function sleep() is easier to use.

The documentation for this class was generated from the following files:
gul14::Trigger::Trigger
Trigger(bool triggered=false) noexcept
Constructor.
Definition: Trigger.h:108
gul14::Trigger::trigger
GUL_EXPORT void trigger() noexcept
Set the trigger to high (true).
Definition: Trigger.cc:60
gul14::sleep
bool sleep(const std::chrono::duration< Rep, Period > &duration, const Trigger &trg)
Sleep for at least the given time span, with the option of being woken up from another thread.
Definition: time_util.h:109