From e787e11a1b168c48246807b6ec71b3e61816d9c6 Mon Sep 17 00:00:00 2001 From: Ryan Date: Wed, 20 May 2009 16:58:08 +0200 Subject: [PATCH] Begin documentation for file i/o --- website/node.html | 86 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 74 insertions(+), 12 deletions(-) diff --git a/website/node.html b/website/node.html index 72a4643..474139d 100644 --- a/website/node.html +++ b/website/node.html @@ -164,6 +164,27 @@ make install on. All methods and members are camel cased. Constructors always have a capital first letter. +
+
puts(string, callback)
+
Outputs the string and a trailing new-line to stdout. +

The callback argument is optional and mostly useless: it will + notify the user when the operation has completed. Everything in node is + asynchronous; puts() is no exception. This might seem ridiculous + but, if for example, one is piping their output into an NFS'd file, + printf() will block. + There is an internal queue for puts() output, so you can be assured that + output will be displayed in the order it was called. +

+ +
print(string, callback)
+
Like puts() but without the trailing new-line.
+ +
node.debug(string)
+
A synchronous output function. Will block the process and output the + string immediately to stdout. Use with care.
+ +
+

Timers

Timers allow one to schedule execution of a function for a later time. @@ -177,7 +198,38 @@ See Mozilla's documentation for more information. -

File System

+

node.File

+ +

File system I/O has always been tricky because there are not any portable +ways of doing non-blocking file I/O. To get around this, Node uses an internal +thread pool to execute file system calls. Internal request queues exist for +each node.File instance so that multiple commands can be issued at +once without worry that they will reach the file system out of order. +Thus the following is safe: +

file.open("/tmp/blah", "w+");
+file.write("hello ");
+file.write("world");
+file.close();
+Additionally there is a process-wide queue for all commands which operate on +the file system directory structure (like rename and +unlink.) It's important to understand that all of these request queues are +distinct. If, for example, you do +
fileA.write("hello");
+fileB.write("world");
+it could be that +first fileB gets written to and then fileA gets written to. +So if a certain operation order is needed involving multiple files, use the +completion callbacks: +
fileA.write("hello", function () {
+  fileB.write("world");
+});
+ +
+
node.File.rename()
+
+
+
+

node.tcp

@@ -188,6 +240,19 @@ low-level but complete (it does not limit you from any of HTTP's features). The interface abstracts the transfer-encoding (i.e. chunked or identity), message boundaries, and persistent connections. +

HTTP message headers are represented by an array of 2-element arrays like this +

+[ ["Content-Length", "123"]
+, ["Content-Type", "text/plain"]
+, ["Connection", "keep-alive"]
+, ["Accept", "*/*"]
+]
+
+

Dictionary-like objects are popularly used to represent HTTP headers but they are +an incorrect abstraction. It is rare, but possible, to have multiple header lines +with the same field. Setting multiple cookies in a single response, for +example, can only be done with multiple Cookie lines. +

node.http.Server

@@ -225,8 +290,8 @@ chunked or identity), message boundaries, and persistent connections.

node.http.ServerRequest

-

This object is created internally by a HTTP server—not by the user. -It is passed as the first argument to the This object is created internally by a HTTP server—not by the user. +It is passed to the user as the first argument to the request_handler callback.

@@ -254,14 +319,6 @@ class="sh_javascript">request_handler callback.
req.headers
The request headers expressed as an array of 2-element arrays. Read only. - Example: -
-[ ["Content-Length", "123"]
-, ["Content-Type", "text/plain"]
-, ["Connection", "keep-alive"]
-, ["Accept", "*/*"]
-]
-
req.httpVersion
The HTTP protocol version as a string. Read only. Examples: "1.1", @@ -295,6 +352,11 @@ req.onBody = function (chunk) {

node.http.ServerResponse

+

This object is created internally by a HTTP server—not by the user. +It is passed to the user as the second argument to the request_handler callback. + +

res.sendHeader(statusCode, headers)
@@ -334,7 +396,7 @@ res.sendHeader(200, [ ["Content-Length", body.length]

An HTTP client is constructed with a server address as its argument, then the user issues one or more requests. Depending on the server connected to, the client might pipeline the requests or reestablish the connection after each -connection. (CURRENTLY: The client does not pipeline.) +connection. Currently the client does not pipeline requests.

Example of connecting to google.com 

-- 
2.7.4