include/socketengine.h

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