This repository has been archived by the owner. It is now read-only.
Permalink
Browse files

Add more explanation to docs for request.finish().

  • Loading branch information...
ry committed Sep 17, 2009
1 parent b54fad9 commit 6f31a3763d3520d8a3e030db783a251af2752b24
Showing with 94 additions and 12 deletions.
  1. +28 −4 doc/api.html
  2. +29 −3 doc/api.txt
  3. +37 −5 doc/node.1
View
@@ -1319,18 +1319,42 @@ <h4 id="_tt_node_http_clientrequest_tt"><tt>node.http.ClientRequest</tt></h4>
as it is faster.</p></div>
</dd>
<dt class="hdlist1">
-<tt>request.finish(response_listener)</tt>
+<tt>request.finish(responseListener)</tt>
</dt>
<dd>
<p>
Finishes sending the request. If any parts of the body are
unsent, it will flush them to the socket. If the request is
chunked, this will send the terminating <tt>"0\r\n\r\n"</tt>.
</p>
-<div class="paragraph"><p>The parameter <tt>response_listener</tt> is a callback which
+<div class="paragraph"><p>The parameter <tt>responseListener</tt> is a callback which
will be executed when the response headers have been received.
-The <tt>response_listener</tt> callback is executed with one
+The <tt>responseListener</tt> callback is executed with one
argument which is an instance of <tt>node.http.ClientResponse</tt>.</p></div>
+<div class="paragraph"><p>In the <tt>responseListener</tt> callback, one can add more listeners to the
+response, in particular listening for the <tt>"body"</tt> event. Note that
+the <tt>responseListener</tt> is called before any part of the body is receieved,
+so there is no need to worry about racing to catch the first part of the
+body. As long as a listener for <tt>"body"</tt> is added during the
+<tt>responseListener</tt> callback, the entire body will be caught.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>// Good
+request.finish(function (response) {
+ response.addListener("body", function (chunk) {
+ puts("BODY: " + chunk);
+ });
+});
+
+// Bad - misses all or part of the body
+request.finish(function (response) {
+ setTimeout(function () {
+ response.addListener("body", function (chunk) {
+ puts("BODY: " + chunk);
+ });
+ }, 10);
+});</tt></pre>
+</div></div>
</dd>
</dl></div>
<h4 id="_tt_node_http_clientresponse_tt"><tt>node.http.ClientResponse</tt></h4>
@@ -1906,7 +1930,7 @@ <h2 id="_extension_api">Extension API</h2>
<div id="footer">
<div id="footer-text">
Version 0.1.10<br />
-Last updated 2009-09-15 22:34:24 CEST
+Last updated 2009-09-17 15:13:13 CEST
</div>
</div>
</body>
View
@@ -845,16 +845,42 @@ argument should be either +"utf8"+ or
as it is faster.
-+request.finish(response_listener)+ ::
++request.finish(responseListener)+ ::
Finishes sending the request. If any parts of the body are
unsent, it will flush them to the socket. If the request is
chunked, this will send the terminating +"0\r\n\r\n"+.
+
-The parameter +response_listener+ is a callback which
+The parameter +responseListener+ is a callback which
will be executed when the response headers have been received.
-The +response_listener+ callback is executed with one
+The +responseListener+ callback is executed with one
argument which is an instance of +node.http.ClientResponse+.
++
+In the +responseListener+ callback, one can add more listeners to the
+response, in particular listening for the +"body"+ event. Note that
+the +responseListener+ is called before any part of the body is receieved,
+so there is no need to worry about racing to catch the first part of the
+body. As long as a listener for +"body"+ is added during the
++responseListener+ callback, the entire body will be caught.
++
+----------------------------------------
+// Good
+request.finish(function (response) {
+ response.addListener("body", function (chunk) {
+ puts("BODY: " + chunk);
+ });
+});
+
+// Bad - misses all or part of the body
+request.finish(function (response) {
+ setTimeout(function () {
+ response.addListener("body", function (chunk) {
+ puts("BODY: " + chunk);
+ });
+ }, 10);
+});
+----------------------------------------
+
View
@@ -1,11 +1,11 @@
.\" Title: node
.\" Author:
.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
-.\" Date: 09/15/2009
+.\" Date: 09/17/2009
.\" Manual:
.\" Source:
.\"
-.TH "NODE" "1" "09/15/2009" "" ""
+.TH "NODE" "1" "09/17/2009" "" ""
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
@@ -1226,17 +1226,49 @@ or
"ascii"\. By default the body uses ASCII encoding, as it is faster\.
.RE
.PP
-request\.finish(response_listener)
+request\.finish(responseListener)
.RS 4
Finishes sending the request\. If any parts of the body are unsent, it will flush them to the socket\. If the request is chunked, this will send the terminating
"0\er\en\er\en"\.
.sp
The parameter
-response_listener
+responseListener
is a callback which will be executed when the response headers have been received\. The
-response_listener
+responseListener
callback is executed with one argument which is an instance of
node\.http\.ClientResponse\.
+.sp
+In the
+responseListener
+callback, one can add more listeners to the response, in particular listening for the
+"body"
+event\. Note that the
+responseListener
+is called before any part of the body is receieved, so there is no need to worry about racing to catch the first part of the body\. As long as a listener for
+"body"
+is added during the
+responseListener
+callback, the entire body will be caught\.
+.sp
+.RS 4
+.nf
+// Good
+request\.finish(function (response) {
+ response\.addListener("body", function (chunk) {
+ puts("BODY: " + chunk);
+ });
+});
+
+// Bad \- misses all or part of the body
+request\.finish(function (response) {
+ setTimeout(function () {
+ response\.addListener("body", function (chunk) {
+ puts("BODY: " + chunk);
+ });
+ }, 10);
+});
+.fi
+.RE
.RE
.RE
.sp

0 comments on commit 6f31a37

Please sign in to comment.