[or-cvs] [tor/master] correct the spec for the stream_bw event.

[arma@xxxxxxxx]

Author: Roger Dingledine <arma@xxxxxxxxxxxxxx>
Date: Sat, 10 Oct 2009 15:07:37 -0400
Subject: correct the spec for the stream_bw event.
Commit: e84dc32cb837cd5ba805571dd6764d3d7913ab07

"neonomad" pointed out on or-talk that the order is opposite from the
intuitive order. explain why. we chose to fix the spec rather than the
code because there are controllers like torflow that already expect
the current behavior.
---
 doc/spec/control-spec.txt |   20 ++++++++++++--------
 1 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/doc/spec/control-spec.txt b/doc/spec/control-spec.txt
index f968fa8..eb01641 100644
--- a/doc/spec/control-spec.txt
+++ b/doc/spec/control-spec.txt
@@ -1597,17 +1597,21 @@
 4.1.13. Bandwidth used on an application stream
 
   The syntax is:
-     "650" SP "STREAM_BW" SP StreamID SP BytesRead SP BytesWritten CRLF
-     BytesRead = 1*DIGIT
+     "650" SP "STREAM_BW" SP StreamID SP BytesWritten SP BytesRead CRLF
      BytesWritten = 1*DIGIT
+     BytesRead = 1*DIGIT
+
+  BytesWritten and BytesRead are the number of bytes written and read
+  by the application since the last STREAM_BW event on this stream.
 
-  BytesRead and BytesWritten are the number of bytes read and written since
-  the last STREAM_BW event on this stream.  These events are generated about
-  once per second per stream; no events are generated for streams that have
-  not read or written.
+  Note that from Tor's perspective, *reading* a byte on a stream means
+  that the application *wrote* the byte. That's why the order of "written"
+  vs "read" is opposite for stream_bw events compared to bw events.
 
-  These events apply only to streams entering Tor (such as on a SOCKSPort,
-  TransPort, or so on).  They are not generated for exiting streams.
+  These events are generated about once per second per stream; no events
+  are generated for streams that have not written or read. These events
+  apply only to streams entering Tor (such as on a SOCKSPort, TransPort,
+  or so on). They are not generated for exiting streams.
 
 4.1.14. Per-country client stats
 
-- 
1.5.6.5