ircd/api/events

Overview
The IRC server is built around an event loop. Until the u2.10.11 release (which is what ircd-darenet 1.x is based off of), this event loop has been rather ad-hoc; timed events are hard-coded in, signals are handled inside the signal handler, etc. All of this changed with u2.10.11. A new subsystem, the events subsystem, was introduced; the new subsystem contains a generalization of the concept of an event. An event is a signal, the expiration of a timer, or some form of activity on a network socket. This new subsystem has the potential to vastly simplify the code that is arguably the core of any network program, and makes it much simpler to support more exotic forms of network activity monitoring than the conventional select and poll calls.

The primary concepts that the events subsystem works with are the "event," represented by a, and the "generator." There are three types of generators: sockets, represented by a ; signals, represented by a  ; and timers, represented by. Each of these generators will be described in turn.

Signals
The signal is perhaps the simplest generator in the entire events subsystem. Basically, instead of setting a signal handler, the function  is called, specifying a function to be called when a given signal is detected. Most importantly, that call-back function is called outside the context of a signal handler, permitting the call-back to use more exotic functions that are anathema within a signal handler, such as. Once a call-back for a signal has been established, it cannot be deleted; this design decision was driven by the fact that ircd never changes its signal handlers.

Whenever a signal is received, an event of type  is generated, and that event is passed to the event call-back function specified in the   call.

Timers
Execution of the call-back functions for a timer occur when that timer expires; when a timer expires depends on the type of timer and the expiration time that was used for that timer. A  timer, for instance, expires at exactly the time given as the expiration time. This time is a standard UNIX  value, measuring seconds since the UNIX epoch. The  timer type is complemented by the   timer; the time passed as its expiration time is relative to the current time. If a  is given an expiration time of 5, for instance, it will expire 5 seconds after the present time. Internally,  timers are converted into   timers, with the expiration time adjusted by addition of the current time.

These two types of timers,  and , are single-shot timers. Once they expire, they are removed from the timer list unless re-added by the event call-back or through some other mechanism. There is another type of timer, however, the  timer, that is not removed from the timer list. timers are similar to  timers, in that one passes in the expire time as a relative number of seconds, but when they expire, they are re-added to the timer list with the same relative expire time. This means that a  timer with an expire time of 5 seconds that is set at 11:50:00 will have its call-back called at 11:50:05, 11:50:10, 11:50:15, and so on.

Timers have to be run by the event engines explicitly by calling  on the generator list passed to the engine event loop. In addition, engines may determine the next (absolute) time that a timer needs to be run by calling the  macro; this may be used to set a timeout on the engine's network activity monitoring function. Engines are described in detail below.

When a timer expires, an event of  is generated, and the call-back function is called. When a timer is destroyed, either as the result of an expiration or as result of an explicit  call, am event of   is generated, notifying the call-back that the   can be deallocated.

Sockets
Perhaps the most complicated event generator in all of the event subsystem is the socket, as described by. This single classification covers datagram sockets and stream sockets. To differentiate the different kinds of sockets, there is a socket state associated with each socket. The available states are, which indicates that a particular socket is in the process of completing a non-blocking  ;  , which indicates that a particular socket is a listening socket;  , which is the state of every other stream socket;  , which is an ordinary datagram socket, and  , which describes a connected datagram socket. The  state is for the internal use of the event subsystem and will not be described here.

In addition to the socket states, there is also an event mask for each socket; this set of flags is used to tell the events subsystem what events the application is interested in for the socket. For  and   sockets, this events mask has no meaning, but on the other socket states, the event mask is used to determine if the application is interested in readable  or writable  indications.

Most of the defined event types have to do with socket generators. When a socket turns up readable, for instance, an event type  is generated. Similarly,  is generated when a socket can be written to. The  event is generated when a listening socket indicates that there is a connection to be accepted;   is generated when a non-blocking connect is completed. Finally, if an end-of-file indication is detected,  is generated, whereas if an error has occurred on the socket,   is generated. Of course, when a socket has been deleted by the  function, an event of   is generated when it is safe for the memory used by the   to be reclaimed.

Events
An event, represented by a, describes in detail all of the particulars of an event. Each event has a type, and an optional integer piece of data may be passed with some events -- in particular,  events pass the signal number, and   events pass the   value. The  also contains a pointer to the structure describing the generated event -- although it should be noted that the only way to disambiguate which type of generator is contained within the   is by which call-back function has been called.

All generators have a void pointer which can be used to pass important information to the call-back, such as a pointer to a. Additionally, generators have a reference count, and a union of a void pointer and an integer that should only be utilized by the event engine. Finally, there is also a field for flags, although the only flag of concern to the application (or the engine) is the active flag, which may be tested using the test macros described below.

Whatever the generator, the call-back function is a function returning nothing (void) and taking as its sole argument a pointer to. This call-back function may be implemented as a single switch statement that calls out to appropriate external functions as needed.

Engines
Engines implement the actual socket event loop, and may also have some means of receiving signal events. Each engine has a name, which should describe what its core function is; for instance, the engine based on the standard  function is named, simply, " ." Each engine must implement several call-backs which are used to initialize the engine, notify the engine of sockets the application is interested in, etc. All of this data is described by a single, which should be the only non-static variable or function in the engine's source file.

The engine's event loop, pointed to by the  field of the , must consist of a single while loop predicated on the global variable. Additionally, this loop's final statement must be a call to, to execute all timers that have become due. Ideally, this construction should be pulled out of each engine's and put in the   function of the events subsystem.

Reference Counts
As mentioned previously, all generators keep a reference count. Should  or   be called on a generator with a non-zero reference count, for whatever reason, the actual destruction of the generator will be delayed until the reference count again reaches zero. This is used by the event loop to keep sockets that it is currently referencing from being deallocated before it is done checking all pending events on them. To increment the reference count by one, call  on the generator; the corresponding macro   decrements the reference counts, and will automatically destroy the generator if the appropriate conditions are met.

Debugging Functions
It can be difficult to debug an engine if, say, a socket state can only be expressed as a meaningless number; therefore, when  is  'd, five number-to-name functions are also defined to make the debugging data more meaningful. These functions must only be called when  is  'd. Calling them from within   macro calls is safe; calling them from   calls is not.

Types, Enumerations, Structures, Macros and Functions
typedef void (*EventCallBack)(struct Event*);

The  type is used to simplify declaration of event call-back functions. It is used in,  , and. The event call-back should process the event, taking whatever actions are necessary. The function should be declared as returning void.

typedef int (*EngineInit)(int);

The  function takes an integer specifying the maximum number of sockets the event system is expecting to handle. This number may be used by the engine initialization function for memory allocation computations. If initialization succeeds, this function must return 1. If initialization fails, the function should clean up after itself and return 0. The events subsystem has the ability to fall back upon another engine, should an engine initialization fail. Needless to say, the engines based upon  and   should never fail in this way.

typedef void (*EngineSignal)(struct Signal*);

If an engine has the capability to directly detect signals, it should set the  field of   non-zero. When the application indicates interest in a particular signal, the  function will be called with the filled-in , in order to register interest in that signal with the engine.

typedef int (*EngineAdd)(struct Socket*);

All engines must define an  function, which is used to inform the engine of the application's interest in the socket. If the new socket cannot be accommodated by the engine for whatever reason, this function must return 0. Otherwise, the function must return 1, informing the events subsystem that the interest has been noted.

typedef void (*EngineState)(struct Socket*, enum SocketState new_state);

Sockets can change state. sockets, for instance, can become. Whenever a socket state changes, the engine is informed, since some states require different notification procedures than others. This is accomplished by calling the  function with the new state. The  passed to the engine will still have the old state, if the engine must reference that.

typedef void (*EngineEvents)(struct Socket*, unsigned int new_events);

Applications may only be interested in given events on a socket for a limited time. When the application's interest shifts, a new events mask is set for the socket. The engine is informed of this change by a call to its  function.

typedef void (*EngineDelete)(struct Socket*);

Eventually, an application will close all the sockets it has opened. When a socket is closed, and the corresponding  deleted with a call to , the   function will be called to notify the engine of the change.

typedef void (*EngineLoop)(struct Generators*);

The workhorse of the entire events subsystem is the event loop, implemented by each engine as the  function. This function is called with a single argument that may be passed to  to calculate the next time a timer will expire.

enum SocketState { SS_CONNECTING,	/* Connection in progress on socket */ SS_LISTENING,		/* Socket is a listening socket */ SS_CONNECTED,		/* Socket is a connected socket */ SS_DATAGRAM,		/* Socket is a datagram socket */ SS_CONNECTDG,		/* Socket is a connected datagram socket */ SS_NOTSOCK		/* Socket isn't a socket at all */ };</c>

This enumeration contains a list of all possible states a socket can be in. Applications should not use ; engines should treat it as a special socket state for non-sockets. The only event that should be watched for on a  in the   state is readability. This socket state is used to implement the fall-back signal event generation.

enum TimerType { TT_ABSOLUTE,		/* timer that runs at a specific time */ TT_RELATIVE,		/* timer that runs so many seconds in the future */ TT_PERIODIC		/* timer that runs periodically */ };</c>

The three possible timer types are defined by the  enumeration. More details can be found in the "Timers" section, above.

enum EventType { ET_READ,		/* Readable event detected */ ET_WRITE,		/* Writable event detected */ ET_ACCEPT,		/* Connection can be accepted */ ET_CONNECT,		/* Connection completed */ ET_EOF,		/* End-of-file on connection */ ET_ERROR,		/* Error condition detected */ ET_SIGNAL,		/* A signal was received */ ET_EXPIRE,		/* A timer expired */ ET_DESTROY		/* The generator is being destroyed */ };</c>

This enumeration contains all the types of events that can be generated by the events subsystem. The first 6 are generated by socket generators, the next by signal generators, and the next by timer generators. is generated by both socket and timer generators when the events subsystem is finished with the memory allocated by both.

struct Socket { struct GenHeader s_header;	/* Generator information */ enum SocketState s_state;	/* State socket's in */ unsigned int    s_events;	/* Events socket is interested in */ int             s_fd;	/* File descriptor for socket */ SSL*            ssl;         /* If not NULL, use SSL routines on socket */ };</c>
 * 1) ifdef USE_SSL
 * 1) endif                         /* USE_SSL */

This structure describes everything the events subsystem knows about a given socket. All of its fields may be accessed through the s_* macros described below.

struct Timer { struct GenHeader t_header;	/* Generator information */ enum TimerType  t_type;	/* What type of timer this is */ time_t          t_value;	/* Value timer was added with */ time_t          t_expire;	/* Time at which timer expires */ };</c>

The  structure describes everything the events subsystem knows about a given timer. Again, all of its fields may be accessed through the t_* macros described below.

struct Signal { struct GenHeader sig_header;	/* Generator information */ int             sig_signal;	/* Signal number */ };</c>

Signal generators are described by a. All of the fields of a  may be accessed by the sig_* macros described below.

struct Event { struct Event*      ev_next;	  /* Linked list of events on queue */ struct Event**     ev_prev_p;  /* Previous pointer to this event */ enum EventType     ev_type;	  /* Event type */ int                ev_data;    /* Extra data, like errno value */ union { struct GenHeader* gen_header; /* Generator header */ struct Socket*   gen_socket; /* Socket generating event */ struct Signal*   gen_signal; /* Signal generating event */ struct Timer*    gen_timer;  /* Timer generating event */ } ev_gen;	                 /* Object generating event */ };</c>

Each event is described by a. Its fields may be examined using the ev_* macros described below.

struct Generators { struct GenHeader* g_socket;	/* List of socket generators */ struct GenHeader* g_signal;	/* List of signal generators */ struct GenHeader* g_timer;	/* List of timer generators */ };</c>

Each engine is passed a list of all generators when the engine's  function is called. The only valid way to access this structure is via the  function described below.

struct Engine { const char*	eng_name;	/* a name for the engine */ EngineInit	eng_init;	/* initialize engine */ EngineSignal	eng_signal;	/* express interest in a signal */ EngineAdd	eng_add;	/* express interest in a socket */ EngineState	eng_state;	/* mention a change in state to engine */ EngineEvents	eng_events;	/* express interest in socket events */ EngineDelete	eng_closing;	/* socket is being closed */ EngineLoop	eng_loop;	/* actual event loop */ };</c>

Each engine is described by the  structure. Each engine must define all of the functions described above except for the  function, which is optional.

#define SOCK_EVENT_READABLE	0x0001	/* interested in readable */</c>

The  flag indicates to the engine that the application is interested in readability on this particular socket.

#define SOCK_EVENT_WRITABLE	0x0002	/* interested in writable */</c>

The  flag indicates to the engine that the application is interested in this socket being writable.

#define SOCK_EVENT_MASK		(SOCK_EVENT_READABLE | SOCK_EVENT_WRITABLE)</c>

may be used to extract only the event interest flags from an event interest set.

#define SOCK_ACTION_SET		0x0000	/* set interest set as follows */</c>

When  is called with a set of event interest flags and , the socket's event interest flags are set to those passed into.

#define SOCK_ACTION_ADD		0x1000	/* add to interest set */</c>

When  is used in a call to , the event interest flags passed in are added to the existing event interest flags for the socket.

#define SOCK_ACTION_DEL		0x2000	/* remove from interest set */</c>

When  is used in a call to , the event interest flags passed in are removed from the existing event interest flags for the socket.

#define SOCK_ACTION_MASK	0x3000	/* mask out the actions */</c>

is used to isolate the socket action desired.

<c>enum SocketState s_state(struct Socket* sock);</c>

This macro returns the state of the given socket.

<c>unsigned int s_events(struct Socket* sock);</c>

This macro returns the current event interest mask for a given socket. Note that if the socket is in the  or   states, this mask has no meaning.

<c>int s_fd(struct Socket* sock);</c>

This macro simply returns the file descriptor for the given socket.

<c>void* s_data(struct Socket* sock);</c>

When a  is initialized, data that the call-back function may find useful, such as a pointer to a , is stored in the. This macro returns that pointer.

<c>int s_ed_int(struct Socket* sock);</c>

Engines may find it convenient to associate an integer with a. This macro may be used to retrieve that integer or, when used as an lvalue, to assign a value to it. Engine data must be either an int or a void*; use of both is prohibited.

<c>void* s_ed_ptr(struct Socket* sock);</c>

Engines may find it convenient to associate a void* pointer with a. This macro may be used to retrieve that pointer or, when used as an lvalue, to assign a value to it. Engine data must be either an int or a void*; use of both is prohibited.

<c>int s_active(struct Socket* sock);</c>

A socket's active flag is set when initialized by, and is cleared immediately prior to generating an event of type. This may be used by the application to determine whether or not the socket is still in use by the events subsystem. If it is,  returns a non-zero value; otherwise, its value is 0.

<c>int socket_add(struct Socket* sock, EventCallBack call, void* data,	      enum SocketState state, unsigned int events, int fd);</c>

This function is called to add a socket to the list of sockets to be monitored. The sock parameter is a pointer to a  that is allocated by the application. The call parameter is a pointer to a function to process any events on the socket. The data parameter is for use of the socket call-back and may be zero. The state parameter must be one of the valid socket states. The events parameter must be a valid events interest mask--0, or the binary OR of  or. Finally, the fd parameter specifies the socket's file descriptor. This function returns 1 if successful or 0 otherwise.

<c>void socket_del(struct Socket* sock);</c>

When the application is no longer interested in a particular socket, it should call the  function. This function must be called no later than when the socket has been closed, to avoid attempting to call  or similar functions on closed sockets.

<c>void socket_state(struct Socket* sock, enum SocketState state);</c>

Occasionally, a socket's state will change. This function is used to inform the events subsystem of that change. Only certain state transitions are valid--a socket in the  or   states cannot change states, nor can an   socket change to some state other than. Of course,  sockets may change state only to , and   sockets may only change states to.

<c>void socket_events(struct Socket* sock, unsigned int events);</c>

When the application changes the events it is interested in, it uses  to notify the events subsystem of that change. The events parameter is the binary OR of one of,  , or   with an events mask. See the documentation for the SOCK_* macros for more information.

<c>const char* state_to_name(enum SocketState state);</c>

This function is defined only when  is  'd. It takes the given state and returns a string giving that state's name. This function may safely be called from  macros.

<c>const char* sock_flags(unsigned int flags);</c>

This function is defined only when  is  'd. It takes the given event interest flags and returns a string naming each of those flags. This function may safely be called from  macros, but may only be called once, since it uses function static storage to store the flag strings.

<c>int sig_signal(struct Signal* sig);</c>

This macro returns the signal number for the given.

<c>void* sig_data(struct Signal* sig);</c>

When a  is initialized, data that the call-back function may find useful is stored in the. This macro returns that pointer.

<c>int sig_ed_int(struct Signal* sig);</c>

Engines may find it convenient to associate an integer with a. This macro may be used to retrieve that integer or, when used as an lvalue, to assign a value to it. Engine data must be either an int or a void*; use of both is prohibited.

<c>void* sig_ed_ptr(struct Signal* sig);</c>

Engines may find it convenient to associate a void* pointer with a. This macro may be used to retrieve that pointer or, when used as an lvalue, to assign a value to it. Engine data must be either an int or a void*; use of both is prohibited.

<c>int sig_active(struct Signal* sig);</c>

A signal's active flag is set when initialized by. This may be used by the application to determine whether or not the signal has been initialized yet. If it is,  returns a non-zero value; otherwise, its value is 0.

<c>void signal_add(struct Signal* signal, EventCallBack call, void* data, int sig);</c>

This function is called to add a signal to the list of signals to be monitored. The signal parameter is a pointer is a pointer to a  that is allocated by the application. The call parameter is a pointer to a function to process any signal events. The data parameter is for use of the signal call-back and may be zero. The sig parameter is the integer value of the signal to be monitored.

<c>enum TimerType t_type(struct Timer* tim);</c>

This macro returns the type of the given timer.

<c>time_t t_value(struct Timer* tim);</c>

This macro returns the value that was used when the given timer was initialized by the events subsystem. It will contain an absolute time if the timer type is, and a relative time otherwise.

<c>time_t t_expire(struct Timer* tim);</c>

This macro returns the absolute time at which the timer will next expire.

<c>void* t_data(struct Timer* tim);</c>

When a  is initialized, data that the call-back function may find useful is stored in the. This macro returns that pointer.

<c>int t_ed_int(struct Timer *tim);</c>

Engines may find it convenient to associate an integer with a. This macro may be used to retrieve that integer or, when used as an lvalue, to assign a value to it. Engine data must be either an int or a void*; use of both is prohibited.

<c>void* t_ed_ptr(struct Timer *tim);</c>

Engines may find it convenient to associate a void* pointer with a. This macro may be used to retrieve that pointer or, when used as an lvalue, to assign a value to it. Engine data must be either an int or a void*; use of both is prohibited.

<c>int t_active(struct Timer *tim);</c>

A timer's active flag is set when initialized by, and is cleared immediately prior to generating an event of type. This may be used by the application to determine whether or not the timer is still in use by the events subsystem. If it is,  returns a non-zero value; otherwise, its value is 0.

<c>void timer_add(struct Timer* timer, EventCallBack call, void* data,	      enum TimerType type, time_t value);</c>

This function is called to initialize and queue a timer. The timer parameter is a pointer to a  that is allocated by the application. The call parameter is a pointer to a function to process the timer's expiration. The data parameter is for use of the timer call-back and may be zero. The type parameter must be one of the valid timer types --,  , or. Finally, value is the value for the timer's expiration.

<c>void timer_del(struct Timer* timer);</c>

When the application no longer needs a  timer, or when it wishes to stop a   or   timer before its expiration, it should call the   function.

<c>void timer_chg(struct Timer* timer, enum TimerType type, time_t value);</c>

Occasionally, an application may wish to delay an existing  or   timer; this may be done with the   or   --changing the values of   timers is not supported. The value parameter is the same as would be given to  for that particular type of timer.

<c>void timer_run(void);</c>

When an engine has finished processing the results of its socket and signal checks -- just before it loops around to test for more events -- it should call the  function to expire any waiting timers.

<c>time_t timer_next(struct Generators* gen);</c>

Most engines will use a blocking call with a timeout to check for socket activity. To determine when the next timer needs to be run, and thus to calculate how long the call should block, the engine should call  with the gen parameter passed to the   function. The  function returns an absolute time, which may have to be massaged into a relative time before the engine may use it.

<c>const char* timer_to_name(enum TimerType type);</c>

This function is defined only when 'd. It takes the given type and returns a string giving that type's name. This function may safely be called from  macros.

<c>enum EventType ev_type(struct Event* ev);</c>

This macro simply returns the type of the event ev.

<c>int ev_data(struct Event* ev);</c>

When an event is generated, a single integer can be passed along as a piece of extra information. This can be used, for instance, to carry an  value when an   is generated. This macro simply returns that integer.

<c>struct Socket* ev_socket(struct Event* ev);</c>

If the event was generated by a socket, this macro returns a pointer to the  that generated the event. The results are undefined if the event was not generated by a socket.

<c>struct Signal* ev_signal(struct Event* ev);</c>

If the event was generated by a signal, this macro returns a pointer to the  that generated the event. The results are undefined if the event was not generated by a signal.

<c>struct Timer* ev_timer(struct Event* ev);</c>

If the event was generated by a timer, this macro returns a pointer to the  that generated the event. The results are undefined if the event was not generated by a timer.

<c>void event_init(int max_sockets);</c>

Before any of the functions or macros described here can be called, the events subsystem must be initialized by calling. The max_sockets parameter specifies to the events subsystem how many sockets it must be able to support; this figure may be used for memory allocation by the engines.

<c>void event_loop(void);</c>

Once the initial sockets are open, signals added, and timers queued, the application must call the  function in order to actually begin monitoring those sockets, signals, and timers.

<c>void event_generate(enum EventType type, void* arg, int data);</c>

This is the function called by the events subsystem to generate particular events. The type parameter specifies the type of event to generate, and the arg parameter must be a pointer to the event's generator. The data parameter may be used for passing such things as signal numbers or  values.

<c>const char* event_to_name(enum EventType type);</c>

This function is defined only when  is  'd. It takes the given type and returns a string giving that event type's name. This function may safely be called from  macros.

<c>const char* engine_name(void);</c>

This function is used to retrieve the name of the engine presently being used by the events subsystem.

<c>void gen_ref_inc(void* gen);</c>

This macro increments the reference count of the generator gen, preventing it from simply disappearing without warning.

<c>void gen_ref_dec(void* gen);</c>

This macro decrements the reference count of the generator gen, and releases the memory associated with it by generating at  event if the reference count falls to zero and the generator is marked for destruction. No references should be made to the generator after calling this macro.