Clarify ConnectionHandler documentation

src/connection_handler.hpp

@@ -29,11 +29,14 @@ public:
    *
    * Implementation should:
    * - Parse incoming data using arena allocator when needed
-   * - Use conn_ptr->appendMessage() to queue response data
+   * - Use conn_ptr->appendMessage() to queue response data to be sent
    * - Handle partial messages and streaming protocols appropriately
    * - Can take ownership by calling conn_ptr.release() to pass to other threads
    * - If ownership is taken, handler must call Server::releaseBackToServer()
    * when done
+   * @note `data` is *not* owned by the connection arena, and its lifetime ends
+   * after the call to process_data.
+   * @note May be called from an arbitrary network thread.
    */
   virtual void process_data(std::string_view data,
                             std::unique_ptr<Connection> &conn_ptr) = 0;
@@ -44,7 +47,8 @@ public:
    * @param conn Newly established connection
    *
    * Use this for:
-   * - Connection-specific initialization
+   * - Connection-specific initialization.
+   * @note May be called from an arbitrary accept thread.
    */
   virtual void on_connection_established(Connection &) {}
 
@@ -54,7 +58,8 @@ public:
    * @param conn Connection being closed
    *
    * Use this for:
-   * - Cleanup of connection-specific resources
+   * - Cleanup of connection-specific resources.
+   * @note May be called from an arbitrary accept thread.
    */
   virtual void on_connection_closed(Connection &) {}
 };