Added CullList class

[user/henk/code/inspircd.git] / include / socketengine.h

diff --git a/include/socketengine.h b/include/socketengine.h
index a499b4282d259616415f58745ad2cc8e40ebd622..caccd9b3f2d7825ec84b3c817b0511f797fe9691 100644 (file)
--- a/include/socketengine.h
+++ b/include/socketengine.h
@@ -32,37 +32,112 @@
 #include <sys/time.h>
 #endif
 
+/**
+ * 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).
+ */
 const char X_READBIT            = 0x80;
 
+/**
+ * The actual socketengine class presents the
+ * same interface on all operating systems, but
+ * its private members and internal behaviour
+ * should be treated as blackboxed, and vary
+ * from system to system and upon the config
+ * settings chosen by the server admin. The current
+ * version supports select, epoll and kqueue.
+ */
 class SocketEngine {
 
-       std::vector<int> fds;
-       int EngineHandle;
+       std::vector<int> fds;                   /* List of file descriptors being monitored */
+       int EngineHandle;                       /* Handle to the socket engine if needed */
 #ifdef USE_SELECT
-       fd_set wfdset, rfdset;
+       fd_set wfdset, rfdset;                  /* Readable and writeable sets for select() */
 #endif
 #ifdef USE_KQUEUE
-       struct kevent ke_list[65535];
-       struct timespec ts;
+       struct kevent ke_list[65535];           /* Up to 64k sockets for kqueue */
+       struct timespec ts;                     /* kqueue delay value */
 #endif
 #ifdef USE_EPOLL
-       struct epoll_event events[65535];
+       struct epoll_event events[65535];       /* Up to 64k sockets for epoll */
 #endif
 
 public:
 
+       /** 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.
+        */
        SocketEngine();
+
+       /** Destructor
+        * The destructor transparently tidies up
+        * any resources used by the socket engine.
+        */
        ~SocketEngine();
+
+       /** Add a file descriptor 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).
+        */
        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);
+
+       /** Delete a file descriptor f rom the engine
+        * This function call deletes a file descriptor
+        * from the engine, returning true if it succeeded
+        * and false if it failed.
+        */
        bool DelFd(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.
+        */
        bool Wait(std::vector<int> &fdlist);
+
+       /** Returns the socket engines name
+        * This returns the name of the engine for use
+        * in /VERSION responses.
+        */
        std::string GetName();
 };