Index: trunk/MagicSoft/Control/SubsystemIO/Changelog =================================================================== --- trunk/MagicSoft/Control/SubsystemIO/Changelog (revision 1113) +++ trunk/MagicSoft/Control/SubsystemIO/Changelog (revision 1113) @@ -0,0 +1,2 @@ +- Documented the implementation details in Subsystem.plain.hxx +- Introduced the TODO file where things to do are specified. Filled in there only few things Index: trunk/MagicSoft/Control/SubsystemIO/Subsystem.plain.hxx =================================================================== --- trunk/MagicSoft/Control/SubsystemIO/Subsystem.plain.hxx (revision 1056) +++ trunk/MagicSoft/Control/SubsystemIO/Subsystem.plain.hxx (revision 1113) @@ -219,5 +219,13 @@ - +///////////////////////////////////////////////////////////////////////// +//////////////// 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,16 +233,25 @@ */ 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,8 +268,26 @@ 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,4 +296,9 @@ return ret; } + + /** + * Accessor function for reporting bool variable that takes care of + * properly locking the resource + */ inline void SetReporting(bool trueValue) { @@ -268,26 +308,92 @@ } - //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(); Index: trunk/MagicSoft/Control/SubsystemIO/TODO =================================================================== --- trunk/MagicSoft/Control/SubsystemIO/TODO (revision 1113) +++ trunk/MagicSoft/Control/SubsystemIO/TODO (revision 1113) @@ -0,0 +1,4 @@ +- Copy (and adapt) the implementation comments from Subsystem.plain.hxx to Subsystem.orig.hxx +- Subsystem::reportPeriod change to miliseconds. Change then usleep calls and PeriodicActions parameters. +- Subsystem::ClosingChannel is redundant? +- Generate documentation from inlined comments. (ccdoc, doc++). Also arrange the Makefile to do it automatically.