From 6f31a3763d3520d8a3e030db783a251af2752b24 Mon Sep 17 00:00:00 2001 From: Ryan Dahl Date: Thu, 17 Sep 2009 15:15:05 +0200 Subject: [PATCH] Add more explanation to docs for request.finish(). --- doc/api.html | 32 ++++++++++++++++++++++++++++---- doc/api.txt | 32 +++++++++++++++++++++++++++++--- doc/node.1 | 42 +++++++++++++++++++++++++++++++++++++----- 3 files changed, 94 insertions(+), 12 deletions(-) diff --git a/doc/api.html b/doc/api.html index be20f95dfa..2c21ac6ad8 100644 --- a/doc/api.html +++ b/doc/api.html @@ -1319,7 +1319,7 @@ argument should be either "utf8" or as it is faster.

-request.finish(response_listener) +request.finish(responseListener)

@@ -1327,10 +1327,34 @@ 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);
+});
+

node.http.ClientResponse

@@ -1906,7 +1930,7 @@ init (Handle<Object> target) diff --git a/doc/api.txt b/doc/api.txt index 8a1e818feb..9e17f6557e 100644 --- a/doc/api.txt +++ b/doc/api.txt @@ -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); +}); +---------------------------------------- + diff --git a/doc/node.1 b/doc/node.1 index 0332a29e0b..a701d1d0d9 100644 --- a/doc/node.1 +++ b/doc/node.1 @@ -1,11 +1,11 @@ .\" Title: node .\" Author: .\" Generator: DocBook XSL Stylesheets v1.73.2 -.\" 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