| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <style type="text/css"> |
| ul { |
| padding: 0; |
| margin: 0; |
| } |
| </style> |
| <script type="text/javascript" src="sh_main.js"></script> |
| <script type="text/javascript" src="sh_javascript.min.js"></script> |
| <link type="text/css" rel="stylesheet" href="pipe.css" /> |
| <link type="text/css" rel="stylesheet" href="sh_vim-dark.css" /> |
| <meta http-equiv="content-type" content="text/html; charset=utf-8" /> |
| <title>node.js</title> |
| </head> |
| <body onload="sh_highlightDocument();"> |
| <div id="toc"> |
| <ol> |
| <li><a href="#download">Download</a></li> |
| <li><a href="#build">Build</a></li> |
| <li><a href="#about">About</a></li> |
| <li><a href="#demo">Demo</a></li> |
| <li><a href="#community">Community</a></li> |
| <li><a href="#contribute">Contribute</a></li> |
| <li><a href="#benchmarks">Benchmarks</a></li> |
| <li><a href="api.html">Documentation</a></li> |
| </ol> |
| </div> |
| <div id="content"> |
| |
| <!-- <h1><a href="http://tinyclouds.org/node">Node</a></h1> --> |
| <img id="logo" src="logo.png" alt="node.js"/> |
| |
| <p id="introduction"> |
| Evented I/O for |
| <a href="http://code.google.com/p/v8/">V8 javascript</a>. |
| </p> |
| |
| <p> |
| An example of a web server written with Node which responds with |
| "Hello World" after waiting two seconds: |
| </p> |
| |
| <pre> |
| var sys = require('sys'), |
| http = require('http'); |
| http.createServer(function (req, res) { |
| setTimeout(function () { |
| res.sendHeader(200, {'Content-Type': 'text/plain'}); |
| res.sendBody('Hello World'); |
| res.finish(); |
| }, 2000); |
| }).listen(8000); |
| sys.puts('Server running at http://127.0.0.1:8000/');</pre> |
| </pre> |
| |
| <p> |
| To run the server, put the code into a file |
| <code>example.js</code> and execute it with the <code>node</code> |
| program |
| </p> |
| <pre class="sh_none"> |
| % node example.js |
| Server running at http://127.0.0.1:8000/</pre> |
| |
| <p> |
| Here is an example of a simple TCP server which listens on port 7000 |
| and echos whatever you send it: |
| </p> |
| |
| <pre> |
| var tcp = require('tcp'); |
| var server = tcp.createServer(function (socket) { |
| socket.setEncoding("utf8"); |
| socket.addListener("connect", function () { |
| socket.send("hello\r\n"); |
| }); |
| socket.addListener("receive", function (data) { |
| socket.send(data); |
| }); |
| socket.addListener("eof", function () { |
| socket.send("goodbye\r\n"); |
| socket.close(); |
| }); |
| }); |
| server.listen(7000, "localhost");</pre> |
| |
| <p> |
| See the <a href="api.html">API documentation</a> for more |
| examples. |
| </p> |
| |
| <h2 id="download">Download</h2> |
| |
| <p> |
| <a href="http://github.com/ry/node/tree/master">git repo</a> |
| </p> |
| <p> |
| 2009.12.06 |
| <a |
| href="http://s3.amazonaws.com/four.livejournal/20091206/node-v0.1.21.tar.gz">node-v0.1.21.tar.gz</a> |
| </p> |
| |
| <h2 id="build">Build</h2> |
| |
| <p> |
| Node eventually wants to support all POSIX operating systems |
| (including Windows with MinGW) but at the moment it is only being |
| tested on <b>Linux</b>, <b>Macintosh</b>, and <b>FreeBSD</b>. The |
| build system requires Python 2.4 or better. V8, on which Node is |
| built, supports only IA-32 and ARM processors. V8 is included in the |
| Node distribution. There are no other dependencies. |
| </p> |
| |
| <pre class="sh_none"> |
| ./configure |
| make |
| make install</pre> |
| |
| <p> |
| Then have a look at the <a href="api.html">API documentation</a>. |
| </p> |
| |
| <p>To run the tests</p> |
| |
| <pre class="sh_none">make test</pre> |
| |
| <h2 id="about">About</h2> |
| |
| <p> |
| Node's goal is to provide an easy way to build scalable network |
| programs. In the above example, the two second delay does not |
| prevent the server from handling new requests. Node tells the |
| operating system (through <code>epoll</code>, <code>kqueue</code>, |
| <code class="sh_none">/dev/poll</code>, or <code>select</code>) |
| 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, if the timeout expires, |
| it executes the inner callback. Each connection is only a small |
| heap allocation. |
| </p> |
| |
| <p> |
| This is in contrast to today's more common concurrency model where |
| OS threads are employed. Thread-based networking |
| <a href="http://www.sics.se/~joe/apachevsyaws.html">is</a> |
| <a href="http://www.kegel.com/c10k.html">relatively</a> |
| <a href="http://bulk.fefe.de/scalable-networking.pdf">inefficient</a> |
| <!-- TODO needs links --> |
| and very difficult to use. |
| |
| Node will show much better memory efficiency under high-loads |
| <!-- TODO benchmark --> |
| than systems which allocate 2mb thread stacks for each connection. |
| |
| Furthermore, users of Node are free from worries of dead-locking |
| the process—there are no locks. Almost no function in Node |
| directly performs I/O, so the process never blocks. Because |
| nothing blocks, less-than-expert programmers are able to develop |
| fast systems. |
| </p> |
| |
| <p> |
| Node is similar in design to and influenced by systems like Ruby's <a |
| href="http://rubyeventmachine.com/">Event Machine</a> or Python's <a |
| href="http://twistedmatrix.com/">Twisted</a>. Node takes the event |
| model a bit further—it presents the event loop as a language |
| construct instead of as a library. In other systems there is always |
| a blocking call to start the event-loop. Typically one defines |
| behavior through callbacks at the beginning of a script and at the |
| end starts a server through a blocking call like |
| <code>EventMachine::run()</code>. In Node there is no such |
| start-the-event-loop call. Node simply enters the event loop after |
| executing the input script. Node exits the event loop when there are |
| no more callbacks to perform. This behavior is like browser |
| javascript—the event loop is hidden from the user. |
| </p> |
| |
| <p> |
| HTTP is a first class protocol in Node. Node's HTTP library has |
| grown out of the author's experiences developing and working with |
| web servers. For example, streaming data through most web frameworks |
| is impossible. Node attempts to correct these problems in its HTTP |
| <a href="http://github.com/ry/http-parser/tree/master">parser</a> |
| and API. Coupled with Node's purely evented infrastructure, it makes |
| a good foundation for web libraries or frameworks. |
| </p> |
| |
| <p> |
| <i> |
| But what about multiple-processor concurrency? Threads are |
| necessary to scale programs to multi-core computers. |
| </i> |
| 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 future versions, Node will be able to fork new |
| processes (using the <a |
| href="http://www.whatwg.org/specs/web-workers/current-work/"> Web |
| Workers API </a>), but this is something that fits well into the |
| current design. |
| </p> |
| |
| <p> |
| See also: <a href="http://s3.amazonaws.com/four.livejournal/20091117/jsconf.pdf">slides</a> from jsconf. |
| </p> |
| |
| |
| <h2 id="demo">Demo</h2> |
| <p> |
| A chat room demo is running at <a |
| href="http://chat.nodejs.org">chat.nodejs.org</a>. The |
| source code for the chat room is at <a |
| href="http://github.com/ry/node_chat/tree/master">http://github.com/ry/node_chat</a>. |
| The chat room is not stable and might occasionally be down. |
| </p> |
| |
| <h2 id="community">Community</h2> |
| <p> |
| For help and discussion subscribe to the mailing list at |
| <a href="http://groups.google.com/group/nodejs">http://groups.google.com/group/nodejs</a> |
| or send an email to <a href="mailto:nodejs+subscribe@googlegroups.com">nodejs+subscribe@googlegroups.com</a>. |
| </p> |
| |
| <p> |
| For real-time discussion, check irc.freenode.net #node.js. |
| </p> |
| |
| <p> |
| <a href="http://wiki.github.com/ry/node">Projects/libraries which are using/for Node.js</a> |
| </p> |
| <h2 id="contribute">Contribute</h2> |
| <p> |
| Patches are always welcome. The process is simple: |
| </p> |
| |
| <pre class="sh_none"> |
| git clone git://github.com/ry/node.git |
| cd node |
| # edit/compile/test |
| git commit -m "Good description of what your patch does" |
| git format-patch HEAD^ |
| </pre> |
| |
| <p> |
| The best way for your patch to get noticed is to submit it to the |
| <a href="http://groups.google.com/group/nodejs">mailing list</a> in form |
| of a <a href="http://gist.github.com/">gists</a> or file attachement. |
| </p> |
| |
| <p> |
| Feature patches should usually be discussed before putting in the work. |
| </p> |
| |
| <h2 id="benchmarks">Benchmarks</h2> |
| <p> |
| 2009.09.06 <a href="http://four.livejournal.com/1019177.html">narwhal, node, v8cgi, thin/eventmachine</a> |
| </p> |
| </div> |
| <script type="text/javascript"> |
| var gaJsHost = (("https:" == document.location.protocol) ? |
| "https://ssl." : "http://www."); |
| document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); |
| </script> |
| <script type="text/javascript"> |
| try { |
| var pageTracker = _gat._getTracker("UA-10874194-2"); |
| pageTracker._trackPageview(); |
| } catch(err) {}</script> |
| </body> |
| </html> |