comments

Author: tlaitinen

include/prototls/Common.hpp

@@ -3,6 +3,7 @@
 #include <string>
 #include <sstream>
 namespace prototls {
+    /** a convenience method to convert objects to strings */
     template <class T> std::string toString(T t) {
         std::stringstream s;
         s << t;

include/prototls/Peer.hpp

@@ -4,32 +4,66 @@
 #include "prototls/Socket.hpp"
 #include <boost/smart_ptr.hpp>
 namespace prototls {
+    /** Packet serializer on top of a Socket */
     class Peer {
+        /** socket operated and owned by peer */
         boost::scoped_ptr<Socket> sock;
+
+        /** the length of the next protobuf message if nonzero */
         size_t msgSize;
-        std::string inBuf, outBuf;
+
+        /** buffer for incoming data */
+        std::string inBuf;
+
+        /** buffer for outgoing data */
+        std::string outBuf;
+
+        /** byte position in the incoming data buffer for parsing packets */
         int inBufPos;
 
+        /** reads the next protobuf message size from incoming data buffer
+          and sets 'msgSize' */
         void readMessageSize();
      public:
+
+        /** initializes fields to zero */
         Peer();
 
+        /** sets the socket to use for transferring data */
         void setup(Socket* sock);
+
+        /** closes the socket */
         void close();
+
+        /** \return the socket descriptor */
         int getFd() const {
             return sock->getFd();
         }
+
+        /** \return true if the socket is set and alive */
         bool isActive() const {
             return sock.get() ? sock->isActive() : false;
         }
+
+        /** \return socket specific address description */
         const std::string& getInfo() const {
             return sock->getInfo();
         }
+
+        /** reads data from socket and tries to read the next message size */
         void onInput();
+
+        /** serializes protobuf message and stores the data in the
+          outgoing data buffer */
         void send(const google::protobuf::MessageLite& m);
+
+        /** \return true, if a packet can be deserialized from the
+          incoming data buffer */
         bool hasPacket() const {
             return msgSize && inBuf.size() - inBufPos >= msgSize;
         }
+        /** deserializes a protobuf message of type T from the incoming
+          data buffer */
         template <class T>
             void recv(T& m) {
                 m.ParseFromArray(inBuf.c_str() + inBufPos, msgSize);
@@ -41,8 +75,9 @@ namespace prototls {
                 }
                 readMessageSize();
             }
-        void flush();
 
+        /** sends the outgoing data buffer and empties it */
+        void flush();
     };
 }
 #endif

include/prototls/Select.hpp

@@ -2,25 +2,42 @@
 #define _prototls_select_hpp_
 #include "prototls/Socket.hpp"
 namespace prototls {
+    /** wrapper for select system call to perform asynchronous IO
+      on multiple sockets */
     class Select {
+        /** file descriptor set */
         fd_set rfds;
+
+        /** the highest socket descriptor 'rfds' */
         Socket::Fd max;
     public:
+        /** performs reset */
         Select() {
             reset();
         }
+
+        /** initializes the file descriptor set */
         void reset() {
             FD_ZERO(&rfds);
             max = 0;
         }
+
+        /** marks the socket to be watched for reading */
         void input(Socket::Fd fd) {
             FD_SET(fd, &rfds);
             if (fd > max)
                 max = fd;
         }
+
+        /** \return true if the socket has data waiting to be read */
         bool canRead(Socket::Fd fd) const {
             return FD_ISSET(fd, &rfds);
         }
+
+        /** waits 'msecs' milliseconds for the sockets in the 
+          socket descriptor set for input
+         \return -1 on error, 0 if no data, > 0 number of sockets 
+         that have data waiting */
         int select(int msecs) {
             struct timeval tv;
             tv.tv_usec = (msecs % 1000) * 1000;

include/prototls/Server.hpp

@@ -14,22 +14,48 @@
 #include <vector>
 #include <deque>
 namespace prototls {
+    /** Server class template for implementing 
+        asynchronous servers that send and receive protobuf messages
+        with/without encrypted communication. TLS handshakes
+        are performed in separate threads in order to avoid blocking 
+        for long time. */
     template <class PeerT>
         class Server {
+            /** socket that accepts connections */
             boost::scoped_ptr<Socket> sock;
+
+            /** connected peers are stored in a vector holding
+              boost shared pointers to simplify memory management */
             typedef std::vector< boost::shared_ptr<PeerT> > Peers;
+
+            /** connected peers */
             Peers peers;
+
+            /** a pool of threads for TLS handshakes */
             boost::threadpool::pool pool;
+
+            /** thread safe deque that holds fresh TLS sockets */
             TSDeque<Socket*> socketsReady;
+
+            /** this method is called when a peer can read a packet */
             virtual void onPacket(PeerT&p) = 0;
+
+            /** this method is called when a new peer joins (after TLS
+              handshake if encrypted communication is used) */
             virtual void onJoin(PeerT&p) = 0;
+
+            /** this method is called when a peer leaves */
             virtual void onLeave(PeerT& p) = 0;
+
+            /** performs TLS handshake on the socket and
+             adds it to the list of ready sockets */
             void handshake(Socket* sock) {
                 if (sock->handshake()) {
                     return;
                 }
                 socketsReady.push_back(sock);
             }
+            /** flag marking that the server has been closed */
             bool closed;
         public:
             Server(int threads=16) : pool(threads), closed(false) {