From 243325079bddd4cf7e4114e414f5fcfa64bb4a7e Mon Sep 17 00:00:00 2001
From: Greg Farnum <gregf@hq.newdream.net>
Date: Thu, 10 Dec 2009 14:32:13 -0800
Subject: [PATCH] msgr: Add at least a little documentation

---
 src/msg/SimpleMessenger.cc | 13 +++++++++++++
 src/msg/SimpleMessenger.h  | 12 ++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/src/msg/SimpleMessenger.cc b/src/msg/SimpleMessenger.cc
index 227a24b74ae1c..e0689c0dffea5 100644
--- a/src/msg/SimpleMessenger.cc
+++ b/src/msg/SimpleMessenger.cc
@@ -257,6 +257,15 @@ void SimpleMessenger::Accepter::stop()
  * Endpoint
  */
 
+/*
+ * This function delivers incoming messages to the Messenger.
+ * Pipes with messages are kept in queues; when beginning a message
+ * delivery the highest-priority queue is selected, the pipe from the
+ * front of the queue is removed, and its message read. If the pipe
+ * has remaining messages at that priority level, it is re-placed on to the
+ * end of the queue. If the queue is empty; it's removed.
+ * The message is then delivered and the process starts again.
+ */
 void SimpleMessenger::Endpoint::dispatch_entry()
 {
   endpoint_lock.Lock();
@@ -1173,6 +1182,10 @@ void SimpleMessenger::Pipe::requeue_sent()
   }
 }
 
+/*
+ * Tears down the Pipe's message queues, and removes them from the Endpoint.
+ * Must hold pipe_lock prior to calling.
+ */
 void SimpleMessenger::Pipe::discard_queue()
 {
   dout(10) << "discard_queue" << dendl;
diff --git a/src/msg/SimpleMessenger.h b/src/msg/SimpleMessenger.h
index 8fd31715d6725..86396f2c947c4 100644
--- a/src/msg/SimpleMessenger.h
+++ b/src/msg/SimpleMessenger.h
@@ -35,6 +35,17 @@ using namespace __gnu_cxx;
 #include "tcp.h"
 
 
+/*
+ * This class handles transmission and reception of messages. Generally
+ * speaking, there are 3 major components:
+ * 1) SimpleMessenger. It's the exterior class and handles the others.
+ * 2) Endpoint. Wraps the Messenger object which this SimpleMessenger serves,
+ *    and handles individual message delivery. Once upon a time you could have
+ *    multiple Endpoints in a SimpleMessenger; now it *might* be simpler and
+ *    cleaner to merge the class with SimpleMessenger itself.
+ * 3) Pipe. Each network connection is handled through a pipe, which handles
+ *    the input and output of each message.
+ */
 
 /* Rank - per-process
  */
@@ -217,6 +228,7 @@ private:
 
     //we have two queue_received's to allow local signal delivery
     // via Message * (that doesn't actually point to a Message)
+    //Don't call while holding pipe_lock!
     void queue_received(Message *m, int priority) {
       list<Message *>& queue = in_q[priority];
 
-- 
2.39.5