evthr/README

Libevthr is an API which manages threads and thread-pools in an event based
manner. This API requires libevent with threading support.

Libevthr works a bit differently than most thread management systems. Instead of
conditional signalling and some type of pre-thread queue, Libevthr uses a
deferral type mechanism. That is, a thread is always running, abstracted to a
point where you "defer" your function *into* a thread. 

For example you can start up a single thread with a backlog of 10 (a backlog
being the max number of outstanding callbacks to run within the thread), and
execute a function you would like to run inside the thread one or many times.
The act of deferrals is non-blocking. 

Example Code for evthrs:

	evthr_t * thr = evthr_new(10, NULL);
	
	if (evthr_start(thr) < 0) {
		exit(1);
	}

	evthr_defer(thr, my_cb_1, NULL);
	evthr_defer(thr, my_cb_2, NULL);
	evthr_defer(thr, my_cb_3, NULL);

	sleep(n_seconds);

	evthr_stop(thr);

Libevthr also has the ability to create pools using the same methods that a 
single evthr has. For example, if you would like to create 10 threads, each
with a backlog of 5: 

	evthr_pool_t * thr_pool = evthr_pool_new(10, 5, NULL);

	if (evthr_pool_start(thr_pool) < 0) {
		exit(1);
	}

	evthr_pool_defer(thr_pool, my_cb_1, NULL);
	evthr_pool_defer(thr_pool, my_cb_2, NULL);
	evthr_pool_defer(thr_pool, my_cb_3, NULL);

Your callback functions which you defer must be of type "evthr_cb", or 
"void cb_name(void * arg, void * shared)". In this case, the "arg" variable is
the data you passed as the third argument to either evthr_pool_defer, or
evthr_defer. The "shared" variable is the data that was either the second
variable in evthr_new(), or the third variable in evthr_pool_new().

The gist of this is to allow a global dataset, along with deferred specific
data.

See test.c for a quick example.