From: Haomai Wang <haomaiwang@gmail.com>
Date: Wed, 8 Oct 2014 07:07:02 +0000 (+0800)
Subject: AsyncMessenger: add comments for structures
X-Git-Tag: v0.88~37^2~4^2~1
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=7f2d660d2f014dfb4930c3d1939b7609543da88b;p=ceph.git

AsyncMessenger: add comments for structures

Signed-off-by: Haomai Wang <haomaiwang@gmail.com>
---

diff --git a/src/msg/async/AsyncConnection.h b/src/msg/async/AsyncConnection.h
index 371bb19a4ac5..05515fd59338 100644
--- a/src/msg/async/AsyncConnection.h
+++ b/src/msg/async/AsyncConnection.h
@@ -33,6 +33,13 @@ using namespace std;
 
 class AsyncMessenger;
 
+/*
+ * AsyncConnection maintains a logic session between two endpoints. In other
+ * word, a pair of addresses can find the only AsyncConnection. AsyncConnection
+ * will handle with network fault or read/write transactions. If one file
+ * descriptor broken, AsyncConnection will maintain the message queue and
+ * sequence, try to reconnect peer endpoint.
+ */
 class AsyncConnection : public Connection {
   const static uint64_t IOV_LEN = 1024;
 
diff --git a/src/msg/async/AsyncMessenger.h b/src/msg/async/AsyncMessenger.h
index 27a4cc321db4..2b64080834a2 100644
--- a/src/msg/async/AsyncMessenger.h
+++ b/src/msg/async/AsyncMessenger.h
@@ -76,33 +76,10 @@ class Worker : public Thread {
 
 
 /*
- * This class handles transmission and reception of messages. Generally
- * speaking, there are several major components:
+ * AsyncMessenger is represented for maintaining a set of asynchronous connections,
+ * it may own a bind address and the accepted connections will be managed by
+ * AsyncMessenger.
  *
- * - Connection
- *    Each logical session is associated with a Connection.
- * - AsyncConnection
- *    Each network connection is handled through a AsyncConnection, which handles
- *    the input and output of each message.  There is normally a 1:1
- *    relationship between AsyncConnection and Connection, but logical sessions may
- *    get handed off between AsyncConnection when sockets reconnect or during
- *    connection races.
- * - IncomingQueue
- *    Incoming messages are associated with an IncomingQueue, and there
- *    is one such queue associated with each AsyncConnection.
- * - DispatchQueue
- *    IncomingQueues get queued in the DispatchQueue, which is responsible
- *    for doing a round-robin sweep and processing them via a worker thread.
- * - AsyncMessenger
- *    It's the exterior class passed to the external message handler and
- *    most of the API details.
- *
- * Lock ordering:
- *
- *   AsyncMessenger::lock
- *       Pipe::pipe_lock
- *           DispatchQueue::lock
- *               IncomingQueue::lock
  */
 
 class AsyncMessenger : public SimplePolicyMessenger {
@@ -405,4 +382,4 @@ public:
    */
 } ;
 
-#endif /* CEPH_SIMPLEMESSENGER_H */
+#endif /* CEPH_ASYNCMESSENGER_H */
diff --git a/src/msg/async/Event.h b/src/msg/async/Event.h
index 48a4c72dfd5d..995c99a3a2dd 100644
--- a/src/msg/async/Event.h
+++ b/src/msg/async/Event.h
@@ -61,6 +61,11 @@ struct FiredFileEvent {
   int mask;
 };
 
+/*
+ * EventDriver is a wrap of event mechanisms depends on different OS.
+ * For example, Linux will use epoll(2), BSD will use kqueue(2) and select will
+ * be used for worst condition.
+ */
 class EventDriver {
  public:
   virtual ~EventDriver() {}       // we want a virtual destructor!!!
@@ -71,6 +76,13 @@ class EventDriver {
   virtual int resize_events(int newsize) = 0;
 };
 
+
+/*
+ * EventCenter maintain a set of file descriptor and handle registered events.
+ *
+ * EventCenter is aimed to used by one thread, other threads access EventCenter
+ * only can use dispatch_event_external method which is protected by lock.
+ */
 class EventCenter {
   struct FileEvent {
     int mask;