libfilezilla
Public Member Functions | Public Attributes | Friends | List of all members
event_handler Class Referenceabstract

Simple handler for asynchronous event processing. More...

#include <event_handler.hpp>

Inheritance diagram for event_handler:
Inheritance graph
[legend]
Collaboration diagram for event_handler:
Collaboration graph
[legend]

Public Member Functions

 event_handler (event_loop &loop)
 
 event_handler (event_handler const &h)
 
event_handleroperator= (event_handler const &)=delete
 
void remove_handler ()
 Deactivates handler, removes all pending events and stops all timers for this handler. More...
 
virtual void operator() (event_base const &)=0
 Called by the event loop in the worker thread with the event to process. More...
 
template<typename T , typename... Args>
void send_event (Args &&... args)
 Sends the passed event asynchronously to the handler. More...
 
template<typename T >
void send_event (T *evt)
 
timer_id add_timer (monotonic_clock const &deadline, duration const &interval={})
 Adds a timer, returns the timer id. More...
 
timer_id add_timer (duration const &interval, bool one_shot)
 Adds a timer, returns the timer id. More...
 
void stop_timer (timer_id id)
 
timer_id stop_add_timer (timer_id id, monotonic_clock const &deadline, duration const &interval={})
 
timer_id stop_add_timer (timer_id id, duration const &interval, bool one_shot)
 

Public Attributes

event_loopevent_loop_
 

Friends

class event_loop
 

Detailed Description

Simple handler for asynchronous event processing.

Usage example:

struct foo_event_type{}; // Any uniquely named type that's not implicitly convertible
struct bar_event_type{};
class my_handler final : public fz::event_handler
{
public:
my_handler(fz::event_loop& loop)
: fz::event_handler(loop)
{}
virtual ~my_handler()
{
// It is imperative to call remove_handler
}
void foo(int v, std::string const& s) {
std::cout << "foo called with:" << s << v;
}
void bar() {
std::cout << "bar called";
}
virtual void operator()(event_base const& ev) {
// Tip: Put in order of decreasing frequency
fz::dispatch<foo_event, bar_event>(ev, this, &my_handler::foo, &my_handler::bar);
}
};
my_handler h(loop);
h.SendEvent<foo_event>(42, "Don't Panic");
Simple handler for asynchronous event processing.
Definition: event_handler.hpp:55
void remove_handler()
Deactivates handler, removes all pending events and stops all timers for this handler.
virtual void operator()(event_base const &)=0
Called by the event loop in the worker thread with the event to process.
A threaded event loop that supports sending events and timers.
Definition: event_loop.hpp:34
This is the recommended event class.
Definition: event.hpp:68
The namespace used by libfilezilla.
Definition: apply.hpp:17
Examples
events.cpp, https.cpp, nonblocking_process.cpp, and timer_fizzbuzz.cpp.

Member Function Documentation

◆ add_timer() [1/2]

timer_id add_timer ( duration const &  interval,
bool  one_shot 
)

Adds a timer, returns the timer id.

Once the interval expires, you get a timer event from the event loop.

One-shot timers are deleted automatically

For periodic timers, the next event is scheduled right before the callback is called. If multiple intervals expire before the timer fires, e.g. under heavy load, only one event is sent.

If multiple different timers have expired, the order in which the callbacks are executed is unspecified, there is no fairness guarantee.

Timers take precedence over other queued events.

Note
High-frequency timers doing heavy processing can starve other timers and queued events.

◆ add_timer() [2/2]

timer_id add_timer ( monotonic_clock const &  deadline,
duration const &  interval = {} 
)

Adds a timer, returns the timer id.

Once the deadline is reached, you get a timer event from the event loop. If the deadline is empty, no timer is actually added and the returned timer id is 0.

If the interval is empty, timers are deleted automatically, otherwise the interval is the period of the timer after the deadline is reached.

For periodic timers, the next event is scheduled right before the callback is called. If multiple intervals expire before the timer fires, e.g. under heavy load, only one event is sent.

If multiple different timers have expired, the order in which the callbacks are executed is unspecified, there is no fairness guarantee.

Timers take precedence over other queued events.

Note
High-frequency timers doing heavy processing can starve other timers and queued events.
Examples
timer_fizzbuzz.cpp.

◆ operator()()

virtual void operator() ( event_base const &  )
pure virtual

Called by the event loop in the worker thread with the event to process.

Override in your derived class.

Consider using dispatch inside your function.

Examples
events.cpp, https.cpp, nonblocking_process.cpp, and timer_fizzbuzz.cpp.

◆ remove_handler()

void remove_handler ( )

Deactivates handler, removes all pending events and stops all timers for this handler.

When function returns, handler is not in its callback anymore.

Warning
You MUST call remove_handler no later than inside the destructor of the most derived class.
Examples
events.cpp, https.cpp, nonblocking_process.cpp, and timer_fizzbuzz.cpp.

◆ send_event()

void send_event ( Args &&...  args)
inline

Sends the passed event asynchronously to the handler.

Can be called from any thread.

All events are processed in the order they are sent, excluding possible races between threads.

◆ stop_add_timer() [1/2]

timer_id stop_add_timer ( timer_id  id,
duration const &  interval,
bool  one_shot 
)

Stops the given timer, then adds a new one. Returns the timer id of the newly added timer.

It behaves as-if the two following calls were made in sequence:

stop_timer(id);
return add_timer(interval, one_shot);

◆ stop_add_timer() [2/2]

timer_id stop_add_timer ( timer_id  id,
monotonic_clock const &  deadline,
duration const &  interval = {} 
)

Stops the given timer, then adds a new one. Returns the timer id of the newly added timer.

It behaves as-if the two following calls were made in sequence:

stop_timer(id);
return add_timer(deadline, interval);

◆ stop_timer()

void stop_timer ( timer_id  id)

Stops the given timer.

One-shot timers that have fired stop automatically and do not need to be stopped.

Examples
timer_fizzbuzz.cpp.

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