EVENTSETs

An Overview

It is fairly common, in C programming, to want to do something like this:

// Setting up
create_several_events();

// The main loop
while (not_finished)
{
	wait_until_at_least_one_event_is_signalled();
	for (each signalled event, e)
	{
		do_something(e);
	}
}

EVENTSETs provide a way to do exactly that.

Actually, EVENTSETs do not do the setting up - you still have to create all the events yourself. But the rest of it is all neatly encapsulated within the EVENTSET object.

An EVENTSET is an object. Since this is C and not C++, and C doesn't have objects per se, EVENTSET is implemented as a struct together with a set of functions. There is also a second struct, called ACTIVE_JOB, which represents a single event. For each event you want to handle, you create an ACTIVE_JOB, and insert it into the EVENTSET. The ACTIVE_JOB contains not only the event, but also a callback to the handling function,called do_something() in the pseudocode above.

So why are EVENTSETs better than hand-coding the pseudocode above? What's wrong with WaitForMultipleObjects()?

Well, apart from being non-portable, WaitForMultipleObjects() also gives you almost no information about which events have been signalled: you have to assume that all (or at least, a range) of them have been signalled, just in case.

The EVENTSET approach is better.

In fact, the whole of the main loop is implemented in a single function: eventset_wait(). The EVENTSET mechanism requires that eventset_wait() be run in another thread, called the worker thread in this documentation, which you are responsible for creating. The initial thread, called the management thread in this documentation, does all the setting up and shutting down.

For more detail, read the rest of the documentation:

Structures

EVENTSET
ACTIVE_JOB

Functions

eventset()
eventset_delete()
eventset_dtor()
eventset_insert()
eventset_stop()
eventset_wait()

Callbacks

handler()
cleanup_fn()

EVENTSETs are a good way to organise waiting on multiple Prosody channels.