Add more documentation.

[loba.git] / communicator.h

diff --git a/communicator.h b/communicator.h
index fb06d3448be6f7710e365ace3a0c60ea61bd6450..465d0cf573b3951abaeb54a109194c207710229d 100644 (file)
--- a/communicator.h
+++ b/communicator.h
@@ -29,12 +29,23 @@ public:
     communicator();
     ~communicator();
 
+    // Start to listen for incoming messages
     void listen();
 
+    // Send a message to the "dest" mailbox
     void send(const char* dest, message* msg);
+
+    // Try to receive a message.  Returns true on success.
+    // If "wait" is true, blocks until success or error.
     bool recv(message*& msg, m_host_t& from, bool wait);
+
+    // Try to flush pending sending communications.
+    // If "wait" is true, blocks until success.
     void flush(bool wait);
 
+    // Advertise that the next "close" message is the last one, and
+    // that we do not await any message after that, either on the
+    // control or the data channel.
     void next_close_on_ctrl_is_last();
     void next_close_on_data_is_last();
 
@@ -48,18 +59,19 @@ private:
     int send_counter;
 
     // Control channel for receiving
-    m_task_t    ctrl_task;
-    msg_comm_t  ctrl_comm;
-    bool        ctrl_close_is_last;
+    m_task_t    ctrl_task;          // receive buffer
+    msg_comm_t  ctrl_comm;          // receive communication
+    bool        ctrl_close_is_last; // do not rearm comm after next close
 
     // Data channel for receiving
-    m_task_t    data_task;
-    msg_comm_t  data_comm;
-    bool        data_close_is_last;
+    m_task_t    data_task;          // receive buffer
+    msg_comm_t  data_comm;          // receive communication
+    bool        data_close_is_last; // do not rearm comm after next close
 
     const char* get_ctrl_mbox() const   { return host->get_ctrl_mbox(); }
     const char* get_data_mbox() const   { return host->get_data_mbox(); }
 
+    // Used to test if a communication is over, and to destroy it if it is.
     static bool comm_test_n_destroy(msg_comm_t comm);
 };