From 3c701cb56d40ac42d6ee330d1cf7d15c4aae29d2 Mon Sep 17 00:00:00 2001 From: Ryan Date: Thu, 28 May 2009 13:45:18 +0200 Subject: [PATCH] add long description to website --- README | 8 +++-- website/index.html | 80 ++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 78 insertions(+), 10 deletions(-) diff --git a/README b/README index f56c4dcd82..b6189a7483 100644 --- a/README +++ b/README @@ -1,7 +1,9 @@ -To build +Purely evented I/O for V8 javascript. + +See http://tinyclouds.org/node for more information. + +To build ./configure make make install - -See http://tinyclouds.org/node or website/index.html for documentation. diff --git a/website/index.html b/website/index.html index 52d8ba481e..f7858e7b0e 100644 --- a/website/index.html +++ b/website/index.html @@ -37,9 +37,74 @@ and execute it with the node program Server running at http://127.0.0.1:8000/ -

See the API documentation for more examples. +

Node's goal is to provide easy, scalable concurrency. In the above example, +the 2 second delay does not prevent the server from handling new requests. + +Node notifies the operating system (through epoll(7)) that it +should be notified when the 2 seconds are up, or if a new connection is +made—then it goes to sleep. If someone new connects, then it executes +the callback again. Each connection is only a small allocation on the heap. + +

This is in contrast to most scripting languages (and all other +server-side javascript systems) where OS threads are employed to have +concurrency. But thread-based networking +is +relatively +inefficient + +and +difficult +to +use. +Node will show much better memory performance under high-loads + +than other systems (i.e. all other javascript server-side systems) +which allocate 2mb thread stacks for each connection. + +

For networking, Node is similar to systems like +Ruby's Event Machine +or +Python's Twisted. +But Node also provides full access to the file system in a non-blocking way. +(This is done by using an internal thread pool to handle file system calls.) +Because Javascript does not have I/O libraries and because nothing in +Node blocks, a Node programmer is going to find it difficult to write slow +servers—even if they don't understand how the concurrency system +works. + +

Node's HTTP API has grown out of my difficulties while developing for +Merb and Ebb. Because of limiting low-level design choices, streaming data +through Rack-based frameworks is difficult or impossible. Streaming is +important for large requests or responses (uploads or downloads), so that +the data is not buffered in memory. Other small problems, the incorrect +assumption that all message headers have unique fields are dealt with. The +result is a fast, scalable, and complete low-level HTTP API which can be +built upon. + +

Evented program is different. It requires the program to change how they +view the problem. But it provides many benefits and it more closely matches +what the machine is actually doing. In someways threaded programming is like +fitting a square block into a round hole, and all of the deadlocks and +memory inefficiencies that come from that are a result of the struggle. +Javascript, thankfully, has no concept of threads +and never will. It has a very lucid closures and anonymous functions, +which make evented programming tolerable. + +

"But what about multiple-processor concurrency?", you ask. "Threads are +necessary to scale programs to multi-core computers." The name Node +should give some hint at how it is envisioned being used. Processes are +necessary to scale to multi-core computers, not memory-sharing threads. The +fundamentals of scalable systems are fast networking and non-blocking +design—the rest is message passing. In the future, I'd like Node to +be able to spawn new processes, have a library for passing JSON messages, +and be able accept connections from multiple processes (a pre-fork server); +but these are things that fit into the current design and do not require +threads. +

Node is released under an MIT license.

@@ -56,11 +121,10 @@ href="http://s3.amazonaws.com/four.livejournal/20090527/node-0.0.1.tar.gz">node-

Build

-

Node aims to support all POSIX operating systems (including -Windows with mingw) but at the moment it is only being tested on -Linux, Macintosh, and FreeBSD. -The build system requires Python. -V8, on which Node is built, supports only IA-32 and ARM processors. +

Node eventually wants to support all POSIX operating systems (including +Windows with mingw) but at the moment it is only being tested on Linux, +Macintosh, and FreeBSD. The build system requires Python. V8, on which +Node is built, supports only IA-32 and ARM processors. 

 ./configure
@@ -68,7 +132,9 @@ make
 make install
-

To run the unit tests +

Then have a look at the API documentation. + +

To run the tests 

 ./configure --debug