From 53b76732a98d08618baa052b004c9e57811c583e Mon Sep 17 00:00:00 2001
From: sehraf <sehraf42@gmail.com>
Date: Sun, 3 May 2020 14:54:52 +0200
Subject: [PATCH] pqisslistener: document accept() process

---
 libretroshare/src/pqi/pqissllistener.h | 67 ++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/libretroshare/src/pqi/pqissllistener.h b/libretroshare/src/pqi/pqissllistener.h
index 42ad0d0c2..85af2d869 100644
--- a/libretroshare/src/pqi/pqissllistener.h
+++ b/libretroshare/src/pqi/pqissllistener.h
@@ -34,6 +34,73 @@
 
 #define RS_PQISSL_AUTH_DOUBLE_CHECK 1
 
+
+//  This is a simple overview of how the listener is setup, ticked (calling accept) and peers added to it.
+//  On the highest level (RsServer) the listener lives inside the pqisslpersongrp class (variable: "pqih").
+//  Inside pqisslpersongrp the listener is stored in "pqil".
+//
+//  The listener has an internal list with incoming connections that are handled in a similar fashion to pqissl.
+//  (Mainly setting up the socket (non-blocking) and establisching the ssl handshake.)
+//  When everything went fine the connection is passed to pqissl in finaliseConnection()
+//
+//  This is how the listener is initialized during start up:
+//
+//   RsServer::StartupRetroShare()
+//      |
+//      +----- pqih = new pqisslpersongrp(serviceCtrl, flags, mPeerMgr);
+//      +----- pqih->init_listener();
+//                  |
+//                  +----- pqil = locked_createListener(laddr);
+//                              |
+//                              +----- return new pqissllistener(laddr, mPeerMgr);
+//
+//
+//  This is how the listener is ticked to call accept:
+//
+//   RsServer::StartupRetroShare()
+//      |
+//      +----- pqih->tick();
+//                  |
+//                  +----- pqil->tick();
+//                              |
+//                              +----- acceptconnection();
+//                              |           |
+//                              |           +----- accecpt()
+//                              |
+//                              +----- continueaccepts();
+//                              +----- finaliseAccepts();
+//                                          |
+//                                          +----- finaliseConnection()
+//                                                      |
+//                                                      +----- pqis->accept()
+//
+//
+//  This is how peers (their id) are registered to the listener:
+//  (This is only used to tell if a connection peer is known or a new one (which is then added))
+//
+//   pqipersongrp::addPeer()
+//      |
+//      +----- pqiperson *pqip = locked_createPerson(id, pqil);
+//      |           |
+//      |           +----- pqiperson *pqip = new pqiperson(id, this);
+//      |           +----- pqissl *pqis = new pqissl((pqissllistener *) listener, pqip, mLinkMgr);
+//      |           +----- pqiconnect *pqisc = new pqiconnect(pqip, rss, pqis);
+//      |           +----- pqip->addChildInterface(PQI_CONNECT_TCP, pqisc);
+//      |                       |
+//      |                       +-- sets kids[type] = pqisc;
+//      |
+//      +----- pqip->reset();
+//      +----- pqip->listen();
+//                  |
+//                  +-- for all kids[]
+//                              |
+//                              +----- listen() ( of class pqiconnect )
+//                                          |
+//                                          +----- listen() ( of class pqissl )
+//                                                      |
+//                                                      +----- pqil->addlistenaddr(PeerId(), this);
+
+
 /***************************** pqi Net SSL Interface *********************************
  */