doc/index.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3   <head>
   4     <style type="text/css">
   5     ul {
   6       padding: 0;
   7       margin: 0;
   8     }
   9     </style>
  10     <script type="text/javascript" src="sh_main.js"></script>
  11     <script type="text/javascript" src="sh_javascript.min.js"></script>
  12     <link type="text/css" rel="stylesheet" href="pipe.css" />
  13     <link type="text/css" rel="stylesheet" href="sh_vim-dark.css" />
  14     <meta http-equiv="content-type" content="text/html; charset=utf-8" />
  15     <title>node.js</title>
  16   </head>
  17   <body onload="sh_highlightDocument();">
  18     <div id="toc">
  19       <ol>
  20         <li><a href="#download">Download</a></li>
  21         <li><a href="#build">Build</a></li>
  22         <li><a href="#about">About</a></li>
  23         <li><a href="#demo">Demo</a></li>
  24         <li><a href="#community">Community</a></li>
  25         <li><a href="#contribute">Contribute</a></li>
  26         <li><a href="#benchmarks">Benchmarks</a></li>
  27         <li><a href="api.html">Documentation</a></li>
  28       </ol>
  29     </div>
  30     <div id="content">
  31
  32       <!-- <h1><a href="http://nodejs.org/">Node</a></h1> -->
  33       <img id="logo" src="logo.png" alt="node.js"/>
  34
  35       <p id="introduction">
  36         Evented I/O for
  37         <a href="http://code.google.com/p/v8/">V8 javascript</a>.
  38       </p>
  39
  40       <p>
  41         An example of a web server written with Node which responds with
  42         "Hello World" after waiting two seconds:
  43       </p>
  44
  45       <pre>
  46 var sys = require('sys'),
  47    http = require('http');
  48 http.createServer(function (req, res) {
  49   setTimeout(function () {
  50     res.sendHeader(200, {'Content-Type': 'text/plain'});
  51     res.sendBody('Hello World');
  52     res.finish();
  53   }, 2000);
  54 }).listen(8000);
  55 sys.puts('Server running at http://127.0.0.1:8000/');</pre>
  56 </pre>
  57
  58       <p>
  59         To run the server, put the code into a file
  60         <code>example.js</code> and execute it with the <code>node</code>
  61         program
  62       </p>
  63       <pre class="sh_none">
  64 % node example.js
  65 Server running at http://127.0.0.1:8000/</pre>
  66
  67       <p>
  68         Here is an example of a simple TCP server which listens on port 7000
  69         and echos whatever you send it:
  70       </p>
  71
  72       <pre>
  73 var tcp = require('tcp');
  74 var server = tcp.createServer(function (socket) {
  75   socket.setEncoding("utf8");
  76   socket.addListener("connect", function () {
  77     socket.write("hello\r\n");
  78   });
  79   socket.addListener("receive", function (data) {
  80     socket.write(data);
  81   });
  82   socket.addListener("eof", function () {
  83     socket.write("goodbye\r\n");
  84     socket.close();
  85   });
  86 });
  87 server.listen(7000, "localhost");</pre>
  88
  89       <p>
  90         See the <a href="api.html">API documentation</a> for more
  91         examples.
  92       </p>
  93
  94       <h2 id="download">Download</h2>
  95
  96       <p>
  97         <a href="http://github.com/ry/node/tree/master">git repo</a>
  98       </p>
  99       <p>
 100         2010.02.09
 101         <a
 102         href="http://s3.amazonaws.com/four.livejournal/20100209/node-v0.1.28.tar.gz">node-v0.1.28.tar.gz</a>
 103       </p>
 104
 105       <h2 id="build">Build</h2>
 106
 107       <p>
 108         Node eventually wants to support all POSIX operating systems
 109         (including Windows with MinGW) but at the moment it is only being
 110         tested on <b>Linux</b>, <b>Macintosh</b>, and <b>FreeBSD</b>. The
 111         build system requires Python 2.4 or better.  V8, on which Node is
 112         built, supports only IA-32 and ARM processors. V8 is included in the
 113         Node distribution. There are no other dependencies.
 114       </p>
 115
 116       <pre class="sh_none">
 117 ./configure
 118 make
 119 make install</pre>
 120
 121       <p>
 122         Then have a look at the <a href="api.html">API documentation</a>.
 123       </p>
 124
 125       <p>To run the tests</p>
 126
 127       <pre class="sh_none">make test</pre>
 128
 129       <h2 id="about">About</h2>
 130
 131       <p>
 132         Node's goal is to provide an easy way to build scalable network
 133         programs. In the above example, the two second delay does not
 134         prevent the server from handling new requests. Node tells the
 135         operating system (through <code>epoll</code>, <code>kqueue</code>,
 136         <code class="sh_none">/dev/poll</code>, or <code>select</code>)
 137         that it should be notified when the 2 seconds are up or if a new
 138         connection is made&mdash;then it goes to sleep. If someone new
 139         connects, then it executes the callback, if the timeout expires,
 140         it executes the inner callback. Each connection is only a small
 141         heap allocation.
 142       </p>
 143
 144       <p>
 145         This is in contrast to today's more common concurrency model where
 146         OS threads are employed. Thread-based networking
 147         <a href="http://www.sics.se/~joe/apachevsyaws.html">is</a>
 148         <a href="http://www.kegel.com/c10k.html">relatively</a>
 149         <a href="http://bulk.fefe.de/scalable-networking.pdf">inefficient</a>
 150         <!-- TODO needs links -->
 151         and very difficult to use.
 152
 153         Node will show much better memory efficiency under high-loads
 154         <!-- TODO benchmark -->
 155         than systems which allocate 2mb thread stacks for each connection.
 156
 157         Furthermore, users of Node are free from worries of dead-locking
 158         the process&mdash;there are no locks.  Almost no function in Node
 159         directly performs I/O, so the process never blocks. Because
 160         nothing blocks, less-than-expert programmers are able to develop
 161         fast systems.
 162       </p>
 163
 164       <p>
 165         Node is similar in design to and influenced by systems like Ruby's <a
 166         href="http://rubyeventmachine.com/">Event Machine</a> or Python's <a
 167         href="http://twistedmatrix.com/">Twisted</a>.  Node takes the event
 168         model a bit further&mdash;it presents the event loop as a language
 169         construct instead of as a library. In other systems there is always
 170         a blocking call to start the event-loop.  Typically one defines
 171         behavior through callbacks at the beginning of a script and at the
 172         end starts a server through a blocking call like
 173         <code>EventMachine::run()</code>. In Node there is no such
 174         start-the-event-loop call.  Node simply enters the event loop after
 175         executing the input script. Node exits the event loop when there are
 176         no more callbacks to perform.  This behavior is like browser
 177         javascript&mdash;the event loop is hidden from the user.
 178       </p>
 179
 180       <p>
 181         HTTP is a first class protocol in Node.  Node's HTTP library has
 182         grown out of the author's experiences developing and working with
 183         web servers. For example, streaming data through most web frameworks
 184         is impossible.  Node attempts to correct these problems in its HTTP
 185         <a href="http://github.com/ry/http-parser/tree/master">parser</a>
 186         and API. Coupled with Node's purely evented infrastructure, it makes
 187         a good foundation for web libraries or frameworks.
 188       </p>
 189
 190       <p>
 191         <i>
 192           But what about multiple-processor concurrency? Threads are
 193           necessary to scale programs to multi-core computers.
 194         </i>
 195         Processes are necessary to scale to multi-core computers, not
 196         memory-sharing threads. The fundamentals of scalable systems are
 197         fast networking and non-blocking design&mdash;the rest is message
 198         passing.  In future versions, Node will be able to fork new
 199         processes (using the <a
 200         href="http://www.whatwg.org/specs/web-workers/current-work/"> Web
 201         Workers API </a>), but this is something that fits well into the
 202         current design.
 203       </p>
 204
 205       <p>
 206         See also: <a href="http://s3.amazonaws.com/four.livejournal/20091117/jsconf.pdf">slides</a> from jsconf.
 207       </p>
 208
 209
 210       <h2 id="demo">Demo</h2>
 211       <p>
 212         A chat room demo is running at <a
 213           href="http://chat.nodejs.org">chat.nodejs.org</a>. The
 214         source code for the chat room is at <a
 215           href="http://github.com/ry/node_chat/tree/master">http://github.com/ry/node_chat</a>.
 216         The chat room is not stable and might occasionally be down.
 217       </p>
 218
 219       <h2 id="community">Community</h2>
 220       <p>
 221         For help and discussion subscribe to the mailing list at
 222         <a href="http://groups.google.com/group/nodejs">http://groups.google.com/group/nodejs</a>
 223         or send an email to <a href="mailto:nodejs+subscribe@googlegroups.com">nodejs+subscribe@googlegroups.com</a>.
 224       </p>
 225
 226       <p>
 227         For real-time discussion, check irc.freenode.net #node.js.
 228       </p>
 229
 230       <p>
 231         <a href="http://wiki.github.com/ry/node">Projects/libraries which are using/for Node.js</a>
 232       </p>
 233       <h2 id="contribute">Contribute</h2>
 234       <p>
 235         Patches are always welcome. The process is simple:
 236       </p>
 237
 238       <pre class="sh_none">
 239 git clone git://github.com/ry/node.git
 240 cd node
 241 # edit/compile/test
 242 git commit -m "Good description of what your patch does"
 243 git format-patch HEAD^
 244 </pre>
 245
 246       <p>
 247         The best way for your patch to get noticed is to submit it to the
 248        <a href="http://groups.google.com/group/nodejs">mailing list</a> in form
 249        of a <a href="http://gist.github.com/">gists</a> or file attachement.
 250       </p>
 251
 252       <p>
 253         Feature patches should usually be discussed before putting in the work.
 254       </p>
 255
 256       <h2 id="benchmarks">Benchmarks</h2>
 257       <p>
 258         2009.09.06 <a href="http://four.livejournal.com/1019177.html">narwhal, node, v8cgi, thin/eventmachine</a>
 259       </p>
 260     </div>
 261     <script type="text/javascript">
 262       var gaJsHost = (("https:" == document.location.protocol) ?
 263       "https://ssl." : "http://www.");
 264       document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
 265     </script>
 266     <script type="text/javascript">
 267       try {
 268         var pageTracker = _gat._getTracker("UA-10874194-2");
 269         pageTracker._trackPageview();
 270         } catch(err) {}</script>
 271   </body>
 272 </html>