[Swan-dev] typing libevent callback functions

[D. Hugh Redelmeier]

Getting callback functions right is tricky.  One tool that can detect
some problems is the C type system.

This approach was used with crypto request continuations.  See how the
type crypto_req_cont_func is used.

I think that this technique/convention should be used for libevent
callbacks.

It requires a typedef for callback functions.

Unfortunately, libevent2's event.h declares a type that is called
event_callback_fn but is really a POINTER to a function:
  typedef void (*event_callback_fn)(evutil_socket_t, short, void *);

We have to provide our own typedef:
  typedef void event_callback_routine(evutil_socket_t fd, short events, void *arg);
Notice that I've included the normal argument names: I think that it
makes their meaning clearer.

We should declare each callback function with this type.  That's how
to get the compiler to enforce the type matching requirements.  It
also is a flag to the reader that the function is a callback function.

extern event_callback_routine do_read_cb;

Unfortunately you cannot define the functions using this type because
a function definition needs an explicit parameter list.

void do_read(evutil_socket_t fd, short events, void *arg) {
	/* whatever */
}

I suggest that each callback function use the same names for formal
parameters.  (This is not currently the case.)

Here's a list of the callback functions used with pluto_event_new:
    kernel_process_msg_cb
    kernel_process_queue_cb
    comm_handle_cb
    handle_helper_answer_cb
    timer_event_cb