ircd/api/events - Revision history

Admin: /* Types, Enumerations, Structures, Macros and Functions */

Admin — Tue, 13 Jul 2010 15:14:08 GMT

Types, Enumerations, Structures, Macros and Functions

Admin: /* Types, Enumerations, Structures, Macros and Functions */

Admin — Sat, 10 Jul 2010 20:01:51 GMT

Types, Enumerations, Structures, Macros and Functions

← Older revision		Revision as of 20:01, 10 July 2010
Line 182:		Line 182:

	Each engine is described by the <code>struct Engine</code> structure. Each engine must define all of the functions described above except for the <code>EngineSignal</code> function, which is optional.		Each engine is described by the <code>struct Engine</code> structure. Each engine must define all of the functions described above except for the <code>EngineSignal</code> function, which is optional.
		+
		+	<c>#define SOCK_EVENT_READABLE 0x0001 /* interested in readable */</c>
		+
		+	The <code>SOCK_EVENT_READABLE</code> flag indicates to the engine that the application is interested in readability on this particular socket.
		+
		+	<c>#define SOCK_EVENT_WRITABLE 0x0002 /* interested in writable */</c>
		+
		+	The <code>SOCK_EVENT_WRITABLE</code> flag indicates to the engine that the application is interested in this socket being writable.
		+
		+	<c>#define SOCK_EVENT_MASK (SOCK_EVENT_READABLE \| SOCK_EVENT_WRITABLE)</c>
		+
		+	<code>SOCK_EVENT_MASK</code> may be used to extract only the event interest flags from an event interest set.
		+
		+	<c>#define SOCK_ACTION_SET 0x0000 /* set interest set as follows */</c>
		+
		+	When <code>socket_events()</code> is called with a set of event interest flags and <code>SOCK_ACTION_SET</code>, the socket's event interest flags are set to those passed into <code>socket_events()</code>.
		+
		+	<c>#define SOCK_ACTION_ADD 0x1000 /* add to interest set */</c>
		+
		+	When <code>SOCK_ACTION_ADD</code> is used in a call to <code>socket_events()</code>, the event interest flags passed in are added to the existing event interest flags for the socket.
		+
		+	<c>#define SOCK_ACTION_DEL 0x2000 /* remove from interest set */</c>
		+
		+	When <code>SOCK_ACTION_DEL</code> is used in a call to <code>socket_events()</code>, the event interest flags passed in are removed from the existing event interest flags for the socket.
		+
		+	<c>#define SOCK_ACTION_MASK 0x3000 /* mask out the actions */</c>
		+
		+	<code>SOCK_ACTION_MASK</code> 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 <code>SS_CONNECTING</code> or <code>SS_LISTENING</code> 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 <code>struct Socket</code> is initialized, data that the call-back function may find useful, such as a pointer to a <code>struct Connection</code>, is stored in the <code>struct Socket</code>. 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 <code>struct Socket</code>. 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.

Admin at 19:54, 10 July 2010

Admin — Sat, 10 Jul 2010 19:54:12 GMT

← Older revision		Revision as of 19:54, 10 July 2010
Line 151:		Line 151:
	struct Event** ev_prev_p; /* Previous pointer to this event */		struct Event** ev_prev_p; /* Previous pointer to this event */
	enum EventType ev_type; /* Event type */		enum EventType ev_type; /* Event type */
-	int ev_data; /* Extra data, like errno value */	+	int ev_data; /* Extra data, like errno value */
	union {		union {
	struct GenHeader* gen_header; /* Generator header */		struct GenHeader* gen_header; /* Generator header */

Admin at 19:53, 10 July 2010

Admin — Sat, 10 Jul 2010 19:53:29 GMT

← Older revision		Revision as of 19:53, 10 July 2010
Line 122:		Line 122:
	struct GenHeader s_header; /* Generator information */		struct GenHeader s_header; /* Generator information */
	enum SocketState s_state; /* State socket's in */		enum SocketState s_state; /* State socket's in */
-	unsigned int s_events; /* Events socket is interested in */	+	unsigned int s_events; /* Events socket is interested in */
-	int s_fd; /* File descriptor for socket */	+	int s_fd; /* File descriptor for socket */
	#ifdef USE_SSL		#ifdef USE_SSL
-	SSL* ssl; /* If not NULL, use SSL routines on socket */	+	SSL* ssl; /* If not NULL, use SSL routines on socket */
-	#endif /* USE_SSL */	+	#endif /* USE_SSL */
	};</c>		};</c>

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

Line 142:		Line 142:
	<c>struct Signal {		<c>struct Signal {
	struct GenHeader sig_header; /* Generator information */		struct GenHeader sig_header; /* Generator information */
-	int sig_signal; /* Signal number */	+	int sig_signal; /* Signal number */
	};</c>		};</c>

Line 148:		Line 148:

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

Admin: /* Types, Enumerations, Structures, Macros and Functions */

Admin — Sat, 10 Jul 2010 19:51:43 GMT

Types, Enumerations, Structures, Macros and Functions

← Older revision		Revision as of 19:51, 10 July 2010
Line 96:		Line 96:

	This enumeration contains a list of all possible states a socket can be in. Applications should not use <code>SS_NOTSOCK</code>; engines should treat it as a special socket state for non-sockets. The only event that should be watched for on a <code>struct Socket</code> in the <code>SS_NOTSOCK</code> state is readability. This socket state is used to implement the fall-back signal event generation.		This enumeration contains a list of all possible states a socket can be in. Applications should not use <code>SS_NOTSOCK</code>; engines should treat it as a special socket state for non-sockets. The only event that should be watched for on a <code>struct Socket</code> in the <code>SS_NOTSOCK</code> state is readability. This socket state is used to implement the fall-back signal event generation.
		+
		+	<c>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 <code>TimerType</code> enumeration. More details can be found in the "Timers" section, above.
		+
		+	<c>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. <code>ET_DESTROY</code> is generated by both socket and timer generators when the events subsystem is finished with the memory allocated by both.
		+
		+	<c>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 */
		+	#ifdef USE_SSL
		+	SSL* ssl; /* If not NULL, use SSL routines on socket */
		+	#endif /* USE_SSL */
		+	};</c>
		+
		+	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.
		+
		+	<c>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 <code>struct Timer</code> 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.
		+
		+	<c>struct Signal {
		+	struct GenHeader sig_header; /* Generator information */
		+	int sig_signal; /* Signal number */
		+	};</c>
		+
		+	Signal generators are described by a <code>struct Signal</code>. All of the fields of a <code>struct Signal</code> may be accessed by the sig_* macros described below.
		+
		+	<c>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 <code>struct Event</code>. Its fields may be examined using the ev_* macros described below.
		+
		+	<c>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 <code>EngineLoop</code> function is called. The only valid way to access this structure is via the <code>timer_next()</code> function described below.
		+
		+	<c>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 <code>struct Engine</code> structure. Each engine must define all of the functions described above except for the <code>EngineSignal</code> function, which is optional.

Admin: /* Types, Enumerations, Structures, Macros and Functions */

Admin — Sat, 10 Jul 2010 19:39:30 GMT

Types, Enumerations, Structures, Macros and Functions

← Older revision		Revision as of 19:39, 10 July 2010
Line 73:		Line 73:

	Sockets can change state. <code>SS_CONNECTING</code> sockets, for instance, can become <code>SS_CONNECTED</code>. Whenever a socket state changes, the engine is informed, since some states require different notification procedures than others. This is accomplished by calling the <code>EngineState</code> function with the new state. The <code>struct Socket</code> passed to the engine will still have the old state, if the engine must reference that.		Sockets can change state. <code>SS_CONNECTING</code> sockets, for instance, can become <code>SS_CONNECTED</code>. Whenever a socket state changes, the engine is informed, since some states require different notification procedures than others. This is accomplished by calling the <code>EngineState</code> function with the new state. The <code>struct Socket</code> passed to the engine will still have the old state, if the engine must reference that.
		+
		+	<c>typedef void (EngineEvents)(struct Socket, unsigned int new_events);</c>
		+
		+	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 <code>EngineEvents</code> function.
		+
		+	<c>typedef void (EngineDelete)(struct Socket);</c>
		+
		+	Eventually, an application will close all the sockets it has opened. When a socket is closed, and the corresponding <code>struct Socket</code> deleted with a call to <code>socket_del()</code>, the <code>EngineDelete</code> function will be called to notify the engine of the change.
		+
		+	<c>typedef void (EngineLoop)(struct Generators);</c>
		+
		+	The workhorse of the entire events subsystem is the event loop, implemented by each engine as the <code>EngineLoop</code> function. This function is called with a single argument that may be passed to <code>timer_next()</code> to calculate the next time a timer will expire.
		+
		+	<c>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 <code>SS_NOTSOCK</code>; engines should treat it as a special socket state for non-sockets. The only event that should be watched for on a <code>struct Socket</code> in the <code>SS_NOTSOCK</code> state is readability. This socket state is used to implement the fall-back signal event generation.

Admin: /* Types, Enumerations, Structures, Macros and Functions */

Admin — Sat, 10 Jul 2010 19:35:32 GMT

Types, Enumerations, Structures, Macros and Functions

← Older revision		Revision as of 19:35, 10 July 2010
Line 61:		Line 61:

	The <code>EngineInit</code> 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 <code>poll()</code> and <code>select()</code> should never fail in this way.		The <code>EngineInit</code> 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 <code>poll()</code> and <code>select()</code> should never fail in this way.
		+
		+	<c>typedef void (EngineSignal)(struct Signal);</c>
		+
		+	If an engine has the capability to directly detect signals, it should set the <code>eng_signal</code> field of <code>struct Engine</code> non-zero. When the application indicates interest in a particular signal, the <code>EngineSignal</code> function will be called with the filled-in <code>struct Signal</code>, in order to register interest in that signal with the engine.
		+
		+	<c>typedef int (EngineAdd)(struct Socket);</c>
		+
		+	All engines must define an <code>EngineAdd</code> 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.
		+
		+	<c>typedef void (EngineState)(struct Socket, enum SocketState new_state);</c>
		+
		+	Sockets can change state. <code>SS_CONNECTING</code> sockets, for instance, can become <code>SS_CONNECTED</code>. Whenever a socket state changes, the engine is informed, since some states require different notification procedures than others. This is accomplished by calling the <code>EngineState</code> function with the new state. The <code>struct Socket</code> passed to the engine will still have the old state, if the engine must reference that.

Admin: /* Types, Enumerations, Structures, Macros and Functions */

Admin — Sat, 10 Jul 2010 19:31:21 GMT

Types, Enumerations, Structures, Macros and Functions

← Older revision		Revision as of 19:31, 10 July 2010
Line 60:		Line 60:
	<c>typedef int (*EngineInit)(int);</c>		<c>typedef int (*EngineInit)(int);</c>

-	The <code>EngineInit 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 <code>poll()</code> and <code>select()</code> should never fail in this way.	+	The <code>EngineInit</code> 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 <code>poll()</code> and <code>select()</code> should never fail in this way.

Admin: /* Engines */

Admin — Sat, 10 Jul 2010 19:31:07 GMT

Engines

← Older revision		Revision as of 19:31, 10 July 2010
Line 43:		Line 43:
	The engine's event loop, pointed to by the <code>eng_loop</code> field of the <code>struct Engine</code>, must consist of a single while loop predicated on the global variable <code>running</code>. Additionally, this loop's final statement must be a call to <code>timer_run()</code>, to execute all timers that have become due. Ideally, this construction should be pulled out of each engine's		The engine's event loop, pointed to by the <code>eng_loop</code> field of the <code>struct Engine</code>, must consist of a single while loop predicated on the global variable <code>running</code>. Additionally, this loop's final statement must be a call to <code>timer_run()</code>, to execute all timers that have become due. Ideally, this construction should be pulled out of each engine's
	<code>eng_loop</code> and put in the <code>event_loop()</code> function of the events subsystem.		<code>eng_loop</code> and put in the <code>event_loop()</code> function of the events subsystem.
		+
		+	== Reference Counts ==
		+
		+	As mentioned previously, all generators keep a reference count. Should <code>timer_del()</code> or <code>socket_del()</code> 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 <code>gen_ref_inc()</code> on the generator; the corresponding macro <code>gen_ref_dec()</code> 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 <code>DEBUGMODE</code> is <code>#define</code>'d, five number-to-name functions are also defined to make the debugging data more meaningful. These functions must only be called when <code>DEBUGMODE</code> is <code>#define</code>'d. Calling them from within <code>Debug()</code> macro calls is safe; calling them from <code>log_write()</code> calls is not.
		+
		+	== Types, Enumerations, Structures, Macros and Functions ==
		+
		+	<c>typedef void (EventCallBack)(struct Event);</c>
		+
		+	The <code>EventCallBack</code> type is used to simplify declaration of event call-back functions. It is used in <code>timer_add()</code>, <code>signal_add()</code>, and <code>socket_add()</code>. The event call-back should process the event, taking whatever actions are necessary. The function should be declared as returning void.
		+
		+	<c>typedef int (*EngineInit)(int);</c>
		+
		+	The <code>EngineInit 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 <code>poll()</code> and <code>select()</code> should never fail in this way.

Admin at 19:19, 10 July 2010

Admin — Sat, 10 Jul 2010 19:19:41 GMT

← Older revision		Revision as of 19:19, 10 July 2010
Line 28:		Line 28:

	Most of the defined event types have to do with socket generators. When a socket turns up readable, for instance, an event type <code>ET_READ</code> is generated. Similarly, <code>ET_WRITE</code> is generated when a socket can be written to. The <code>ET_ACCEPT</code> event is generated when a listening socket indicates that there is a connection to be accepted; <code>ET_CONNECT</code> is generated when a non-blocking connect is completed. Finally, if an end-of-file indication is detected, <code>ET_EOF</code> is generated, whereas if an error has occurred on the socket, <code>ET_ERROR</code> is generated. Of course, when a socket has been deleted by the <code>socket_del()</code> function, an event of <code>ET_DESTROY</code> is generated when it is safe for the memory used by the <code>struct Socket</code> to be reclaimed.		Most of the defined event types have to do with socket generators. When a socket turns up readable, for instance, an event type <code>ET_READ</code> is generated. Similarly, <code>ET_WRITE</code> is generated when a socket can be written to. The <code>ET_ACCEPT</code> event is generated when a listening socket indicates that there is a connection to be accepted; <code>ET_CONNECT</code> is generated when a non-blocking connect is completed. Finally, if an end-of-file indication is detected, <code>ET_EOF</code> is generated, whereas if an error has occurred on the socket, <code>ET_ERROR</code> is generated. Of course, when a socket has been deleted by the <code>socket_del()</code> function, an event of <code>ET_DESTROY</code> is generated when it is safe for the memory used by the <code>struct Socket</code> to be reclaimed.
		+
		+	== Events ==
		+
		+	An event, represented by a <code>struct Event</code>, 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, <code>ET_SIGNAL</code> events pass the signal number, and <code>ET_ERROR</code> events pass the <code>errno</code> value. The <code>struct Event</code> 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 <code>struct Event</code> 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 <code>struct Client</code>. 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 <code>struct Event</code>. 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 <code>select()</code> function is named, simply, "<code>select()</code>." 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 <code>struct Engine</code>, 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 <code>eng_loop</code> field of the <code>struct Engine</code>, must consist of a single while loop predicated on the global variable <code>running</code>. Additionally, this loop's final statement must be a call to <code>timer_run()</code>, to execute all timers that have become due. Ideally, this construction should be pulled out of each engine's
		+	<code>eng_loop</code> and put in the <code>event_loop()</code> function of the events subsystem.