include/socketengine.h

   1 /*       +------------------------------------+
   2  *       | Inspire Internet Relay Chat Daemon |
   3  *       +------------------------------------+
   4  *
   5  *  InspIRCd: (C) 2002-2007 InspIRCd Development Team
   6  * See: http://www.inspircd.org/wiki/index.php/Credits
   7  *
   8  * This program is free but copyrighted software; see
   9  *            the file COPYING for details.
  10  *
  11  * ---------------------------------------------------
  12  */
  13
  14 #ifndef __SOCKETENGINE__
  15 #define __SOCKETENGINE__
  16
  17 #include <vector>
  18 #include <string>
  19 #include <map>
  20 #include "inspircd_config.h"
  21 #include "base.h"
  22
  23 /** Types of event an EventHandler may receive.
  24  * EVENT_READ is a readable file descriptor,
  25  * and EVENT_WRITE is a writeable file descriptor.
  26  * EVENT_ERROR can always occur, and indicates
  27  * a write error or read error on the socket,
  28  * e.g. EOF condition or broken pipe.
  29  */
  30 enum EventType
  31 {
  32         EVENT_READ      =       0,
  33         EVENT_WRITE     =       1,
  34         EVENT_ERROR     =       2
  35 };
  36
  37 class InspIRCd;
  38
  39 /** This class is a basic I/O handler class.
  40  * Any object which wishes to receive basic I/O events
  41  * from the socketengine must derive from this class and
  42  * implement the HandleEvent() method. The derived class
  43  * must then be added to SocketEngine using the method
  44  * SocketEngine::AddFd(), after which point the derived
  45  * class will receive events to its HandleEvent() method.
  46  * The derived class should also implement one of Readable()
  47  * and Writeable(). In the current implementation, only
  48  * Readable() is used. If this returns true, the socketengine
  49  * inserts a readable socket. If it is false, the socketengine
  50  * inserts a writeable socket. The derived class should never
  51  * change the value this function returns without first
  52  * deleting the socket from the socket engine. The only
  53  * requirement beyond this for an event handler is that it
  54  * must have a file descriptor. What this file descriptor
  55  * is actually attached to is completely up to you.
  56  */
  57 class EventHandler : public Extensible
  58 {
  59  protected:
  60         /** File descriptor.
  61          * All events which can be handled
  62          * must have a file descriptor.
  63          * This allows you to add events for
  64          * sockets, fifo's, pipes, and various
  65          * other forms of IPC.
  66          */
  67         int fd;
  68  public:
  69         /** Get the current file descriptor
  70          * @return The file descriptor of this handler
  71          */
  72         int GetFd();
  73
  74         /** Set a new file desciptor
  75          * @param FD The new file descriptor. Do not
  76          * call this method without first deleting the
  77          * object from the SocketEngine if you have
  78          * added it to a SocketEngine instance.
  79          */
  80         void SetFd(int FD);
  81
  82         /** Constructor
  83          */
  84         EventHandler() {}
  85
  86         /** Destructor
  87          */
  88         virtual ~EventHandler() {}
  89
  90         /** Override this function to indicate readability.
  91          * @return This should return true if the function
  92          * wishes to receive EVENT_READ events. Do not change
  93          * what this function returns while the event handler
  94          * is still added to a SocketEngine instance!
  95          * If this function is unimplemented, the base class
  96          * will return true.
  97          *
  98          * NOTE: You cannot set both Readable() and
  99          * Writeable() to true. If you wish to receive
 100          * a write event for your object, you must call
 101          * SocketEngine::WantWrite() instead. This will
 102          * trigger your objects next EVENT_WRITE type event.
 103          */
 104         virtual bool Readable();
 105
 106         /** Override this function to indicate writeability.
 107          * @return This should return true if the function
 108          * wishes to receive EVENT_WRITE events. Do not change
 109          * what this function returns while the event handler
 110          * is still added to a SocketEngine instance!
 111          * If this function is unimplemented, the base class
 112          * will return false.
 113          *
 114          * NOTE: You cannot set both Readable() and
 115          * Writeable() to true. If you wish to receive
 116          * a write event for your object, you must call
 117          * SocketEngine::WantWrite() instead. This will
 118          * trigger your objects next EVENT_WRITE type event.
 119          */
 120         virtual bool Writeable();
 121
 122         /** Process an I/O event.
 123          * You MUST implement this function in your derived
 124          * class, and it will be called whenever read or write
 125          * events are received, depending on what your functions
 126          * Readable() and Writeable() returns and wether you
 127          * previously made a call to SocketEngine::WantWrite().
 128          * @param et either one of EVENT_READ for read events,
 129          * and EVENT_WRITE for write events.
 130          */
 131         virtual void HandleEvent(EventType et, int errornum = 0) = 0;
 132 };
 133
 134 /** Provides basic file-descriptor-based I/O support.
 135  * The actual socketengine class presents the
 136  * same interface on all operating systems, but
 137  * its private members and internal behaviour
 138  * should be treated as blackboxed, and vary
 139  * from system to system and upon the config
 140  * settings chosen by the server admin. The current
 141  * version supports select, epoll and kqueue.
 142  * The configure script will enable a socket engine
 143  * based upon what OS is detected, and will derive
 144  * a class from SocketEngine based upon what it finds.
 145  * The derived classes file will also implement a
 146  * classfactory, SocketEngineFactory, which will
 147  * create a derived instance of SocketEngine using
 148  * polymorphism so that the core and modules do not
 149  * have to be aware of which SocketEngine derived
 150  * class they are using.
 151  */
 152 class SocketEngine : public Extensible
 153 {
 154 protected:
 155         /** Owner/Creator
 156          */
 157         InspIRCd* ServerInstance;
 158         /** Handle to socket engine, where needed.
 159          */
 160         int EngineHandle;
 161         /** Current number of descriptors in the engine
 162          */
 163         int CurrentSetSize;
 164         /** Reference table, contains all current handlers
 165          */
 166         EventHandler* ref[MAX_DESCRIPTORS];
 167 public:
 168
 169         /** Constructor.
 170          * The constructor transparently initializes
 171          * the socket engine which the ircd is using.
 172          * Please note that if there is a catastrophic
 173          * failure (for example, you try and enable
 174          * epoll on a 2.4 linux kernel) then this
 175          * function may bail back to the shell.
 176          * @param Instance The creator/owner of this object
 177          */
 178         SocketEngine(InspIRCd* Instance);
 179
 180         /** Destructor.
 181          * The destructor transparently tidies up
 182          * any resources used by the socket engine.
 183          */
 184         virtual ~SocketEngine();
 185
 186         /** Add an EventHandler object to the engine.
 187          * Use AddFd to add a file descriptor to the
 188          * engine and have the socket engine monitor
 189          * it. You must provide an object derived from
 190          * EventHandler which implements HandleEvent()
 191          * and optionally Readable() and Writeable().
 192          * @param eh An event handling object to add
 193          */
 194         virtual bool AddFd(EventHandler* eh);
 195
 196         /** If you call this function and pass it an
 197          * event handler, that event handler will
 198          * receive the next available write event,
 199          * even if the socket is a readable socket only.
 200          * Developers should avoid constantly keeping
 201          * an eventhandler in the writeable state,
 202          * as this will consume large amounts of
 203          * CPU time.
 204          * @param eh An event handler which wants to
 205          * receive the next writeability event.
 206          */
 207         virtual void WantWrite(EventHandler* eh);
 208
 209         /** Returns the maximum number of file descriptors
 210          * you may store in the socket engine at any one time.
 211          * @return The maximum fd value
 212          */
 213         virtual int GetMaxFds();
 214
 215         /** Returns the number of file descriptor slots
 216          * which are available for storing fds.
 217          * @return The number of remaining fd's
 218          */
 219         virtual int GetRemainingFds();
 220
 221         /** Delete an event handler from the engine.
 222          * This function call deletes an EventHandler
 223          * from the engine, returning true if it succeeded
 224          * and false if it failed. This does not free the
 225          * EventHandler pointer using delete, if this is
 226          * required you must do this yourself.
 227          * @param eh The event handler object to remove
 228          * @return True if the event handler was removed
 229          */
 230         virtual bool DelFd(EventHandler* eh);
 231
 232         /** Returns true if a file descriptor exists in
 233          * the socket engine's list.
 234          * @param fd The event handler to look for
 235          * @return True if this fd has an event handler
 236          */
 237         bool HasFd(int fd);
 238
 239         /** Returns the EventHandler attached to a specific fd.
 240          * If the fd isnt in the socketengine, returns NULL.
 241          * @param fd The event handler to look for
 242          * @return A pointer to the event handler, or NULL
 243          */
 244         EventHandler* GetRef(int fd);
 245
 246         /** Waits for events and dispatches them to handlers.
 247          * Please note that this doesnt wait long, only
 248          * a couple of milliseconds. It returns the number of
 249          * events which occured during this call.
 250          * This method will dispatch events to their handlers
 251          * by calling their EventHandler::HandleEvent()
 252          * methods with the neccessary EventType value.
 253          * @return The number of events which have occured.
 254          */
 255         virtual int DispatchEvents();
 256
 257         /** Returns the socket engines name.
 258          * This returns the name of the engine for use
 259          * in /VERSION responses.
 260          * @return The socket engine name
 261          */
 262         virtual std::string GetName();
 263 };
 264
 265 #endif