Bug 742358: Add some documentation to toolkit/devtools/debugger/dbg-transport.js. r=dcamp
authorJim Blandy <jimb@mozilla.com>
Thu, 05 Apr 2012 12:37:21 -0700
changeset 94416 324e1ebd118d47c9b7f164c21015e3877a857395
parent 94415 0b28f9e01c51c6b38f187e8b3f5d4183d4d19ade
child 94417 d3fb71fc5292051c47e143f4eca4d1f902572475
push id886
push userlsblakk@mozilla.com
push dateMon, 04 Jun 2012 19:57:52 +0000
treeherdermozilla-beta@bbd8d5efd6d1 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersdcamp
bugs742358
milestone14.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 742358: Add some documentation to toolkit/devtools/debugger/dbg-transport.js. r=dcamp
toolkit/devtools/debugger/dbg-transport.js
--- a/toolkit/devtools/debugger/dbg-transport.js
+++ b/toolkit/devtools/debugger/dbg-transport.js
@@ -38,47 +38,68 @@
  * ***** END LICENSE BLOCK ***** */
 
 "use strict";
 Cu.import("resource://gre/modules/NetUtil.jsm");
 
 /**
  * An adapter that handles data transfers between the debugger client and
  * server. It can work with both nsIPipe and nsIServerSocket transports so
- * long as the properly created input and output streams are specified. Data is
- * transferred as a JSON packet serialized into a string, with the string length
- * prepended to the packet, followed by a colon ([length]:[packet]). The
- * contents of the JSON packet are specified in the Remote Debugging Protocol
- * specification.
+ * long as the properly created input and output streams are specified.
  *
  * @param aInput nsIInputStream
  *        The input stream.
  * @param aOutput nsIOutputStream
  *        The output stream.
+ *
+ * Given a DebuggerTransport instance dt:
+ * 1) Set dt.hooks to a packet handler object (described below).
+ * 2) Call dt.ready() to begin watching for input packets.
+ * 3) Send packets as you please, and handle incoming packets passed to 
+ *    hook.onPacket.
+ * 4) Call dt.close() to close the connection, and disengage from the event
+ *    loop.
+ *
+ * A packet handler object is an object with two methods:
+ *
+ * - onPacket(packet) - called when we have received a complete packet.
+ *   |Packet| is the parsed form of the packet --- a JavaScript value, not
+ *   a JSON-syntax string.
+ *
+ * - onClosed(status) - called when the connection is closed. |Status| is
+ *   an nsresult, of the sort passed to nsIRequestObserver.
+ * 
+ * Data is transferred as a JSON packet serialized into a string, with the
+ * string length prepended to the packet, followed by a colon
+ * ([length]:[packet]). The contents of the JSON packet are specified in
+ * the Remote Debugging Protocol specification.
  */
 function DebuggerTransport(aInput, aOutput)
 {
   this._input = aInput;
   this._output = aOutput;
 
   this._converter = Cc["@mozilla.org/intl/scriptableunicodeconverter"]
     .createInstance(Ci.nsIScriptableUnicodeConverter);
   this._converter.charset = "UTF-8";
 
   this._outgoing = "";
   this._incoming = "";
+
+  this.hooks = null;
 }
 
 DebuggerTransport.prototype = {
-  _hooks: null,
-  get hooks() { return this._hooks; },
-  set hooks(aHooks) { this._hooks = aHooks; },
-
   /**
-   * Transmit the specified packet.
+   * Transmit a packet.
+   * 
+   * This method returns immediately, without waiting for the entire
+   * packet to be transmitted, registering event handlers as needed to
+   * transmit the entire packet. Packets are transmitted in the order
+   * they are passed to this method.
    */
   send: function DT_send(aPacket) {
     // TODO (bug 709088): remove pretty printing when the protocol is done.
     let data = JSON.stringify(aPacket, null, 2);
     data = this._converter.ConvertFromUnicode(data);
     data = data.length + ':' + data;
     this._outgoing += data;
     this._flushOutgoing();
@@ -104,17 +125,19 @@ DebuggerTransport.prototype = {
 
   onOutputStreamReady: function DT_onOutputStreamReady(aStream) {
     let written = aStream.write(this._outgoing, this._outgoing.length);
     this._outgoing = this._outgoing.slice(written);
     this._flushOutgoing();
   },
 
   /**
-   * Initialize the input stream for reading.
+   * Initialize the input stream for reading. Once this method has been
+   * called, we watch for packets on the input stream, and pass them to
+   * this.hook.onPacket.
    */
   ready: function DT_ready() {
     let pump = Cc["@mozilla.org/network/input-stream-pump;1"]
       .createInstance(Ci.nsIInputStreamPump);
     pump.init(this._input, -1, -1, 0, 0, false);
     pump.asyncRead(this, null);
   },