add some documentation

arangod/GeneralServer/GeneralCommTask.cpp

@@ -79,6 +79,20 @@ GeneralCommTask::~GeneralCommTask() {
   delete _request;
 }
 
+void GeneralCommTask::fillWriteBuffer() {
+  if (!hasWriteBuffer() && !_writeBuffers.empty()) {
+    StringBuffer* buffer = _writeBuffers.front();
+    _writeBuffers.pop_front();
+
+    TRI_ASSERT(buffer != nullptr);
+
+    TRI_request_statistics_t* statistics = _writeBuffersStats.front();
+    _writeBuffersStats.pop_front();
+
+    setWriteBuffer(buffer, statistics);
+  }
+}
+
 void GeneralCommTask::handleResponse(GeneralResponse* response) {
   _requestPending = false;
   _isChunked = false;

arangod/GeneralServer/GeneralCommTask.h

@@ -41,6 +41,10 @@ class GeneralResponse;
 namespace rest {
 class GeneralServer;
 
+// handleEvent (defined in SocketTask and arumented in this class) is called
+// when new data is available. handleEvent calls in turn handleWrite and
+// handleRead (virtual function required by SocketTask) that calls processRead
+// (which has to be implemented in derived) as long as new input is available.
 class GeneralCommTask : public SocketTask, public RequestStatisticsAgent {
   GeneralCommTask(GeneralCommTask const&) = delete;
   GeneralCommTask const& operator=(GeneralCommTask const&) = delete;
@@ -82,6 +86,9 @@ class GeneralCommTask : public SocketTask, public RequestStatisticsAgent {
   void handleTimeout() override final;
 
  protected:
+  void fillWriteBuffer();  // fills SocketTasks _writeBuffer
+                           // _writeBufferStatistics from
+                           // _writeBuffers/_writeBuffersStats
   GeneralServer* const _server;
   GeneralRequest* _request;  // the request with possible incomplete body
   ConnectionInfo _connectionInfo;

arangod/GeneralServer/HttpCommTask.cpp

@@ -448,8 +448,7 @@ bool HttpCommTask::processRead() {
     }
 
     // read "bodyLength" from read buffer and add this body to "httpRequest"
-    _requestAsHttp()->setBody(_readBuffer->c_str() + _bodyPosition,
-                              _bodyLength);
+    requestAsHttp()->setBody(_readBuffer->c_str() + _bodyPosition, _bodyLength);
 
     LOG(TRACE) << "" << std::string(_readBuffer->c_str() + _bodyPosition,
                                     _bodyLength);
@@ -491,7 +490,7 @@ bool HttpCommTask::processRead() {
     // the connection
     LOG(DEBUG) << "connection close requested by client";
     _closeRequested = true;
-  } else if (_requestAsHttp()->isHttp10() && connectionType != "keep-alive") {
+  } else if (requestAsHttp()->isHttp10() && connectionType != "keep-alive") {
     // HTTP 1.0 request, and no "Connection: Keep-Alive" header sent
     // we should close the connection
     LOG(DEBUG) << "no keep-alive, connection close requested by client";
@@ -554,7 +553,7 @@ void HttpCommTask::processRequest() {
   // check for deflate
   bool found;
 
-  auto httpRequest = _requestAsHttp();
+  auto httpRequest = requestAsHttp();
   std::string const& acceptEncoding =
       httpRequest->header(StaticStrings::AcceptEncoding, found);
 
@@ -736,20 +735,6 @@ bool HttpCommTask::checkContentLength(bool expectContentLength) {
   return true;
 }
 
-void HttpCommTask::fillWriteBuffer() {
-  if (!hasWriteBuffer() && !_writeBuffers.empty()) {
-    StringBuffer* buffer = _writeBuffers.front();
-    _writeBuffers.pop_front();
-
-    TRI_ASSERT(buffer != nullptr);
-
-    TRI_request_statistics_t* statistics = _writeBuffersStats.front();
-    _writeBuffersStats.pop_front();
-
-    setWriteBuffer(buffer, statistics);
-  }
-}
-
 void HttpCommTask::processCorsOptions() {
   HttpResponse response(GeneralResponse::ResponseCode::OK);
 
@@ -928,7 +913,8 @@ GeneralResponse::ResponseCode HttpCommTask::authenticateRequest() {
   auto context = (_request == nullptr) ? nullptr : _request->requestContext();
 
   if (context == nullptr && _request != nullptr) {
-    bool res = GeneralServerFeature::HANDLER_FACTORY->setRequestContext(_request);
+    bool res =
+        GeneralServerFeature::HANDLER_FACTORY->setRequestContext(_request);
 
     if (!res) {
       return GeneralResponse::ResponseCode::NOT_FOUND;
@@ -956,10 +942,10 @@ void HttpCommTask::sendChunk(StringBuffer* buffer) {
 }
 
 // convert internal GeneralRequest to HttpRequest
-HttpRequest* HttpCommTask::_requestAsHttp() {
+HttpRequest* HttpCommTask::requestAsHttp() {
   HttpRequest* request = dynamic_cast<HttpRequest*>(_request);
   if (request == nullptr) {
-    // everything is borken FIXME
+    THROW_ARANGO_EXCEPTION(TRI_ERROR_INTERNAL);
   }
   return request;
 };

arangod/GeneralServer/HttpCommTask.h

@@ -15,7 +15,7 @@ class HttpCommTask : public GeneralCommTask {
  public:
   HttpCommTask(GeneralServer*, TRI_socket_t, ConnectionInfo&&, double timeout);
 
-  bool processRead() override;
+  bool processRead() override;  // called by handleRead
   virtual void processRequest() override;
 
   void addResponse(GeneralResponse* response) override {
@@ -35,13 +35,11 @@ class HttpCommTask : public GeneralCommTask {
   bool handleRead() override final;  // required by SocketTask
 
   void signalTask(TaskData*) override final;
-  // resets the internal state
-  // this method can be called to clean up when the request handling aborts
-  // prematurely
+  // resets the internal state this method can be called to clean up when the
+  // request handling aborts prematurely
   virtual void resetState(bool close) override final;
 
-  void fillWriteBuffer();  // fills the write buffer
-  HttpRequest* _requestAsHttp();
+  HttpRequest* requestAsHttp();
   void addResponse(HttpResponse*);
   void finishedChunked();
   // check the content-length header of a request and fail it is broken