From 74977804b139df85d2568aaa92980e483c00f2ef Mon Sep 17 00:00:00 2001
From: Nav <nav@navnav.me>
Date: Tue, 29 Mar 2022 14:54:55 +0100
Subject: [PATCH] Tidying

---
 src/DebugServers/GdbRsp/Connection.hpp        | 28 ++++++++++++++++---
 src/DebugServers/GdbRsp/GdbRspDebugServer.hpp |  8 ++++--
 2 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/src/DebugServers/GdbRsp/Connection.hpp b/src/DebugServers/GdbRsp/Connection.hpp
index 146ac362..a46951b5 100644
--- a/src/DebugServers/GdbRsp/Connection.hpp
+++ b/src/DebugServers/GdbRsp/Connection.hpp
@@ -28,6 +28,10 @@ namespace Bloom::DebugServers::Gdb
         Connection() = delete;
         Connection(const Connection&) = delete;
         Connection& operator = (Connection&) = delete;
+
+        /*
+         * TODO: Implement this. For now, use the move constructor.
+         */
         Connection& operator = (Connection&&) = delete;
 
         Connection(Connection&& other) noexcept
@@ -69,16 +73,24 @@ namespace Bloom::DebugServers::Gdb
     private:
         std::optional<int> socketFileDescriptor;
 
-        EpollInstance epollInstance = EpollInstance();
-
         struct sockaddr_in socketAddress = {};
         int maxPacketSize = 1024;
 
         /**
-         * The interruptEventNotifier allows us to interrupt blocking IO calls on the GDB debug server.
-         * Under the hood, this is just a wrapper for a Linux event notifier. See the EventNotifier class for more.
+         * The interruptEventNotifier (instance of EventNotifier) allows us to interrupt blocking I/O calls on this
+         * connection's socket. Under the hood, the EventNotifier class is just an RAII wrapper for a Linux eventfd
+         * object.
+         *
+         * The file descriptors of the eventfd object and the socket are both added to an EpollInstance (which is just
+         * an RAII wrapper for a Linux epoll instance). The EpollInstance object is then used to wait for events on
+         * either of the two file descriptors. See any of the Connection I/O functions (e.g Connection::read()) for
+         * more on this.
+         *
+         * See the EventNotifier and EpollInstance classes for more.
          */
         EventNotifier& interruptEventNotifier;
+        EpollInstance epollInstance = EpollInstance();
+
         bool readInterruptEnabled = false;
 
         /**
@@ -132,8 +144,16 @@ namespace Bloom::DebugServers::Gdb
          */
         void write(const std::vector<unsigned char>& buffer);
 
+        /**
+         * Removes this->interruptEventNotifier's file descriptor from the EpollInstance (this->epollInstance),
+         * preventing subsequent I/O operations on this->socketFileDescriptor from being interrupted.
+         */
         void disableReadInterrupts();
 
+        /**
+         * Inserts this->interruptEventNotifier's file descriptor into the EpollInstance (this->epollInstance),
+         * allowing for subsequent I/O operations on this->socketFileDescriptor to be interrupted.
+         */
         void enableReadInterrupts();
     };
 }
diff --git a/src/DebugServers/GdbRsp/GdbRspDebugServer.hpp b/src/DebugServers/GdbRsp/GdbRspDebugServer.hpp
index 11e6e5f1..512d83d7 100644
--- a/src/DebugServers/GdbRsp/GdbRspDebugServer.hpp
+++ b/src/DebugServers/GdbRsp/GdbRspDebugServer.hpp
@@ -89,12 +89,14 @@ namespace Bloom::DebugServers::Gdb
         int serverSocketFileDescriptor = -1;
 
         /**
-         * We don't listen on the this->serverSocketFileDescriptor directly. Instead, we use an EpollInstance to
-         * monitor both this->serverSocketFileDescriptor and this->interruptEventNotifier. This allows us to interrupt
-         * any blocking socket IO calls when EventNotifier::notify() is called on this->interruptEventNotifier.
+         * When waiting for a connection, we don't listen on the this->serverSocketFileDescriptor directly. Instead,
+         * we use an EpollInstance to monitor both this->serverSocketFileDescriptor and this->interruptEventNotifier.
+         * This allows us to interrupt any blocking socket IO calls when EventNotifier::notify() is called on
+         * this->interruptEventNotifier.
          *
          * See GdbRspDebugServer::init()
          * See DebugServer::interruptEventNotifier
+         * See EpollInstance
          * See EventNotifier
          */
         EpollInstance epollInstance = EpollInstance();