gul17::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
Trigger trigger;
 
...
 
// 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
Trigger trigger;
 
...
 
// 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
Trigger &	operator= (const Trigger &)=delete
Trigger &	operator= (Trigger &&)=delete
GUL_EXPORT	operator bool () const noexcept
	Return if the trigger is high==true or low==false.
GUL_EXPORT Trigger &	operator= (bool interrupt) noexcept
	Set the trigger to high==true or low==false.
GUL_EXPORT void	reset () noexcept
	Set the trigger to low (false).
GUL_EXPORT void	trigger () noexcept
	Set the trigger to high (true).
GUL_EXPORT void	wait () const
	Suspend execution of the current thread until the trigger goes high (true).
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.
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.

Member Function Documentation

operator bool()

gul17::Trigger::operator bool ( ) const

noexcept

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

Example:

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

References gul17::bit_set().

operator=()

Trigger & gul17::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.

References gul17::bit_set().

trigger()

void gul17::Trigger::trigger ( )

noexcept

Set the trigger to high (true).

This causes any waiting threads to resume.

References gul17::bit_set().

Referenced by ~Trigger().

wait()

void gul17::Trigger::wait

(

)

const

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

Execution is also resumed if the object is destructed.

References gul17::bit_set().

wait_for()

template<class Rep , class Period >

bool gul17::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

Clock	The type of the underlying clock, e.g. std::chrono::system_clock.
Duration	The duration type to be used, typically Clock::duration.

Parameters

delta_t

A 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.

References gul17::bit_set().

wait_until()

template<class Clock , class Duration >

bool gul17::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

Clock	The type of the underlying clock, e.g. std::chrono::system_clock.
Duration	The duration type to be used, typically Clock::duration.

Parameters

t	A 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.

References gul17::bit_set().

---

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

• Trigger.h
• Trigger.cc