Changeset 1113 for trunk/MagicSoft/Control

Timestamp:

12/13/01 17:25:49 (23 years ago)

Author:

casaldaliga

Message:

*** empty log message ***

Location:

trunk/MagicSoft/Control/SubsystemIO

Files:

• Changelog (added)
• Subsystem.plain.hxx (modified) (5 diffs)
• TODO (added)

trunk/MagicSoft/Control/SubsystemIO/Subsystem.plain.hxx

@@ -219 +219 @@
 
     
-
+/////////////////////////////////////////////////////////////////////////
+//////////////// IMPLEMENTATION DETAILS /////////////////////////////////
+/////////////////////////////////////////////////////////////////////////
+
+        //we implement commandListener as a TCPListener derived class, to be   
+        //able to custom the behaviour by overriding it's methods, namely
+        //process, which is called when something arrives.
+        //This could be though as inheritance for implementation, which is not
+        //desired. Can be avoided by using signals/slots
 private:
         /**
@@ -225 +233 @@
          */
     char* ccName;
+
         /**
          * Aproximate (+- 500ms) time in microsec, between each report is sent
-         * to CC
+         * to CC. 
+         * It is expressed in microsec, despite the big uncertanty in these
+         * units, because is feed directly to usleep. This should be changed at
+         * least to ms: remember then to multiply per 1000 in usleep. Take care
+         * also with long periods: usleep will accept only long int
          */  
     unsigned long int reportPeriod;
-    
+
+        /**
+         * TCP/IP port for commandListener socket, here at subsystem machine
+         */
     unsigned short int portCommandListener;
+
+        /**
+         * TCP/IP port for reportListener socket in CC machine
+         */
     unsigned short int portReportListener;
 
-        //we implement commandListener as a TCPListener derived class, to be   
-        //able to custom the behaviour by overriding it's methods, namely
-        //process     
 
         /* maxTimeoutCount. Times subsystem tries to reconnect CC (with reportPeriod)
@@ -251 +268 @@
     short int maxTimeoutCount;
 
-
+        /**
+         * If locked == true Subsystem is being commanded by CC.
+         */
     bool locked;
+
+        /**
+         * When REPOR received, reporting = true, and thread
+         * ReportingAndCheckingLoop is started
+         */
     bool reporting;
+        /**
+         * mutex used to prevent that while reporting state is being checked
+         * in ReportingAndCheckingLoop thread, connection closing is detected
+         * in TCPListener thread and reporting is set at the same time.
+         *
+         * I'm not sure if really needed
+         */
     pthread_mutex_t mutex4reporting;
+        /**
+         * Accessor function for reporting bool variable that takes care of
+         * properly locking the resource
+         */ 
     inline bool Reporting(){ 
         pthread_mutex_lock(&mutex4reporting);
@@ -261 +296 @@
         return ret;
     }
+
+        /**
+         * Accessor function for reporting bool variable that takes care of
+         * properly locking the resource
+         */ 
     inline void SetReporting(bool trueValue)
         {
@@ -268 +308 @@
         }
     
-        //we implement reportSender as an instance of class TCPSender
+        /**
+         * We implement reportSender as an instance of class TCPSender
+         */
     TCPSender reportSender;
-        //reporting and trying connections to cc are implemented as
-        //PeriodicActions     
-
+
+        /**
+         * mutex used to prevent that while report is being send 
+         * in ReportingAndCheckingLoop thread, it is changed at the same time
+         * in the main thread
+         *
+         * This mutex is for sure crucial 
+         *
+         * SuspendComm and ResumeComm lock/unlock it to achieve this purpose
+         */
     pthread_mutex_t mutex4report;
+    
+        /**
+         * Method that we override from TCPListener and gets called when some
+         * command arrives. Here is where all the LOCK, REPOR protocol is
+         * checked and where ReportingAndCheckingLoop thread is started and
+         * stopped 
+         */
     virtual void process();
+
+        /**
+         * Method that we also override from TCPListener and mainly gets
+         * called when endofline is received (connection closed by the other
+         * partner); we don't call it explicitely when the protocol is
+         * not followed (this is done in ResetConnectionToCC). As in
+         * ResetConnectionToCC we properly
+         * close reportSender, and stop ReportingAndCheckingLoop
+         */  
     virtual void ClosingChannel();
-    
+
+        /**
+         * Method that actually sends the report via reportSender and returns
+         * if it was successful (to be used inside a PeriodicAction or
+         * whatever). 
+         * It will also fail if we didn't receive an acknowledge for
+         * last report several (timeoutCount) times, as asynchronously checked
+         * in method CheckReportAcknowledge.
+         * Before actually sending this->reportString it calls the
+         * GenerateReport method that some real subsystems (as Subsystem
+         * derived classes) will override to fill this string. It also calls
+         * ExtractTimeStampFromLastReportTo to be able to check the timestamp
+         * later (in CheckReportAcknowledge) when the acknowledge arrives. 
+         */
     bool SendReport();
+    
+        /** 
+         * Does the actual check of the report acknowledge (when it arrives)
+         * and puts acknowledgeReceivedForLastReport to true; for synchronizing
+         * the threads its better it does
+         * not do anything else like resetting connection itself. If the
+         * acknowledge doesn't arrive acknowledgeReceivedForLastReport will
+         * remain false. SendReport will know and increase the timeoutCount.
+         */
     void CheckReportAcknowledge();
-        //to be able to checkreportacknowledge on has to have the timestamp of
-        //the last report sent
+
+        /**
+         * to be able to checkreportacknowledge on has to have the timestamp of
+         * the last report sent
+         */
     char lastTimeStamp[TIMESTAMP_LEN];
-    void ExtractTimeStampFromLastReportTo(char *);
+
+        /**
+         * Extracts this timestamp to its parameter lastTimeStamp
+         */
+    void ExtractTimeStampFromLastReportTo(char * lastTimeStamp);
+
+        /**
+         * the thread handle itself for ReportingAndCheckingLoop
+         */
     pthread_t reportThread;
+
+        /**
+         * make up for pthread use. Allows pthread to effectively start a
+         * non-static function, which is very convenient to avoid the use of
+         * self
+         */ 
     inline static void * pthread_ReportingAndCheckingLoop(void* self)
         { 
             return (void *) ( ((Subsystem* )self)->ReportingAndCheckingLoop() );
         }
-    
-            
+
+        /** 
+         * The actual method started in reportThread
+         */
     void * ReportingAndCheckingLoop();