tamer::event< T0, T1, T2, T3 > Class Template Reference

A future occurrence. More...

#include <tamer/tamer.hh>

Public Types
typedef std::tuple< T0, T1, T2, T3 >	results_tuple_type

Public Member Functions
	event () noexcept
	Default constructor creates an empty event.
	event (T0 &x0, T1 &x1, T2 &x2, T3 &x3) noexcept
	Construct an empty four-result event on rendezvous r.
	event (results_tuple_type &xs) noexcept
	Construct an empty four-result event on rendezvous r.
	event (const event< T0, T1, T2, T3 > &x) noexcept
	Copy-construct event from x.
	event (event< T0, T1, T2, T3 > &&x) noexcept
	Move-construct event from x.
	~event () noexcept
	Destroy the event instance.
	operator bool () const
	Test if event is active.
bool	empty () const
	Test if event is empty.
void	operator() (T0 v0, T1 v1, T2 v2, T3 v3)
	Trigger event.
void	trigger (T0 v0, T1 v1, T2 v2, T3 v3)
	Trigger event.
void	tuple_trigger (const results_tuple_type &vs)
	Trigger event.
void	unblock () noexcept
	Unblock event.
template<size_t I>
void	set_result (typename std::tuple_element< I, results_tuple_type >::type vi)
void	at_trigger (const event<> &e)
	Register a trigger notifier.
void	at_trigger (event<> &&e)
event	unblocker () const noexcept
	Return a no-result event for the same occurrence as e.
event< T0, T1, T2, T3 > &	operator= (const event< T0, T1, T2, T3 > &x) noexcept
	Assign this event to x.
event< T0, T1, T2, T3 > &	operator= (event< T0, T1, T2, T3 > &&x) noexcept
	Move-assign this event to x.
event< T0, T1, T2, T3 > &	operator+= (event< T0, T1, T2, T3 > x)
const char *	file_annotation () const
int	line_annotation () const
event< T0, T1, T2, T3 > &	__instantiate (tamerpriv::abstract_rendezvous &r, uintptr_t rid, const char *file=nullptr, int line=0)
tamerpriv::simple_event *	__get_simple () const
tamerpriv::simple_event *	__release_simple ()

Detailed Description

template<typename T0, typename T1, typename T2, typename T3>
class tamer::event< T0, T1, T2, T3 >

A future occurrence.

An event object represents a future occurrence, such as the completion of a network read. When the occurrence becomes ready—for instance, a packet arrives—the event object is triggered via its trigger() method (or, equivalently, by operator()()). Code can block until an event triggers using twait special forms.

Events have from zero to four results of arbitrary type. Result values are set when the event is triggered and passed to the function waiting for the event. For example, an event of type event<int, char*, bool> has three results. Most constructors for event<int, char*, bool> take three reference arguments of types int&, char*&, and bool&. To trigger the event, the caller supplies actual values for these results.

Events may be active or empty. An active event is ready to be triggered, while an empty event has already been triggered. Events can be triggered at most once; triggering an empty event has no additional effect. The empty() and operator bool() member functions test whether an event is empty or active.

    Constructors               Default constructor
         |                             |
         v                             v
       ACTIVE   ==== trigger ====>   EMPTY   =====+
                                       ^       trigger
                                       |          |
                                       +==========+

Multiple event objects may refer to the same underlying occurrence. Triggering an event can thus affect several event objects. For instance, after an assignment e1 = e2, e1 and e2 refer to the same occurrence. Either e1.trigger() or e2.trigger() would trigger the underlying occurrence, making both e1 and e2 empty.

The unblocker() method returns a version of the event with no results. The unblocker().trigger() method triggers the underlying occurrence, but does not change the caller’s result values. For instance:

tvars { event<int> e; int x = 0; }
 
twait {
   e = make_event(x);
   e.trigger(1);
}
printf("%d\n", x);        // will print 1
 
twait {
   e = make_event(x);
   e.unblocker().trigger();
   e.trigger(2);               // ignored
}
printf("%d\n", x);        // will print 1

Tamer automatically triggers the unblocker for any active event when the last reference to its underlying occurrence is deleted. Leaking an active event is usually considered a programming error, and a message is printed at run time to indicate that an event triggered abnormally. For example, the following code:

twait { (void) make_event(); }

will print a message like "<tt>ex4.tt:11: dropping last reference to active event</tt>". However, it is sometimes convenient to rely on this triggering behavior, so the error message is turned off for rendezvous declared as volatile:

twait volatile { (void) make_event(); }

Deleting the last reference to an empty event is not an error and does not produce an error message.

An event's trigger notifiers are triggered when the event itself is triggered. A trigger notifier is simply an event<>.

Events are usually created with the make_event() helper function, which automatically detects the right type of event to return.

Constructor & Destructor Documentation

event() [1/4]

template<typename T0, typename T1, typename T2, typename T3>

tamer::event< T0, T1, T2, T3 >::event ( T0 & x0, T1 & x1, T2 & x2, T3 & x3 )

inlinenoexcept

Construct an empty four-result event on rendezvous r.

Parameters

x0	First result.
x1	Second result.
x2	Third result.
x3	Fourth result.

event() [2/4]

template<typename T0, typename T1, typename T2, typename T3>

tamer::event< T0, T1, T2, T3 >::event ( results_tuple_type & xs )

inlinenoexcept

Construct an empty four-result event on rendezvous r.

Parameters

xs	Result tuple.

event() [3/4]

template<typename T0, typename T1, typename T2, typename T3>

tamer::event< T0, T1, T2, T3 >::event ( const event< T0, T1, T2, T3 > & x )

inlinenoexcept

Copy-construct event from x.

Parameters

x	Source event.

References event().

event() [4/4]

template<typename T0, typename T1, typename T2, typename T3>

tamer::event< T0, T1, T2, T3 >::event ( event< T0, T1, T2, T3 > && x )

inlinenoexcept

Move-construct event from x.

Parameters

x	Source event.

References event().

~event()

template<typename T0, typename T1, typename T2, typename T3>

tamer::event< T0, T1, T2, T3 >::~event ( )

inlinenoexcept

Destroy the event instance.

Note

The underlying occurrence is canceled if this event was the last remaining reference.

Referenced by tamer::event< int >::operator=().

Member Function Documentation

operator bool()

template<typename T0, typename T1, typename T2, typename T3>

tamer::event< T0, T1, T2, T3 >::operator bool ( ) const

inlineexplicit

Test if event is active.

Returns

True if event is active, false if it is empty.

References event().

empty()

template<typename T0, typename T1, typename T2, typename T3>

bool tamer::event< T0, T1, T2, T3 >::empty ( ) const

inline

Test if event is empty.

Returns

True if event is empty, false if it is active.

Referenced by tamer::event< int >::operator=().

operator()()

template<typename T0, typename T1, typename T2, typename T3>

void tamer::event< T0, T1, T2, T3 >::operator() ( T0 v0, T1 v1, T2 v2, T3 v3 )

inline

Trigger event.

Parameters

v0	First trigger value.
v1	Second trigger value.
v2	Third trigger value.
v3	Fourth trigger value.

Does nothing if event is empty.

Referenced by tamer::event< int >::operator=(), trigger(), and tuple_trigger().

trigger()

template<typename T0, typename T1, typename T2, typename T3>

void tamer::event< T0, T1, T2, T3 >::trigger ( T0 v0, T1 v1, T2 v2, T3 v3 )

inline

Trigger event.

Parameters

v0	First trigger value.
v1	Second trigger value.
v2	Third trigger value.
v3	Fourth trigger value.

Does nothing if event is empty.

Note

This is a synonym for operator()().

References operator()().

Referenced by tamer::event< int >::operator=(), and tamer::tcp_listen().

tuple_trigger()

template<typename T0, typename T1, typename T2, typename T3>

void tamer::event< T0, T1, T2, T3 >::tuple_trigger ( const results_tuple_type & vs )

inline

Trigger event.

Parameters

vs	Trigger values.

Does nothing if event is empty.

Note

This is a synonym for trigger().

References operator()().

Referenced by tamer::event< int >::operator=().

unblock()

template<typename T0, typename T1, typename T2, typename T3>

void tamer::event< T0, T1, T2, T3 >::unblock ( )

inlinenoexcept

Unblock event.

Like trigger(), but does not change results.

Does nothing if event is empty.

Referenced by tamer::event< int >::operator=().

at_trigger() [1/2]

template<typename T0>

void tamer::event< T0 >::at_trigger ( const event<> & e )

inline

Register a trigger notifier.

Parameters

e	Trigger notifier.

If this event is empty, e is triggered immediately. Otherwise, when this event is triggered, triggers e.

Referenced by tamer::map(), and tamer::event< int >::operator=().

at_trigger() [2/2]

template<typename T0>

void tamer::event< T0 >::at_trigger ( event<> && e )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

unblocker()

template<typename T0>

event tamer::event< T0 >::unblocker ( ) const

inlinenoexcept

Return a no-result event for the same occurrence as e.

Returns

New event.

The returned event refers to the same occurrence as this event, so triggering either event makes both events empty. The returned event has no results, however, and unblocker().trigger() will leave this event's results unchanged.

References event().

Referenced by tamer::add_signal(), tamer::add_timeout(), tamer::map(), tamer::event< int >::operator=(), tamer::with_signal(), tamer::with_signal(), and tamer::with_timeout().

operator=() [1/2]

template<typename T0, typename T1, typename T2, typename T3>

event< T0, T1, T2, T3 > & tamer::event< T0, T1, T2, T3 >::operator= ( const event< T0, T1, T2, T3 > & x )

inlinenoexcept

Assign this event to x.

Parameters

x	Source event.

References event().

Referenced by tamer::event< int >::operator=().

operator=() [2/2]

template<typename T0, typename T1, typename T2, typename T3>

event< T0, T1, T2, T3 > & tamer::event< T0, T1, T2, T3 >::operator= ( event< T0, T1, T2, T3 > && x )

inlinenoexcept

Move-assign this event to x.

Parameters

x	Source event.

References event().

---

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

• tamer/event.hh