[Csp-commits] svn:csp r1183 - trunk/CSP/SimNet

[<sv...@ww...>]

Author: mkrose
Date: 2004-07-25 13:34:10 -0700 (Sun, 25 Jul 2004)
New Revision: 1183

Modified:
   trunk/CSP/SimNet/Sockets.h
   trunk/CSP/SimNet/StopWatch.h
   trunk/CSP/SimNet/TestMessage.net
Log:
Add doxygen comments to a few files.

Browse at: https://www.zerobar.net/viewcvs/viewcvs.cgi?view=rev&rev=1183

Modified: trunk/CSP/SimNet/Sockets.h
===================================================================
--- trunk/CSP/SimNet/Sockets.h	2004-07-25 20:33:45 UTC (rev 1182)
+++ trunk/CSP/SimNet/Sockets.h	2004-07-25 20:34:10 UTC (rev 1183)
@@ -29,34 +29,50 @@
 #define _WINSOCKAPI_
 #include <cc++/network.h>
 
-
 namespace simnet {
 
+
+/** Minimal wrapper for GNU CommonC++ UDPReceive.
+ *
+ *  Exposes several protected methods.
+ */
 class DatagramReceiveSocket: public ost::UDPReceive {
 public:
 	DatagramReceiveSocket(const ost::InetHostAddress &host, ost::tpport_t port):
 	    ost::UDPReceive(host, port) { }
+
 	Error connect(const ost::InetHostAddress &host, ost::tpport_t port) {
 		return ost::UDPReceive::connect(host, port);
 	}
+
 	Error disconnect(void) { return ost::UDPReceive::disconnect(); }
-	bool isPendingReceive(timeout_t timeout) {
+
+	inline bool isPendingReceive(timeout_t timeout) {
 		return ost::UDPReceive::isPendingReceive(timeout);
 	}
+
 	inline int peek(void *buf, size_t len) {
 		return ost::UDPReceive::peek(buf, len);
 	}
 };
 
+
+/** Minimal wrapper for GNU CommonC++ UDPTransmit.
+ *
+ *  Exposes several protected methods.
+ */
 class DatagramTransmitSocket: public ost::UDPTransmit {
 public:
 	DatagramTransmitSocket(): ost::UDPTransmit() { }
-	Error connect(const ost::InetHostAddress &host, ost::tpport_t port) {
+
+	inline Error connect(const ost::InetHostAddress &host, ost::tpport_t port) {
 		return ost::UDPTransmit::connect(host, port);
 	}
-	Error disconnect(void) { return ost::UDPTransmit::disconnect(); }
+
+	inline Error disconnect(void) { return ost::UDPTransmit::disconnect(); }
 };
 
+
 } // namespace simnet
 
 #endif // __SIMNET_SOCKETS_H__

Modified: trunk/CSP/SimNet/StopWatch.h
===================================================================
--- trunk/CSP/SimNet/StopWatch.h	2004-07-25 20:33:45 UTC (rev 1182)
+++ trunk/CSP/SimNet/StopWatch.h	2004-07-25 20:34:10 UTC (rev 1183)
@@ -30,22 +30,84 @@
 
 namespace simnet {
 
+
+/** Class for managing iterations of a timed loop.
+ *
+ *  StopWatch is intended to be used to regulate the number of iterations
+ *  of tight loops that are restricted to run for a limited amount of time.
+ *  Rather than continuously polling the system clock (which can incur
+ *  significant overhead), we keep a running estimate of how long each
+ *  iteration requires in order to predict how many iterations can fit
+ *  within the alotted time.  If the loop takes longer than expected, the
+ *  estimated time per iteration is increased.  If the iterations complete
+ *  early, we increase the estimated time per iteration and continue with
+ *  additional iterations.  Assuming that the iteration time is reasonably
+ *  consistent, the estimated loop time and iteration counts quickly
+ *  converge.
+ *
+ *  Example usage:
+ *
+ *  @code
+ *  void loop(double timeout) {
+ *    // static stopwatch timing data (not threadsafe as is)
+ *    static simnet::StopWatch::Data swdata;
+ *    StopWatch watch(timeout, swdata);
+ *    watch.start();
+ *    do {
+ *      // main loop action here (may exit early with break;)
+ *    } while (!watch.checkExpired());
+ *  }
+ *  @endcode
+ *
+ */
 class StopWatch {
 public:
+
+	/** Internal timing data.  Declare separate, persistent Data instance for each
+	 *  loop that needs to be timed.  Beware that using static Data instances isn't
+	 *  thread-safe.
+	 */
 	struct Data {
 		double scale;
 		// default to 100 us per iteration inital guess, adjust as needed
 		Data(float itertime=0.0001): scale(1.0/itertime) {}
 	};
+
+	/** Construct a new stop watch.
+	 *
+	 *  @param timeout The maximum time to spend in the timed loop (seconds).
+	 *  @param data The persistent Data instance used to store timing data for this loop.
+	 */
 	StopWatch(double timeout, Data &data): m_data(data), m_tally(0), m_count(0), m_counts(0), m_timeout(timeout) {
 		resetCount(timeout);
 		SIMNET_LOG(TIMING, DEBUG, "STOPWATCH: " << m_counts << " iterations ~ " << (timeout * 1000.0) << " ms, scale=" << m_data.scale);
 		m_DEBUG_extra = 0;
 	}
+
+	/** Start the stop watch.  Call this right before starting the timed loop.
+	 */
 	inline void start() { m_start_time = simdata::get_realtime(); }
+
+	/** Force a check of the elapsed time, even if we still expect to be able to
+	 *  complete more iterations in the allotted time.
+	 *
+	 *  Call this method after any unusual events occur within the timed loop that
+	 *  may take much longer than the average iteration.  The iteration timing
+	 *  estimate will not be updated, and additional iterations will be scheduled
+	 *  if time remains.  If time has expired, the next checkExpired() will return
+	 *  true and exit the loop.
+	 */
 	void forceCheck() {
 		resetCount(m_timeout - elapsed());
 	}
+
+	/** Test if the timout has expired.
+	 *
+	 *  Simply counts iterations, returning false until the expected number have
+	 *  completed.  At that point it checks the elapsed time and updates the time
+	 *  per iteration estimate.  If more time is left, additional iterations are
+	 *  scheduled and it returns false.  Otherwise it returns true.
+	 */
 	inline bool checkExpired() {
 		if (--m_count > 0) return false;
 		double dt = elapsed();
@@ -64,6 +126,11 @@
 		m_DEBUG_extra += m_count;
 		return (m_count < 1);
 	}
+
+	/** Updates the iteration time estimate based on all iterations to this
+	 *  point.  Call this before exiting the loop early (ie. by any means
+	 *  other than checkExpired()).
+	 */
 	inline void calibrate() {
 		resetCount(0.0);
 		if (m_tally >= 10) {
@@ -75,9 +142,20 @@
 			}
 		}
 	}
+
+	/** Return the time elapsed since the watch was started.  Gets the
+	 *  current system time in order to compute the elapsed time.
+	 */
 	inline double elapsed() {
 		return simdata::get_realtime() - m_start_time;
 	}
+
+	/** Get the system time at which the watch was started.
+	 */
+	inline double getStartTime() {
+		return m_start_time;
+	}
+
 private:
 	Data &m_data;
 	int m_tally;

Modified: trunk/CSP/SimNet/TestMessage.net
===================================================================
--- trunk/CSP/SimNet/TestMessage.net	2004-07-25 20:33:45 UTC (rev 1182)
+++ trunk/CSP/SimNet/TestMessage.net	2004-07-25 20:34:10 UTC (rev 1183)
@@ -2,6 +2,8 @@
 
 #include <SimNet/NetworkMessage.h>
 
+// simple message used for testing the network layer.
+// the fields have no particular meaning.
 Message TestMessage BASE=simnet::NetworkMessage {
 	int32 number;
 	std::string helo;