Made a few other little corrections too.
website: website/api.html website/index.html
website/api.html: website/api.txt
- asciidoc -a toc -o website/api.html website/api.txt
+ asciidoc --unsafe \\
+ -a theme=pipe \\
+ -a toc \\
+ -a linkcss \\
+ -o website/api.html website/api.txt
+
+# -a stylesdir=website/ \\
+# -a scriptsdir=website/ \\
website-upload: website
scp website/* linode:~/tinyclouds/node/
Version, 0.1.6, 2009.08.22
-== NAME
+== Name
node - purely event-based I/O for V8 javascript
-== SYNOPSIS
+== Synopsis
An example of a web server written with Node which responds with "Hello
World" after waiting two seconds:
----------------------------------------
-== DESCRIPTION
-
-Node provides an easy way to build scalable network programs. In the above
-example, the 2 second delay does not prevent the server from handling new
-requests. Node tells the operating system (through +epoll+, +kqueue+,
-+/dev/poll+, or +select+) 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.
-
-This is in contrast to today's more common model where OS threads are employed
-for concurrency. Thread-based networking
-http://www.sics.se/~joe/apachevsyaws.html[is]
-http://www.kegel.com/c10k.html[relatively]
-http://bulk.fefe.de/scalable-networking.pdf[inefficient]
-and very difficult to use. Node will show much better memory efficiency
-under high-loads 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. In fact, no function in Node
-directly performs I/O. Because nothing blocks, less-than-expert programmers
-are able to develop fast systems.
-
-Node is similar in design to systems like Ruby's
-http://rubyeventmachine.com/[Event Machine]
-or Python's http://twistedmatrix.com/[Twisted].
-Node takes the event model a bit further. For example, 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 call like +EventMachine::run()+. In Node it works differently.
-By default Node enters the event loop after executing the input script. Node
-exits the event loop when there are no more callbacks to perform. Like in
-traditional browser javascript, the event loop is hidden from the user.
-
-Node's HTTP API has grown out of my difficulties developing and working with
-web servers. For example, streaming data through most web frameworks is
-impossible. Or the oft-made false assumption that all message headers have
-unique fields. Node attempts to correct these and other problems in its API.
-Coupled with Node's purely evented infrastructure, it will make a more
-comprehensive foundation for future web libraries/frameworks.
-
-_But what about multiple-processor concurrency? 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 (probably using the
-http://www.whatwg.org/specs/web-workers/current-work/[Web Workers API]),
-but this is something that fits well into the current design.
-
-
== API
</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="style.css" />
+ <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>
<h1><a href="http://tinyclouds.org/node">Node</a></h1>
<p id="introduction">
- Purely event-based I/O for
+ Mostly event-based I/O for
<a href="http://code.google.com/p/v8/">V8 javascript</a>.
</p>
<p>
Node's goal is to provide an easy way to build scalable network
- programs. In the above example, the 2 second delay does not
+ 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>)
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. No function in Node
+ 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 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. For example, 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 call like
- <code>EventMachine::run()</code>. In Node it works differently.
- By default Node enters the event loop after executing the input
- script. Node exits the event loop when there are no more callbacks
- to perform. Like in traditional browser javascript, the event loop
- is hidden from the user.
+ Node is similar in design to 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. For example, 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 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>
- Node's HTTP API has grown out of my difficulties developing and
- working with web servers. For example, streaming data through
- most web frameworks is impossible. Or the oft-made false
- assumption that all message headers have unique fields. Node
- attempts to correct these and other problems in its API. Coupled
- with Node's purely evented infrastructure, it will make a more
- comprehensive foundation for future web libraries/frameworks.
+ Node's HTTP library has grown out of my difficulties 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 API. Coupled with Node's purely evented
+ infrastructure, it makes a good foundation for web libraries or
+ frameworks.
</p>
<p>
But what about multiple-processor concurrency? Threads are
necessary to scale programs to multi-core computers.
</i>
- The name <i>Node</i> should give some hint at how it is envisioned
+ The name <i>Node</i> gives 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
font-size: 16pt;
line-height: 150%;
font-family: times, Times New Roman, times-roman, georgia, serif;
-}
-#content {
max-width: 30em;
margin: 0 0 5em 8em;
}
font-size: 14pt;
line-height: 120%;
}
+#toctitle {
+ display: none;
+}
#toc ol {
list-style: none;
+}
+#toc ol, .toclevel2 {
margin: 0;
padding: 0;
padding-left: 1em;
+++ /dev/null
-/* Copyright (C) 2007, 2008 gnombat@users.sourceforge.net */
-/* License: http://shjs.sourceforge.net/doc/gplv3.html */
-
-if(!this.sh_languages){this.sh_languages={}}var sh_requests={};function sh_isEmailAddress(a){if(/^mailto:/.test(a)){return false}return a.indexOf("@")!==-1}function sh_setHref(b,c,d){var a=d.substring(b[c-2].pos,b[c-1].pos);if(a.length>=2&&a.charAt(0)==="<"&&a.charAt(a.length-1)===">"){a=a.substr(1,a.length-2)}if(sh_isEmailAddress(a)){a="mailto:"+a}b[c-2].node.href=a}function sh_konquerorExec(b){var a=[""];a.index=b.length;a.input=b;return a}function sh_highlightString(B,o){if(/Konqueror/.test(navigator.userAgent)){if(!o.konquered){for(var F=0;F<o.length;F++){for(var H=0;H<o[F].length;H++){var G=o[F][H][0];if(G.source==="$"){G.exec=sh_konquerorExec}}}o.konquered=true}}var N=document.createElement("a");var q=document.createElement("span");var A=[];var j=0;var n=[];var C=0;var k=null;var x=function(i,a){var p=i.length;if(p===0){return}if(!a){var Q=n.length;if(Q!==0){var r=n[Q-1];if(!r[3]){a=r[1]}}}if(k!==a){if(k){A[j++]={pos:C};if(k==="sh_url"){sh_setHref(A,j,B)}}if(a){var P;if(a==="sh_url"){P=N.cloneNode(false)}else{P=q.cloneNode(false)}P.className=a;A[j++]={node:P,pos:C}}}C+=p;k=a};var t=/\r\n|\r|\n/g;t.lastIndex=0;var d=B.length;while(C<d){var v=C;var l;var w;var h=t.exec(B);if(h===null){l=d;w=d}else{l=h.index;w=t.lastIndex}var g=B.substring(v,l);var M=[];for(;;){var I=C-v;var D;var y=n.length;if(y===0){D=0}else{D=n[y-1][2]}var O=o[D];var z=O.length;var m=M[D];if(!m){m=M[D]=[]}var E=null;var u=-1;for(var K=0;K<z;K++){var f;if(K<m.length&&(m[K]===null||I<=m[K].index)){f=m[K]}else{var c=O[K][0];c.lastIndex=I;f=c.exec(g);m[K]=f}if(f!==null&&(E===null||f.index<E.index)){E=f;u=K;if(f.index===I){break}}}if(E===null){x(g.substring(I),null);break}else{if(E.index>I){x(g.substring(I,E.index),null)}var e=O[u];var J=e[1];var b;if(J instanceof Array){for(var L=0;L<J.length;L++){b=E[L+1];x(b,J[L])}}else{b=E[0];x(b,J)}switch(e[2]){case -1:break;case -2:n.pop();break;case -3:n.length=0;break;default:n.push(e);break}}}if(k){A[j++]={pos:C};if(k==="sh_url"){sh_setHref(A,j,B)}k=null}C=w}return A}function sh_getClasses(d){var a=[];var b=d.className;if(b&&b.length>0){var e=b.split(" ");for(var c=0;c<e.length;c++){if(e[c].length>0){a.push(e[c])}}}return a}function sh_addClass(c,a){var d=sh_getClasses(c);for(var b=0;b<d.length;b++){if(a.toLowerCase()===d[b].toLowerCase()){return}}d.push(a);c.className=d.join(" ")}function sh_extractTagsFromNodeList(c,a){var f=c.length;for(var d=0;d<f;d++){var e=c.item(d);switch(e.nodeType){case 1:if(e.nodeName.toLowerCase()==="br"){var b;if(/MSIE/.test(navigator.userAgent)){b="\r"}else{b="\n"}a.text.push(b);a.pos++}else{a.tags.push({node:e.cloneNode(false),pos:a.pos});sh_extractTagsFromNodeList(e.childNodes,a);a.tags.push({pos:a.pos})}break;case 3:case 4:a.text.push(e.data);a.pos+=e.length;break}}}function sh_extractTags(c,b){var a={};a.text=[];a.tags=b;a.pos=0;sh_extractTagsFromNodeList(c.childNodes,a);return a.text.join("")}function sh_mergeTags(d,f){var a=d.length;if(a===0){return f}var c=f.length;if(c===0){return d}var i=[];var e=0;var b=0;while(e<a&&b<c){var h=d[e];var g=f[b];if(h.pos<=g.pos){i.push(h);e++}else{i.push(g);if(f[b+1].pos<=h.pos){b++;i.push(f[b]);b++}else{i.push({pos:h.pos});f[b]={node:g.node.cloneNode(false),pos:h.pos}}}}while(e<a){i.push(d[e]);e++}while(b<c){i.push(f[b]);b++}return i}function sh_insertTags(k,h){var g=document;var l=document.createDocumentFragment();var e=0;var d=k.length;var b=0;var j=h.length;var c=l;while(b<j||e<d){var i;var a;if(e<d){i=k[e];a=i.pos}else{a=j}if(a<=b){if(i.node){var f=i.node;c.appendChild(f);c=f}else{c=c.parentNode}e++}else{c.appendChild(g.createTextNode(h.substring(b,a)));b=a}}return l}function sh_highlightElement(d,g){sh_addClass(d,"sh_sourceCode");var c=[];var e=sh_extractTags(d,c);var f=sh_highlightString(e,g);var b=sh_mergeTags(c,f);var a=sh_insertTags(b,e);while(d.hasChildNodes()){d.removeChild(d.firstChild)}d.appendChild(a)}function sh_getXMLHttpRequest(){if(window.ActiveXObject){return new ActiveXObject("Msxml2.XMLHTTP")}else{if(window.XMLHttpRequest){return new XMLHttpRequest()}}throw"No XMLHttpRequest implementation available"}function sh_load(language,element,prefix,suffix){if(language in sh_requests){sh_requests[language].push(element);return}sh_requests[language]=[element];var request=sh_getXMLHttpRequest();var url=prefix+"sh_"+language+suffix;request.open("GET",url,true);request.onreadystatechange=function(){if(request.readyState===4){try{if(!request.status||request.status===200){eval(request.responseText);var elements=sh_requests[language];for(var i=0;i<elements.length;i++){sh_highlightElement(elements[i],sh_languages[language])}}else{throw"HTTP error: status "+request.status}}finally{request=null}}};request.send(null)}function sh_highlightDocument(g,k){var b=document.getElementsByTagName("pre");for(var e=0;e<b.length;e++){var f=b.item(e);var a=sh_getClasses(f);for(var c=0;c<a.length;c++){var h=a[c].toLowerCase();if(h==="sh_sourcecode"){continue}if(h.substr(0,3)==="sh_"){var d=h.substring(3);if(d in sh_languages){sh_highlightElement(f,sh_languages[d])}else{if(typeof(g)==="string"&&typeof(k)==="string"){sh_load(d,f,g,k)}else{throw'Found <pre> element with class="'+h+'", but no such language exists'}}break}}}};
\ No newline at end of file
--- /dev/null
+/* Author: Mihai Bazon, September 2002
+ * http://students.infoiasi.ro/~mishoo
+ *
+ * Table Of Content generator
+ * Version: 0.4
+ *
+ * Feel free to use this script under the terms of the GNU General Public
+ * License, as long as you do not remove or alter this notice.
+ */
+
+ /* modified by Troy D. Hanson, September 2006. License: GPL */
+ /* modified by Stuart Rackham, October 2006. License: GPL */
+
+function getText(el) {
+ var text = "";
+ for (var i = el.firstChild; i != null; i = i.nextSibling) {
+ if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
+ text += i.data;
+ else if (i.firstChild != null)
+ text += getText(i);
+ }
+ return text;
+}
+
+function TocEntry(el, text, toclevel) {
+ this.element = el;
+ this.text = text;
+ this.toclevel = toclevel;
+}
+
+function tocEntries(el, toclevels) {
+ var result = new Array;
+ var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
+ // Function that scans the DOM tree for header elements (the DOM2
+ // nodeIterator API would be a better technique but not supported by all
+ // browsers).
+ var iterate = function (el) {
+ for (var i = el.firstChild; i != null; i = i.nextSibling) {
+ if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
+ var mo = re.exec(i.tagName)
+ if (mo)
+ result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
+ iterate(i);
+ }
+ }
+ }
+ iterate(el);
+ return result;
+}
+
+// This function does the work. toclevels = 1..4.
+function generateToc(toclevels) {
+ var toc = document.getElementById("toc");
+ var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels);
+ for (var i = 0; i < entries.length; ++i) {
+ var entry = entries[i];
+ if (entry.element.id == "")
+ entry.element.id = "toc" + i;
+ var a = document.createElement("a");
+ a.href = "#" + entry.element.id;
+ a.appendChild(document.createTextNode(entry.text));
+ var div = document.createElement("div");
+ div.appendChild(a);
+ div.className = "toclevel" + entry.toclevel;
+ toc.appendChild(div);
+ }
+ if (entries.length == 0)
+ document.getElementById("header").removeChild(toc);
+}