mirror of https://github.com/lukechilds/node.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
302 lines
11 KiB
302 lines
11 KiB
<!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="changelog.html">ChangeLog</a></li>
|
|
<li><a href="#build">Build</a></li>
|
|
<li><a href="#about">About</a></li>
|
|
<li><a href="#links">Links</a></li>
|
|
<li><a href="#contributing">Contributing</a></li>
|
|
<li><a href="http://nodejs.org/docs/v0.3.1/api">v0.3.1 docs</a></li>
|
|
<li><a href="http://nodejs.org/docs/v0.2.5/api.html">v0.2.5 docs</a></li>
|
|
</ol>
|
|
</div>
|
|
<div id="content">
|
|
|
|
<!-- <h1><a href="http://nodejs.org/">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 in Node which responds with
|
|
"Hello World" for every request.
|
|
</p>
|
|
|
|
<pre>
|
|
var http = require('http');
|
|
http.createServer(function (req, res) {
|
|
res.writeHead(200, {'Content-Type': 'text/plain'});
|
|
res.end('Hello World\n');
|
|
}).listen(8124, "127.0.0.1");
|
|
console.log('Server running at http://127.0.0.1:8124/');
|
|
</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:8124/</pre>
|
|
|
|
<p>
|
|
Here is an example of a simple TCP server which listens on port 8124
|
|
and echoes whatever you send it:
|
|
</p>
|
|
|
|
<pre>
|
|
var net = require('net');
|
|
net.createServer(function (socket) {
|
|
socket.write("Echo server\r\n");
|
|
socket.on("data", function (data) {
|
|
socket.write(data);
|
|
});
|
|
}).listen(8124, "127.0.0.1");
|
|
</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>
|
|
Stable: 2010.11.16
|
|
<a href="http://nodejs.org/dist/node-v0.2.5.tar.gz">node-v0.2.5.tar.gz</a>
|
|
(<a href="http://nodejs.org/docs/v0.2.5/api.html">Documentation</a>)
|
|
</p>
|
|
|
|
<p>
|
|
Unstable: 2010.11.16
|
|
<a href="http://nodejs.org/dist/node-v0.3.1.tar.gz">node-v0.3.1.tar.gz</a>
|
|
(<a href="http://nodejs.org/docs/v0.3.1/api/index.html">Documentation</a>)
|
|
</p>
|
|
|
|
<p>Historical: <a href="http://nodejs.org/dist">versions</a>, <a href="http://nodejs.org/docs">docs</a></p>
|
|
|
|
<h2 id="build">Build</h2>
|
|
|
|
<p>
|
|
Node is tested on <b>Linux</b>, <b>Macintosh</b>, and
|
|
<b>Solaris</b>. It also runs on <b>Windows/Cygwin</b>,
|
|
<b>FreeBSD</b>, and <b>OpenBSD</b>. The build system requires Python
|
|
2.4 or better. V8, on which Node is built, supports only IA-32,
|
|
x64, and ARM processors. V8 is included in the Node distribution.
|
|
To use TLS, OpenSSL is required. 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 "hello world" web server example above, many
|
|
client connections can be handled concurrently. 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 a new connection is made, and
|
|
then it goes to sleep. If someone new connects, then it executes
|
|
the 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 is relatively
|
|
inefficient and very difficult to use. See:
|
|
<a href="http://www.kegel.com/c10k.html">this</a> and
|
|
<a href="http://bulk.fefe.de/scalable-networking.pdf">this.</a>
|
|
|
|
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? Aren't threads
|
|
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>) which fits well into the current design.
|
|
</p>
|
|
|
|
<p>
|
|
See also:
|
|
<ul>
|
|
<li><a href="http://s3.amazonaws.com/four.livejournal/20091117/jsconf.pdf">slides</a> from JSConf 2009</li>
|
|
<li><a href="http://nodejs.org/jsconf2010.pdf">slides</a> from JSConf 2010</li>
|
|
<li><a href="http://www.yuiblog.com/blog/2010/05/20/video-dahl/">video</a> from a talk at Yahoo in May 2010</li>
|
|
</ul>
|
|
</p>
|
|
|
|
|
|
<h2 id="links">Links</h2>
|
|
|
|
<ul>
|
|
|
|
<li>
|
|
A chat room <b>demo</b> 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.
|
|
</li>
|
|
|
|
<li>
|
|
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>.
|
|
For real-time discussion, check irc.freenode.net <code>#node.js</code>.
|
|
</li>
|
|
|
|
<li>
|
|
<a href="http://nodejs.debuggable.com/">IRC logs</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="http://wiki.github.com/ry/node">Projects/libraries which are using/for Node.js</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="http://buildbot.nodejs.org:8010/">Node.js buildbot</a>
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
<h2 id="contributing">Contributing</h2>
|
|
<p>
|
|
Patches are welcome. The process is simple:
|
|
</p>
|
|
|
|
<pre class="sh_none">
|
|
git clone git://github.com/ry/node.git
|
|
cd node
|
|
(make your changes)
|
|
./configure --debug
|
|
make test-all # Check your patch with both debug and release builds
|
|
git commit -m "Good description of what your patch does"
|
|
git format-patch HEAD^
|
|
</pre>
|
|
|
|
<p>
|
|
Be sure the your patch includes your full name and your valid email
|
|
address. Git can be configured to do this like so:
|
|
<pre class="sh_none">
|
|
git config --global user.email "ry@tinyclouds.org"
|
|
git config --global user.name "Ryan Dahl"
|
|
</pre>
|
|
</p>
|
|
|
|
<p>
|
|
Before your code your code can be accepted you have to sign the
|
|
<a href="cla.html">contributor license agreement</a>.
|
|
</p>
|
|
|
|
<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>
|
|
You should ask the mailing list if a new feature is wanted before
|
|
working on a patch.
|
|
</p>
|
|
|
|
</div>
|
|
|
|
|
|
<div style="padding-top: 10em; font-size: 8pt">
|
|
<a href="http://joyent.com/"><img style="border: 0; padding: 0;" src="sponsored.png"/></a>
|
|
<br/>
|
|
<br/>
|
|
|
|
Copyright 2010 Joyent, Inc
|
|
</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>
|
|
|