EventHandler class, an abstraction for raw i/o

git-svn-id: http://svn.inspircd.org/repository/trunk/inspircd@4941 e03df62e-2008-0410-955e-edbf42e46eb7

1 files changed, 147 insertions, 59 deletions

diff --git a/include/socketengine.h b/include/socketengine.h
index 5ccfa801e..fd01b4cf8 100644
--- a/include/socketengine.h
+++ b/include/socketengine.h
@@ -21,34 +21,103 @@
 #include <string>
 #include <map>
 #include "inspircd_config.h"
-#include "globals.h"
-#include "inspircd.h"
-
-/**
- * Each of these values represents a socket
- * type in our reference table (the reference
- * table itself is only accessible to
- * socketengine.cpp)
- */
-const char X_EMPTY_SLOT		= 0;
-const char X_LISTEN             = 1;
-const char X_ESTAB_CLIENT       = 2;
-const char X_ESTAB_MODULE       = 3;
-const char X_ESTAB_DNS          = 4;
-
-/**
- * To indicate that a socket is readable, we
- * mask its top bit with this X_READBIT value.
- * The socket engine can handle two types of
- * socket, readable and writeable (;error sockets
- * are dealt with when read() and write() return
- * negative or zero values).
+#include "base.h"
+
+/** Types of event an EventHandler may receive.
+ * EVENT_READ is a readable file descriptor,
+ * and EVENT_WRITE is a writeable file descriptor.
  */
-const char X_READBIT            = 0x80;
+enum EventType
+{
+	EVENT_READ	=	0,
+	EVENT_WRITE	=	1
+};
 
 class InspIRCd;
 
-/**
+/** This class is a basic I/O handler class.
+ * Any object which wishes to receive basic I/O events
+ * from the socketengine must derive from this class and
+ * implement the HandleEvent() method. The derived class
+ * must then be added to SocketEngine using the method
+ * SocketEngine::AddFd(), after which point the derived
+ * class will receive events to its HandleEvent() method.
+ * The derived class should also implement one of Readable()
+ * and Writeable(). In the current implementation, only
+ * Readable() is used. If this returns true, the socketengine
+ * inserts a readable socket. If it is false, the socketengine
+ * inserts a writeable socket. The derived class should never
+ * change the value this function returns without first
+ * deleting the socket from the socket engine. The only
+ * requirement beyond this for an event handler is that it
+ * must have a file descriptor. What this file descriptor
+ * is actually attached to is completely up to you.
+ */
+class EventHandler : public Extensible
+{
+ protected:
+	/** File descriptor.
+	 * All events which can be handled
+	 * must have a file descriptor.
+	 * This allows you to add events for
+	 * sockets, fifo's, pipes, and various
+	 * other forms of IPC.
+	 */
+	int fd;
+ public:
+	/** Get the current file descriptor
+	 * @return The file descriptor of this handler
+	 */
+	int GetFd();
+
+	/** Set a new file desciptor
+	 * @param FD The new file descriptor. Do not
+	 * call this method without first deleting the
+	 * object from the SocketEngine if you have
+	 * added it to a SocketEngine instance.
+	 */
+	void SetFd(int FD);
+
+	/** Constructor
+	 */
+	EventHandler() {}
+
+	/** Destructor
+	 */
+	virtual ~EventHandler() {}
+
+	/** Override this function to indicate readability.
+	 * @return This should return true if the function
+	 * wishes to receive EVENT_READ events. Do not change
+	 * what this function returns while the event handler
+	 * is still added to a SocketEngine instance!
+	 * If this function is unimplemented, the base class
+	 * will return true.
+	 */
+	virtual bool Readable();
+
+	/** Override this function to indicate writeability.
+	 * @return This should return true if the function
+	 * wishes to receive EVENT_WRITE events. Do not change
+	 * what this function returns while the event handler
+	 * is still added to a SocketEngine instance!
+	 * If this function is unimplemented, the base class
+	 * will return false.
+	 */
+	virtual bool Writeable();
+
+	/** Process an I/O event.
+	 * You MUST implement this function in your derived
+	 * class, and it will be called whenever read or write
+	 * events are received, depending on what your functions
+	 * Readable() and Writeable() returns.
+	 * @param et either one of EVENT_READ for read events,
+	 * and EVENT_WRITE for write events.
+	 */
+	virtual void HandleEvent(EventType et) = 0;
+};
+
+/** Provides basic file-descriptor-based I/O support.
  * The actual socketengine class presents the
  * same interface on all operating systems, but
  * its private members and internal behaviour
@@ -69,84 +138,103 @@ class InspIRCd;
 class SocketEngine : public Extensible
 {
 protected:
+	/** Owner/Creator
+	 */
 	InspIRCd* ServerInstance;
-	int EngineHandle;			/* Handle to the socket engine if needed */
-	int CurrentSetSize;			/* Current number of descriptors in the engine */
-	char ref[MAX_DESCRIPTORS];		/* Reference table */
+	/** Handle to socket engine, where needed.
+	 */
+	int EngineHandle;
+	/** Current number of descriptors in the engine
+	 */
+	int CurrentSetSize;
+	/** Reference table, contains all current handlers
+	 */
+	EventHandler* ref[MAX_DESCRIPTORS];
 public:
 
-	/** Constructor
+	/** Constructor.
 	 * The constructor transparently initializes
 	 * the socket engine which the ircd is using.
 	 * Please note that if there is a catastrophic
 	 * failure (for example, you try and enable
 	 * epoll on a 2.4 linux kernel) then this
 	 * function may bail back to the shell.
+	 * @param Instance The creator/owner of this object
 	 */
 	SocketEngine(InspIRCd* Instance);
 
-	/** Destructor
+	/** Destructor.
 	 * The destructor transparently tidies up
 	 * any resources used by the socket engine.
 	 */
 	virtual ~SocketEngine();
 
-	/** Add a file descriptor to the engine
+	/** Add an EventHandler object to the engine.
 	 * Use AddFd to add a file descriptor to the
 	 * engine and have the socket engine monitor
-	 * it. You must provide a type (see the consts
-	 * in socketengine.h) and a boolean flag to
-	 * indicate wether to watch this fd for read
-	 * or write events (there is currently no
-	 * need for support of both).
-	 */
-	virtual bool AddFd(int fd, bool readable, char type);
-
-	/** Returns the type value for this file descriptor
-	 * This function masks off the X_READBIT value
-	 * so that the type of the socket can be obtained.
-	 * The core uses this to decide where to dispatch
-	 * the event to. Please note that some engines
-	 * such as select() have an upper limit of 1024
-	 * descriptors which may be active at any one time,
-	 * where others such as kqueue have no practical
-	 * limits at all.
-	 */
-	char GetType(int fd);
+	 * it. You must provide an object derived from
+	 * EventHandler which implements HandleEvent()
+	 * and optionally Readable() and Writeable().
+	 * @param eh An event handling object to add
+	 */
+	virtual bool AddFd(EventHandler* eh);
 
 	/** Returns the maximum number of file descriptors
 	 * you may store in the socket engine at any one time.
+	 * @return The maximum fd value
 	 */
 	virtual int GetMaxFds();
 
 	/** Returns the number of file descriptor slots
 	 * which are available for storing fds.
+	 * @return The number of remaining fd's
 	 */
 	virtual int GetRemainingFds();
 
-	/** Delete a file descriptor from the engine
-	 * This function call deletes a file descriptor
+	/** Delete an event handler from the engine.
+	 * This function call deletes an EventHandler
 	 * from the engine, returning true if it succeeded
-	 * and false if it failed.
+	 * and false if it failed. This does not free the
+	 * EventHandler pointer using delete, if this is
+	 * required you must do this yourself.
+	 * @param eh The event handler object to remove
+	 * @return True if the event handler was removed
 	 */
-	virtual bool DelFd(int fd);
+	virtual bool DelFd(EventHandler* eh);
 
-	/** Returns true if a socket exists in the socket
-	 * engine's list.
+	/** Returns true if a file descriptor exists in
+	 * the socket engine's list.
+	 * @param fd The event handler to look for
+	 * @return True if this fd has an event handler
 	 */
 	bool HasFd(int fd);
 
+	/** Returns the EventHandler attached to a specific fd.
+	 * If the fd isnt in the socketengine, returns NULL.
+	 * @param fd The event handler to look for
+	 * @return A pointer to the event handler, or NULL
+	 */
+	EventHandler* GetRef(int fd);
+
 	/** Waits for an event.
 	 * Please note that this doesnt wait long, only
 	 * a couple of milliseconds. It returns a list
-	 * of active file descriptors in the vector
-	 * fdlist which the core may then act upon.
+	 * of active EventHandlers in the array fdlist
+	 * which the core will then dispatch events to
+	 * by calling their EventHandler::HandleEvent()
+	 * methods with the neccessary EventType value.
+	 * @param fdlist A pointer to a set of EventHandler
+	 * classes. You should ensure that the array you pass
+	 * is at least MAX_DESCRIPTORS in size, to accomodate
+	 * for the maximum number of events which can occur.
+	 * @return The number of events which have occured.
 	 */
-	virtual int Wait(int* fdlist);
+	virtual int Wait(EventHandler** fdlist);
 
-	/** Returns the socket engines name
+	/** Returns the socket engines name.
 	 * This returns the name of the engine for use
 	 * in /VERSION responses.
+	 * @return The socket engine name
 	 */
 	virtual std::string GetName();
 };