include/socketengine.h

   1 /*       +------------------------------------+
   2  *       | Inspire Internet Relay Chat Daemon |
   3  *       +------------------------------------+
   4  *
   5  *  InspIRCd: (C) 2002-2008 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         /** Read event */
  33         EVENT_READ      =       0,
  34         /** Write event */
  35         EVENT_WRITE     =       1,
  36         /** Error event */
  37         EVENT_ERROR     =       2
  38 };
  39
  40 class InspIRCd;
  41
  42 /** This class is a basic I/O handler class.
  43  * Any object which wishes to receive basic I/O events
  44  * from the socketengine must derive from this class and
  45  * implement the HandleEvent() method. The derived class
  46  * must then be added to SocketEngine using the method
  47  * SocketEngine::AddFd(), after which point the derived
  48  * class will receive events to its HandleEvent() method.
  49  * The derived class should also implement one of Readable()
  50  * and Writeable(). In the current implementation, only
  51  * Readable() is used. If this returns true, the socketengine
  52  * inserts a readable socket. If it is false, the socketengine
  53  * inserts a writeable socket. The derived class should never
  54  * change the value this function returns without first
  55  * deleting the socket from the socket engine. The only
  56  * requirement beyond this for an event handler is that it
  57  * must have a file descriptor. What this file descriptor
  58  * is actually attached to is completely up to you.
  59  */
  60 class CoreExport EventHandler : public Extensible
  61 {
  62  protected:
  63         /** File descriptor.
  64          * All events which can be handled
  65          * must have a file descriptor.
  66          * This allows you to add events for
  67          * sockets, fifo's, pipes, and various
  68          * other forms of IPC.
  69          */
  70         int fd;
  71  public:
  72
  73         /** Get the current file descriptor
  74          * @return The file descriptor of this handler
  75          */
  76         int GetFd();
  77
  78         /** Set a new file desciptor
  79          * @param FD The new file descriptor. Do not
  80          * call this method without first deleting the
  81          * object from the SocketEngine if you have
  82          * added it to a SocketEngine instance.
  83          */
  84         void SetFd(int FD);
  85
  86         /** Constructor
  87          */
  88         EventHandler() {}
  89
  90         /** Destructor
  91          */
  92         virtual ~EventHandler() {}
  93
  94         /** Override this function to indicate readability.
  95          * @return This should return true if the function
  96          * wishes to receive EVENT_READ events. Do not change
  97          * what this function returns while the event handler
  98          * is still added to a SocketEngine instance!
  99          * If this function is unimplemented, the base class
 100          * will return true.
 101          *
 102          * NOTE: You cannot set both Readable() and
 103          * Writeable() to true. If you wish to receive
 104          * a write event for your object, you must call
 105          * SocketEngine::WantWrite() instead. This will
 106          * trigger your objects next EVENT_WRITE type event.
 107          */
 108         virtual bool Readable();
 109
 110         /** Override this function to indicate writeability.
 111          * @return This should return true if the function
 112          * wishes to receive EVENT_WRITE events. Do not change
 113          * what this function returns while the event handler
 114          * is still added to a SocketEngine instance!
 115          * If this function is unimplemented, the base class
 116          * will return false.
 117          *
 118          * NOTE: You cannot set both Readable() and
 119          * Writeable() to true. If you wish to receive
 120          * a write event for your object, you must call
 121          * SocketEngine::WantWrite() instead. This will
 122          * trigger your objects next EVENT_WRITE type event.
 123          */
 124         virtual bool Writeable();
 125
 126         /** Process an I/O event.
 127          * You MUST implement this function in your derived
 128          * class, and it will be called whenever read or write
 129          * events are received, depending on what your functions
 130          * Readable() and Writeable() returns and wether you
 131          * previously made a call to SocketEngine::WantWrite().
 132          * @param et either one of EVENT_READ for read events,
 133          * and EVENT_WRITE for write events.
 134          */
 135         virtual void HandleEvent(EventType et, int errornum = 0) = 0;
 136 };
 137
 138 /** Provides basic file-descriptor-based I/O support.
 139  * The actual socketengine class presents the
 140  * same interface on all operating systems, but
 141  * its private members and internal behaviour
 142  * should be treated as blackboxed, and vary
 143  * from system to system and upon the config
 144  * settings chosen by the server admin. The current
 145  * version supports select, epoll and kqueue.
 146  * The configure script will enable a socket engine
 147  * based upon what OS is detected, and will derive
 148  * a class from SocketEngine based upon what it finds.
 149  * The derived classes file will also implement a
 150  * classfactory, SocketEngineFactory, which will
 151  * create a derived instance of SocketEngine using
 152  * polymorphism so that the core and modules do not
 153  * have to be aware of which SocketEngine derived
 154  * class they are using.
 155  */
 156 class CoreExport SocketEngine : public Extensible
 157 {
 158 protected:
 159         /** Owner/Creator
 160          */
 161         InspIRCd* ServerInstance;
 162         /** Handle to socket engine, where needed.
 163          */
 164         int EngineHandle;
 165         /** Current number of descriptors in the engine
 166          */
 167         int CurrentSetSize;
 168         /** Reference table, contains all current handlers
 169          */
 170         EventHandler** ref;
 171
 172         int MAX_DESCRIPTORS;
 173 public:
 174
 175         double TotalEvents;
 176         double ReadEvents;
 177         double WriteEvents;
 178         double ErrorEvents;
 179
 180         /** Constructor.
 181          * The constructor transparently initializes
 182          * the socket engine which the ircd is using.
 183          * Please note that if there is a catastrophic
 184          * failure (for example, you try and enable
 185          * epoll on a 2.4 linux kernel) then this
 186          * function may bail back to the shell.
 187          * @param Instance The creator/owner of this object
 188          */
 189         SocketEngine(InspIRCd* Instance);
 190
 191         /** Destructor.
 192          * The destructor transparently tidies up
 193          * any resources used by the socket engine.
 194          */
 195         virtual ~SocketEngine();
 196
 197         /** Add an EventHandler object to the engine.
 198          * Use AddFd to add a file descriptor to the
 199          * engine and have the socket engine monitor
 200          * it. You must provide an object derived from
 201          * EventHandler which implements HandleEvent()
 202          * and optionally Readable() and Writeable().
 203          * @param eh An event handling object to add
 204          */
 205         virtual bool AddFd(EventHandler* eh);
 206
 207         /** If you call this function and pass it an
 208          * event handler, that event handler will
 209          * receive the next available write event,
 210          * even if the socket is a readable socket only.
 211          * Developers should avoid constantly keeping
 212          * an eventhandler in the writeable state,
 213          * as this will consume large amounts of
 214          * CPU time.
 215          * @param eh An event handler which wants to
 216          * receive the next writeability event.
 217          */
 218         virtual void WantWrite(EventHandler* eh);
 219
 220         /** Returns the maximum number of file descriptors
 221          * you may store in the socket engine at any one time.
 222          * @return The maximum fd value
 223          */
 224         virtual int GetMaxFds();
 225
 226         /** Returns the number of file descriptor slots
 227          * which are available for storing fds.
 228          * @return The number of remaining fd's
 229          */
 230         virtual int GetRemainingFds();
 231
 232         /** Delete an event handler from the engine.
 233          * This function call deletes an EventHandler
 234          * from the engine, returning true if it succeeded
 235          * and false if it failed. This does not free the
 236          * EventHandler pointer using delete, if this is
 237          * required you must do this yourself.
 238          * Note on forcing deletes. DO NOT DO THIS! This is
 239          * extremely dangerous and will most likely render the
 240          * socketengine dead. This was added only for handling
 241          * very rare cases where broken 3rd party libs destroys
 242          * the OS socket beyond our control. If you can't explain
 243          * in minute details why forcing is absolutely necessary
 244          * then you don't need it. That was a NO!
 245          * @param eh The event handler object to remove
 246          * @param force *DANGEROUS* See method description!
 247          * @return True if the event handler was removed
 248          */
 249         virtual bool DelFd(EventHandler* eh, bool force = false);
 250
 251         /** Returns true if a file descriptor exists in
 252          * the socket engine's list.
 253          * @param fd The event handler to look for
 254          * @return True if this fd has an event handler
 255          */
 256         virtual bool HasFd(int fd);
 257
 258         /** Returns the EventHandler attached to a specific fd.
 259          * If the fd isnt in the socketengine, returns NULL.
 260          * @param fd The event handler to look for
 261          * @return A pointer to the event handler, or NULL
 262          */
 263         virtual EventHandler* GetRef(int fd);
 264
 265         /** Waits for events and dispatches them to handlers.
 266          * Please note that this doesnt wait long, only
 267          * a couple of milliseconds. It returns the number of
 268          * events which occured during this call.
 269          * This method will dispatch events to their handlers
 270          * by calling their EventHandler::HandleEvent()
 271          * methods with the neccessary EventType value.
 272          * @return The number of events which have occured.
 273          */
 274         virtual int DispatchEvents();
 275
 276         /** Returns the socket engines name.
 277          * This returns the name of the engine for use
 278          * in /VERSION responses.
 279          * @return The socket engine name
 280          */
 281         virtual std::string GetName();
 282
 283         /** Returns true if the file descriptors in the
 284          * given event handler are within sensible ranges
 285          * which can be handled by the socket engine.
 286          */
 287         virtual bool BoundsCheckFd(EventHandler* eh);
 288
 289         /** Abstraction for BSD sockets accept(2).
 290          * This function should emulate its namesake system call exactly.
 291          * @param fd This version of the call takes an EventHandler instead of a bare file descriptor.
 292          * @return This method should return exactly the same values as the system call it emulates.
 293          */
 294         virtual int Accept(EventHandler* fd, sockaddr *addr, socklen_t *addrlen);
 295
 296         /** Abstraction for BSD sockets close(2).
 297          * This function should emulate its namesake system call exactly.
 298          * @param fd This version of the call takes an EventHandler instead of a bare file descriptor.
 299          * @return This method should return exactly the same values as the system call it emulates.
 300          */
 301         virtual int Close(EventHandler* fd);
 302
 303         /** Abstraction for BSD sockets close(2).
 304          * This function should emulate its namesake system call exactly.
 305          * This function should emulate its namesake system call exactly.
 306          * @return This method should return exactly the same values as the system call it emulates.
 307          */
 308         virtual int Close(int fd);
 309
 310         /** Abstraction for BSD sockets send(2).
 311          * This function should emulate its namesake system call exactly.
 312          * @param fd This version of the call takes an EventHandler instead of a bare file descriptor.
 313          * @return This method should return exactly the same values as the system call it emulates.
 314          */
 315         virtual int Send(EventHandler* fd, const void *buf, size_t len, int flags);
 316
 317         /** Abstraction for BSD sockets recv(2).
 318          * This function should emulate its namesake system call exactly.
 319          * @param fd This version of the call takes an EventHandler instead of a bare file descriptor.
 320          * @return This method should return exactly the same values as the system call it emulates.
 321          */
 322         virtual int Recv(EventHandler* fd, void *buf, size_t len, int flags);
 323
 324         /** Abstraction for BSD sockets recvfrom(2).
 325          * This function should emulate its namesake system call exactly.
 326          * @param fd This version of the call takes an EventHandler instead of a bare file descriptor.
 327          * @return This method should return exactly the same values as the system call it emulates.
 328          */
 329         virtual int RecvFrom(EventHandler* fd, void *buf, size_t len, int flags, sockaddr *from, socklen_t *fromlen);
 330
 331         /** Abstraction for BSD sockets sendto(2).
 332          * This function should emulate its namesake system call exactly.
 333          * @param fd This version of the call takes an EventHandler instead of a bare file descriptor.
 334          * @return This method should return exactly the same values as the system call it emulates.
 335          */
 336         virtual int SendTo(EventHandler* fd, const void *buf, size_t len, int flags, const sockaddr *to, socklen_t tolen);
 337
 338         /** Abstraction for BSD sockets connect(2).
 339          * This function should emulate its namesake system call exactly.
 340          * @param fd This version of the call takes an EventHandler instead of a bare file descriptor.
 341          * @return This method should return exactly the same values as the system call it emulates.
 342          */
 343         virtual int Connect(EventHandler* fd, const sockaddr *serv_addr, socklen_t addrlen);
 344
 345         /** Make a file descriptor blocking.
 346          * @param fd a file descriptor to set to blocking mode
 347          * @return 0 on success, -1 on failure, errno is set appropriately.
 348          */
 349         virtual int Blocking(int fd);
 350
 351         /** Make a file descriptor nonblocking.
 352          * @param fd A file descriptor to set to nonblocking mode
 353          * @return 0 on success, -1 on failure, errno is set appropriately.
 354          */
 355         virtual int NonBlocking(int fd);
 356
 357         /** Abstraction for BSD sockets shutdown(2).
 358          * This function should emulate its namesake system call exactly.
 359          * @param fd This version of the call takes an EventHandler instead of a bare file descriptor.
 360          * @return This method should return exactly the same values as the system call it emulates.
 361          */
 362         virtual int Shutdown(EventHandler* fd, int how);
 363
 364         /** Abstraction for BSD sockets shutdown(2).
 365          * This function should emulate its namesake system call exactly.
 366          * @return This method should return exactly the same values as the system call it emulates.
 367          */
 368         virtual int Shutdown(int fd, int how);
 369
 370         /** Abstraction for BSD sockets bind(2).
 371          * This function should emulate its namesake system call exactly.
 372          * @return This method should return exactly the same values as the system call it emulates.
 373          */
 374         virtual int Bind(int fd, const sockaddr *my_addr, socklen_t addrlen);
 375
 376         /** Abstraction for BSD sockets listen(2).
 377          * This function should emulate its namesake system call exactly.
 378          * @return This method should return exactly the same values as the system call it emulates.
 379          */
 380         virtual int Listen(int sockfd, int backlog);
 381
 382         /** Abstraction for BSD sockets getsockname(2).
 383          * This function should emulate its namesake system call exactly.
 384          * @param fd This version of the call takes an EventHandler instead of a bare file descriptor.
 385          * @return This method should return exactly the same values as the system call it emulates.
 386          */
 387         virtual int GetSockName(EventHandler* fd, sockaddr *name, socklen_t* namelen);
 388
 389         /** This function is called immediately after fork().
 390          * Some socket engines (notably kqueue) cannot have their
 391          * handles inherited by forked processes. This method
 392          * allows for the socket engine to re-create its handle
 393          * after the daemon forks as the socket engine is created
 394          * long BEFORE the daemon forks.
 395          * @return void, but it is acceptable for this function to bail back to
 396          * the shell or operating system on fatal error.
 397          */
 398         virtual void RecoverFromFork();
 399 };
 400
 401 #endif
 402