2009-06-05 12:23:51 +02:00
|
|
|
<!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;
|
|
|
|
|
}
|
2009-08-26 22:03:19 +02:00
|
|
|
</style>
|
2009-06-05 12:23:51 +02:00
|
|
|
<script type="text/javascript" src="sh_main.js"></script>
|
|
|
|
|
<script type="text/javascript" src="sh_javascript.min.js"></script>
|
2009-08-25 16:23:01 +02:00
|
|
|
<link type="text/css" rel="stylesheet" href="pipe.css" />
|
2009-06-05 12:23:51 +02:00
|
|
|
<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>
|
2010-02-21 07:30:56 +01:00
|
|
|
<li><a href="changelog.html">ChangeLog</a></li>
|
2009-06-05 12:23:51 +02:00
|
|
|
<li><a href="#build">Build</a></li>
|
2009-10-16 13:46:16 +02:00
|
|
|
<li><a href="#about">About</a></li>
|
2010-03-06 00:59:31 +01:00
|
|
|
<li><a href="#links">Links</a></li>
|
|
|
|
|
<li><a href="#contributing">Contributing</a></li>
|
2009-06-05 12:23:51 +02:00
|
|
|
<li><a href="api.html">Documentation</a></li>
|
|
|
|
|
</ol>
|
|
|
|
|
</div>
|
|
|
|
|
<div id="content">
|
|
|
|
|
|
2010-02-12 09:08:26 +01:00
|
|
|
<!-- <h1><a href="http://nodejs.org/">Node</a></h1> -->
|
2009-11-02 12:28:08 +01:00
|
|
|
<img id="logo" src="logo.png" alt="node.js"/>
|
2009-06-05 12:23:51 +02:00
|
|
|
|
|
|
|
|
<p id="introduction">
|
2009-09-03 17:21:08 +02:00
|
|
|
Evented I/O for
|
2009-06-05 12:23:51 +02:00
|
|
|
<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>
|
2009-08-26 22:03:19 +02:00
|
|
|
|
2009-06-05 12:23:51 +02:00
|
|
|
<pre>
|
2009-10-31 19:02:30 +01:00
|
|
|
var sys = require('sys'),
|
|
|
|
|
http = require('http');
|
2009-10-09 14:18:10 +02:00
|
|
|
http.createServer(function (req, res) {
|
2009-05-13 17:46:00 +02:00
|
|
|
setTimeout(function () {
|
2010-02-25 21:54:48 +01:00
|
|
|
res.writeHead(200, {'Content-Type': 'text/plain'});
|
2010-02-17 07:16:29 +01:00
|
|
|
res.write('Hello World');
|
2010-02-17 20:10:10 +01:00
|
|
|
res.close();
|
2009-05-13 17:46:00 +02:00
|
|
|
}, 2000);
|
2009-09-28 12:36:36 +02:00
|
|
|
}).listen(8000);
|
2009-10-31 19:02:30 +01:00
|
|
|
sys.puts('Server running at http://127.0.0.1:8000/');</pre>
|
2009-09-28 12:06:30 +02:00
|
|
|
</pre>
|
2009-08-26 22:03:19 +02:00
|
|
|
|
2009-06-05 12:23:51 +02:00
|
|
|
<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">
|
2009-10-16 13:46:16 +02:00
|
|
|
% node example.js
|
2009-06-05 12:23:51 +02:00
|
|
|
Server running at http://127.0.0.1:8000/</pre>
|
2009-08-26 22:03:19 +02:00
|
|
|
|
2009-10-16 13:46:16 +02:00
|
|
|
<p>
|
|
|
|
|
Here is an example of a simple TCP server which listens on port 7000
|
|
|
|
|
and echos whatever you send it:
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<pre>
|
2009-10-31 20:26:03 +01:00
|
|
|
var tcp = require('tcp');
|
2009-10-16 13:46:16 +02:00
|
|
|
var server = tcp.createServer(function (socket) {
|
|
|
|
|
socket.setEncoding("utf8");
|
|
|
|
|
socket.addListener("connect", function () {
|
2010-02-16 22:15:30 +01:00
|
|
|
socket.write("hello\r\n");
|
2009-10-16 13:46:16 +02:00
|
|
|
});
|
2010-02-18 02:07:08 +01:00
|
|
|
socket.addListener("data", function (data) {
|
2010-02-16 22:15:30 +01:00
|
|
|
socket.write(data);
|
2009-10-16 13:46:16 +02:00
|
|
|
});
|
2010-02-18 02:07:08 +01:00
|
|
|
socket.addListener("end", function () {
|
2010-02-16 22:15:30 +01:00
|
|
|
socket.write("goodbye\r\n");
|
2009-10-16 13:46:16 +02:00
|
|
|
socket.close();
|
|
|
|
|
});
|
|
|
|
|
});
|
|
|
|
|
server.listen(7000, "localhost");</pre>
|
|
|
|
|
|
2009-06-05 12:23:51 +02:00
|
|
|
<p>
|
|
|
|
|
See the <a href="api.html">API documentation</a> for more
|
|
|
|
|
examples.
|
|
|
|
|
</p>
|
|
|
|
|
|
2009-10-16 13:46:16 +02:00
|
|
|
<h2 id="download">Download</h2>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
<a href="http://github.com/ry/node/tree/master">git repo</a>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
2010-03-06 02:55:00 +01:00
|
|
|
2010.03.05
|
|
|
|
|
<a href="http://nodejs.org/dist/node-v0.1.31.tar.gz">node-v0.1.31.tar.gz</a>
|
2009-10-16 13:46:16 +02:00
|
|
|
</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
|
2010-02-17 22:39:03 +01:00
|
|
|
Node distribution. To use TLS, GnuTLS and libgpg-error are required.
|
|
|
|
|
There are no other dependencies.
|
2009-10-16 13:46:16 +02:00
|
|
|
</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>
|
|
|
|
|
|
2009-06-05 12:23:51 +02:00
|
|
|
<h2 id="about">About</h2>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Node's goal is to provide an easy way to build scalable network
|
2009-08-25 16:23:01 +02:00
|
|
|
programs. In the above example, the two second delay does not
|
2009-06-05 12:23:51 +02:00
|
|
|
prevent the server from handling new requests. Node tells the
|
|
|
|
|
operating system (through <code>epoll</code>, <code>kqueue</code>,
|
2009-08-26 22:03:19 +02:00
|
|
|
<code class="sh_none">/dev/poll</code>, or <code>select</code>)
|
2009-06-05 12:23:51 +02:00
|
|
|
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>
|
2009-08-26 22:03:19 +02:00
|
|
|
|
2009-06-05 12:23:51 +02:00
|
|
|
<p>
|
2009-09-03 17:21:08 +02:00
|
|
|
This is in contrast to today's more common concurrency model where
|
|
|
|
|
OS threads are employed. Thread-based networking
|
2009-06-05 12:23:51 +02:00
|
|
|
<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 -->
|
2009-08-26 22:03:19 +02:00
|
|
|
and very difficult to use.
|
2009-06-05 12:23:51 +02:00
|
|
|
|
2009-08-26 22:03:19 +02:00
|
|
|
Node will show much better memory efficiency under high-loads
|
2009-06-05 12:23:51 +02:00
|
|
|
<!-- TODO benchmark -->
|
|
|
|
|
than systems which allocate 2mb thread stacks for each connection.
|
|
|
|
|
|
|
|
|
|
Furthermore, users of Node are free from worries of dead-locking
|
2009-08-25 16:23:01 +02:00
|
|
|
the process—there are no locks. Almost no function in Node
|
2009-06-05 12:23:51 +02:00
|
|
|
directly performs I/O, so the process never blocks. Because
|
|
|
|
|
nothing blocks, less-than-expert programmers are able to develop
|
|
|
|
|
fast systems.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
2009-09-14 22:44:25 +02:00
|
|
|
Node is similar in design to and influenced by systems like Ruby's <a
|
2009-08-25 16:23:01 +02:00
|
|
|
href="http://rubyeventmachine.com/">Event Machine</a> or Python's <a
|
|
|
|
|
href="http://twistedmatrix.com/">Twisted</a>. Node takes the event
|
2009-09-03 17:21:08 +02:00
|
|
|
model a bit further—it presents the event loop as a language
|
|
|
|
|
construct instead of as a library. In other systems there is always
|
2009-08-25 16:23:01 +02:00
|
|
|
a blocking call to start the event-loop. Typically one defines
|
|
|
|
|
behavior through callbacks at the beginning of a script and at the
|
2009-09-03 17:21:08 +02:00
|
|
|
end starts a server through a blocking call like
|
2009-08-25 16:23:01 +02:00
|
|
|
<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.
|
2009-06-05 12:23:51 +02:00
|
|
|
</p>
|
2009-08-26 22:03:19 +02:00
|
|
|
|
2009-06-05 12:23:51 +02:00
|
|
|
<p>
|
2009-09-03 17:21:08 +02:00
|
|
|
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.
|
2009-06-05 12:23:51 +02:00
|
|
|
</p>
|
2009-08-26 22:03:19 +02:00
|
|
|
|
2009-06-05 12:23:51 +02:00
|
|
|
<p>
|
|
|
|
|
<i>
|
|
|
|
|
But what about multiple-processor concurrency? Threads are
|
|
|
|
|
necessary to scale programs to multi-core computers.
|
|
|
|
|
</i>
|
2009-09-03 17:21:08 +02:00
|
|
|
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.
|
2009-06-05 12:23:51 +02:00
|
|
|
</p>
|
|
|
|
|
|
2009-11-17 14:22:23 +01:00
|
|
|
<p>
|
|
|
|
|
See also: <a href="http://s3.amazonaws.com/four.livejournal/20091117/jsconf.pdf">slides</a> from jsconf.
|
|
|
|
|
</p>
|
|
|
|
|
|
2009-08-26 22:03:19 +02:00
|
|
|
|
2010-03-06 00:59:31 +01:00
|
|
|
<h2 id="links">Links</h2>
|
|
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
A chat room <b>demo</b> is running at <a
|
2009-10-02 16:24:49 +02:00
|
|
|
href="http://chat.nodejs.org">chat.nodejs.org</a>. The
|
2009-06-27 18:26:25 +02:00
|
|
|
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.
|
2010-03-06 00:59:31 +01:00
|
|
|
</li>
|
2009-05-14 17:36:25 +02:00
|
|
|
|
2010-03-06 00:59:31 +01:00
|
|
|
<li>
|
|
|
|
|
For help and discussion, subscribe to the mailing list at
|
2009-06-05 12:23:51 +02:00
|
|
|
<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>.
|
2010-03-06 00:59:31 +01:00
|
|
|
For real-time discussion, check irc.freenode.net <code>#node.js</code>.
|
|
|
|
|
</li>
|
2009-06-27 18:26:25 +02:00
|
|
|
|
2010-03-06 00:59:31 +01:00
|
|
|
<li>
|
|
|
|
|
<a href="http://nodejs.debuggable.com/">IRC logs</a>
|
|
|
|
|
</li>
|
2009-09-07 12:54:08 +02:00
|
|
|
|
2010-03-06 00:59:31 +01:00
|
|
|
<li>
|
2009-09-24 13:44:25 +02:00
|
|
|
<a href="http://wiki.github.com/ry/node">Projects/libraries which are using/for Node.js</a>
|
2010-03-06 00:59:31 +01:00
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
<a href="http://buildbot.nodejs.org:8010/">Node.js buildbot</a>
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h2 id="contributing">Contributing</h2>
|
2009-10-13 19:45:13 +02:00
|
|
|
<p>
|
2010-03-06 00:59:31 +01:00
|
|
|
Patches are welcome. The process is simple:
|
2009-10-13 19:45:13 +02:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<pre class="sh_none">
|
|
|
|
|
git clone git://github.com/ry/node.git
|
|
|
|
|
cd node
|
2010-03-01 18:11:04 +01:00
|
|
|
(make your changes)
|
|
|
|
|
./configure --debug
|
|
|
|
|
make test-all # Check your patch with both debug and release builds
|
2009-10-13 19:45:13 +02:00
|
|
|
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>
|
2010-03-06 00:59:31 +01:00
|
|
|
You should ask the mailing list if a new feature is wanted before
|
|
|
|
|
working on a patch.
|
2009-10-13 19:45:13 +02:00
|
|
|
</p>
|
2009-09-24 13:44:25 +02:00
|
|
|
|
2009-06-05 12:23:51 +02:00
|
|
|
</div>
|
2009-10-16 13:46:16 +02:00
|
|
|
<script type="text/javascript">
|
|
|
|
|
var gaJsHost = (("https:" == document.location.protocol) ?
|
|
|
|
|
"https://ssl." : "http://www.");
|
2009-11-04 00:18:05 +01:00
|
|
|
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
|
2009-10-16 13:46:16 +02:00
|
|
|
</script>
|
|
|
|
|
<script type="text/javascript">
|
|
|
|
|
try {
|
|
|
|
|
var pageTracker = _gat._getTracker("UA-10874194-2");
|
|
|
|
|
pageTracker._trackPageview();
|
|
|
|
|
} catch(err) {}</script>
|
2009-06-05 12:23:51 +02:00
|
|
|
</body>
|
2009-05-13 17:46:00 +02:00
|
|
|
</html>
|
