зеркало из https://github.com/mozilla/gecko-dev.git
Bug 423867 - Migrate js/src/README.html to developer.mozilla.org (r=brendan)
This commit is contained in:
Родитель
25f72423a4
Коммит
a663802904
|
@ -38,494 +38,17 @@
|
||||||
<html>
|
<html>
|
||||||
<head>
|
<head>
|
||||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||||
<meta name="GENERATOR" content="Mozilla/4.5 [en] (WinNT; I) [Netscape]">
|
<meta http-equiv="Refresh"
|
||||||
<title>JavaScript Reference Implementation (JSRef) README</title>
|
content="0;URL=http://developer.mozilla.org/en/docs/SpiderMonkey">
|
||||||
|
<title>SpiderMonkey README</title>
|
||||||
</head>
|
</head>
|
||||||
<body>
|
<body>
|
||||||
|
|
||||||
<h2>
|
<h1>SpiderMonkey README</h1>
|
||||||
Table of Contents</h2>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<a href="#Introduction">Introduction</a></li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
<a href="#Build">Build instructions</a></li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
<a href="#Debugging">Debugging notes</a></li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
<a href="#Conventions">Naming and coding conventions</a></li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
<a href="#JSAPI">Using the JS API</a></li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
<a href="#Design">Design walk-through</a></li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
<a href="#Resources">Additional Resources (links, API docs, and newsgroups)</a></li>
|
|
||||||
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<h2>
|
|
||||||
<a NAME="Introduction"></a>Introduction</h2>
|
|
||||||
This is the README file for the <span CLASS=LXRSHORTDESC>JavaScript
|
|
||||||
Reference (JSRef, now better known as SpiderMonkey) implementation.</span>
|
|
||||||
It consists of build instructions, source code conventions, a design
|
|
||||||
walk-through, and a brief file-by-file description of the source.
|
|
||||||
<p><span CLASS=LXRLONGDESC>JSRef builds a library or DLL containing the
|
|
||||||
JavaScript runtime (compiler, interpreter, decompiler, garbage collector,
|
|
||||||
atom manager, standard classes). It then compiles a small "shell" program
|
|
||||||
and links that with the library to make an interpreter that can be used
|
|
||||||
interactively and with test .js files to run scripts. The code has
|
|
||||||
no dependencies on the rest of the Mozilla codebase.</span>
|
|
||||||
<p><i>Quick start tip</i>: skip to "Using the JS API" below, build the
|
|
||||||
js shell, and play with the object named "it" (start by setting 'it.noisy
|
|
||||||
= true').
|
|
||||||
|
|
||||||
<h2>
|
|
||||||
<a NAME="Build"></a>Build instructions</h2>
|
|
||||||
|
|
||||||
<p>To build the standalone JavaScript engine, see the
|
|
||||||
<a href="http://developer.mozilla.org/en/docs/SpiderMonkey_Build_Documentation">SpiderMonkey
|
|
||||||
build documentation</a> page.</p>
|
|
||||||
|
|
||||||
<p>To build within the browser, use the
|
|
||||||
<a href="http://developer.mozilla.org/en/docs/Build_Documentation">Mozilla
|
|
||||||
build documentation</a> instead.</p>
|
|
||||||
|
|
||||||
<h2>
|
|
||||||
<a NAME="Debugging"></a>Debugging notes</h2>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
To turn on GC instrumentation, define <tt>JS_GCMETER</tt>.</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
To dump the JS heap use the JS_DumpHeap API, available in DEBUG
|
|
||||||
builds. For an example of how to call it, see the DumpHeap function in
|
|
||||||
js.cpp.</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
To turn on the arena package's instrumentation, define <tt>JS_ARENAMETER</tt>.</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
To turn on the hash table package's metering, define <tt>JS_HASHMETER</tt>.</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<h2>
|
|
||||||
<a NAME="Conventions"></a>Naming and coding conventions</h2>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Public function names begin with <tt>JS_</tt> followed by capitalized "intercaps",
|
|
||||||
e.g. <tt>JS_NewObject</tt>.</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
Extern but library-private function names use a <tt>js_</tt> prefix and
|
|
||||||
mixed case, e.g. <tt>js_SearchScope</tt>.</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
Most static function names have unprefixed, mixed-case names: <tt>GetChar</tt>.</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
But static native methods of JS objects have lowercase, underscore-separated
|
|
||||||
or intercaps names, e.g., <tt>str_indexOf</tt>.</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
And library-private and static data use underscores, not intercaps (but
|
|
||||||
library-private data do use a <tt>js_</tt> prefix).</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
Scalar type names are lowercase and js-prefixed: <tt>jsdouble</tt>.</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
Aggregate type names are JS-prefixed and mixed-case: <tt>JSObject.</tt></li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
Macros are generally <tt>ALL_CAPS </tt>and underscored, to call out potential
|
|
||||||
side effects, multiple uses of a formal argument, etc.</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
Four spaces of indentation per statement nesting level.</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
Tabs are taken to be eight spaces, and an Emacs magic comment at the top
|
|
||||||
of each file tries to help. If you're using MSVC or similar, you'll want
|
|
||||||
to set tab width to 8, and help convert these files to be space-filled.
|
|
||||||
<font color="#CC0000">Do not add hard tabs to source files; do remove them
|
|
||||||
whenever possible.</font></li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
DLL entry points have their return type expanded within a <tt>JS_PUBLIC_API()</tt>
|
|
||||||
macro call, to get the right Windows secret type qualifiers in the right
|
|
||||||
places for all build variants.</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
Callback functions that might be called from a DLL are similarly macroized
|
|
||||||
with <tt>JS_STATIC_DLL_CALLBACK</tt> (if the function otherwise would be
|
|
||||||
static to hide its name) or <tt>JS_DLL_CALLBACK</tt> (this macro takes
|
|
||||||
no type argument; it should be used after the return type and before the
|
|
||||||
function name).</li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<h2>
|
|
||||||
<a NAME="JSAPI"></a>Using the JS API</h2>
|
|
||||||
|
|
||||||
<p>The core JSAPI documentation is hosted on the Mozilla Developer Center.</p>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
|
|
||||||
<li><p>The <a href="http://developer.mozilla.org/en/docs/JSAPI_User_Guide">JSAPI
|
|
||||||
User Guide</a> explains the basic JSAPI concepts and includes large chunks
|
|
||||||
of sample code.</p></li>
|
|
||||||
|
|
||||||
<li><p>The <a href="http://developer.mozilla.org/en/docs/JSAPI_Phrasebook">JSAPI
|
|
||||||
Phrasebook</a> shows the JSAPI translation of some commonly used
|
|
||||||
JavaScript expressions and statements.</p></li>
|
|
||||||
|
|
||||||
<li><p>The <a href="http://developer.mozilla.org/en/docs/JSAPI_Reference">JSAPI
|
|
||||||
Reference</a> contains detailed documentation for each JSAPI
|
|
||||||
feature.</p></li>
|
|
||||||
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<h4>
|
|
||||||
Debugging API</h4>
|
|
||||||
See the<tt> trap, untrap, watch, unwatch, line2pc</tt>, and <tt>pc2line</tt>
|
|
||||||
commands in <tt>js.c</tt>. Also the (scant) comments in <i>jsdbgapi.h</i>.
|
|
||||||
<h2>
|
|
||||||
<a NAME="Design"></a>Design walk-through</h2>
|
|
||||||
This section must be brief for now -- it could easily turn into a book.
|
|
||||||
<h4>
|
|
||||||
JS "JavaScript Proper"</h4>
|
|
||||||
JS modules declare and implement the JavaScript compiler, interpreter,
|
|
||||||
decompiler, GC and atom manager, and standard classes.
|
|
||||||
<p>JavaScript uses untyped bytecode and runtime type tagging of data values.
|
|
||||||
The <tt>jsval</tt> type is a signed machine word that contains either a
|
|
||||||
signed integer value (if the low bit is set), or a type-tagged pointer
|
|
||||||
or boolean value (if the low bit is clear). Tagged pointers all refer to
|
|
||||||
8-byte-aligned things in the GC heap.
|
|
||||||
<p>Objects consist of a possibly shared structural description, called
|
|
||||||
the map or scope; and unshared property values in a vector, called the
|
|
||||||
slots. Object properties are associated with nonnegative integers stored
|
|
||||||
in <tt>jsval</tt>'s, or with atoms (unique string descriptors) if named
|
|
||||||
by an identifier or a non-integral index expression.
|
|
||||||
<p>Scripts contain bytecode, source annotations, and a pool of string,
|
|
||||||
number, and identifier literals. Functions are objects that extend scripts
|
|
||||||
or native functions with formal parameters, a literal syntax, and a distinct
|
|
||||||
primitive type ("function").
|
|
||||||
<p>The compiler consists of a recursive-descent parser and a random-logic
|
|
||||||
rather than table-driven lexical scanner. Semantic and lexical feedback
|
|
||||||
are used to disambiguate hard cases such as missing semicolons, assignable
|
|
||||||
expressions ("lvalues" in C parlance), etc. The parser generates bytecode
|
|
||||||
as it parses, using fixup lists for downward branches and code buffering
|
|
||||||
and rewriting for exceptional cases such as for loops. It attempts no error
|
|
||||||
recovery. The interpreter executes the bytecode of top-level scripts, and
|
|
||||||
calls itself indirectly to interpret function bodies (which are also scripts).
|
|
||||||
All state associated with an interpreter instance is passed through formal
|
|
||||||
parameters to the interpreter entry point; most implicit state is collected
|
|
||||||
in a type named JSContext. Therefore, all API and almost all other functions
|
|
||||||
in JSRef take a JSContext pointer as their first argument.
|
|
||||||
<p>The decompiler translates postfix bytecode into infix source by consulting
|
|
||||||
a separate byte-sized code, called source notes, to disambiguate bytecodes
|
|
||||||
that result from more than one grammatical production.
|
|
||||||
<p>The GC is a mark-and-sweep, non-conservative (exact) collector. It
|
|
||||||
can allocate only fixed-sized things -- the current size is two machine
|
|
||||||
words. It is used to hold JS object and string descriptors (but not property
|
|
||||||
lists or string bytes), and double-precision floating point numbers. It
|
|
||||||
runs automatically only when maxbytes (as passed to <tt>JS_NewRuntime()</tt>)
|
|
||||||
bytes of GC things have been allocated and another thing-allocation request
|
|
||||||
is made. JS API users should call <tt>JS_GC()</tt> or <tt>JS_MaybeGC()</tt>
|
|
||||||
between script executions or from the branch callback, as often as necessary.
|
|
||||||
<p>An important point about the GC's "exactness": you must add roots for
|
|
||||||
new objects created by your native methods if you store references to them
|
|
||||||
into a non-JS structure in the malloc heap or in static data. Also, if
|
|
||||||
you make a new object in a native method, but do not store it through the
|
|
||||||
<tt>rval</tt>
|
|
||||||
result parameter (see math_abs in the "Using the JS API" section above)
|
|
||||||
so that it is in a known root, the object is guaranteed to survive only
|
|
||||||
until another new object is created. Either lock the first new object when
|
|
||||||
making two in a row, or store it in a root you've added, or store it via
|
|
||||||
rval.
|
|
||||||
See the <a href="http://www.mozilla.org/js/spidermonkey/gctips.html">GC tips</a>
|
|
||||||
document for more.
|
|
||||||
<p>The atom manager consists of a hash table associating strings uniquely
|
|
||||||
with scanner/parser information such as keyword type, index in script or
|
|
||||||
function literal pool, etc. Atoms play three roles in JSRef: as literals
|
|
||||||
referred to by unaligned 16-bit immediate bytecode operands, as unique
|
|
||||||
string descriptors for efficient property name hashing, and as members
|
|
||||||
of the root GC set for exact GC.
|
|
||||||
<p>Native objects and methods for arrays, booleans, dates, functions, numbers,
|
|
||||||
and strings are implemented using the JS API and certain internal interfaces
|
|
||||||
used as "fast paths".
|
|
||||||
<p>In general, errors are signaled by false or unoverloaded-null return
|
|
||||||
values, and are reported using <tt>JS_ReportError()</tt> or one of its
|
|
||||||
variants by the lowest level in order to provide the most detail. Client
|
|
||||||
code can substitute its own error reporting function and suppress errors,
|
|
||||||
or reflect them into Java or some other runtime system as exceptions, GUI
|
|
||||||
dialogs, etc..
|
|
||||||
<h2>
|
|
||||||
File walk-through (OUT OF DATE!)</h2>
|
|
||||||
|
|
||||||
<h4>
|
|
||||||
jsapi.c, jsapi.h</h4>
|
|
||||||
The public API to be used by almost all client code. If your client
|
|
||||||
code can't make do with <tt>jsapi.h</tt>, and must reach into a friend
|
|
||||||
or private js* file, please let us know so we can extend <tt>jsapi.h</tt>
|
|
||||||
to include what you need in a fashion that we can support over the long
|
|
||||||
run.
|
|
||||||
<h4>
|
|
||||||
jspubtd.h, jsprvtd.h</h4>
|
|
||||||
These files exist to group struct and scalar typedefs so they can be used
|
|
||||||
everywhere without dragging in struct definitions from N different files.
|
|
||||||
The <tt>jspubtd.h</tt> file contains public typedefs, and is included by
|
|
||||||
<tt>jsapi.h</tt>.
|
|
||||||
The <tt>jsprvtd.h</tt> file contains private typedefs and is included by
|
|
||||||
various .h files that need type names, but not type sizes or declarations.
|
|
||||||
<h4>
|
|
||||||
jsdbgapi.c, jsdbgapi.h</h4>
|
|
||||||
The Debugging API, still very much under development. Provided so far:
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Traps, with which breakpoints, single-stepping, step over, step out, and
|
|
||||||
so on can be implemented. The debugger will have to consult jsopcode.def
|
|
||||||
on its own to figure out where to plant trap instructions to implement
|
|
||||||
functions like step out, but a future jsdbgapi.h will provide convenience
|
|
||||||
interfaces to do these things. At most one trap per bytecode can be set.
|
|
||||||
When a script (<tt>JSScript</tt>) is destroyed, all traps set in its bytecode
|
|
||||||
are cleared.</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
Watchpoints, for intercepting set operations on properties and running
|
|
||||||
a debugger-supplied function that receives the old value and a pointer
|
|
||||||
to the new one, which it can use to modify the new value being set.</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
Line number to PC and back mapping functions. The line-to-PC direction
|
|
||||||
"rounds" toward the next bytecode generated from a line greater than or
|
|
||||||
equal to the input line, and may return the PC of a for-loop update part,
|
|
||||||
if given the line number of the loop body's closing brace. Any line after
|
|
||||||
the last one in a script or function maps to a PC one byte beyond the last
|
|
||||||
bytecode in the script. An example, from perfect.js:</li>
|
|
||||||
|
|
||||||
<pre><tt>14 function perfect(n)
|
|
||||||
15 {
|
|
||||||
16 print("The perfect numbers up to " + n + " are:");
|
|
||||||
17
|
|
||||||
18 // We build sumOfDivisors[i] to hold a string expression for
|
|
||||||
19 // the sum of the divisors of i, excluding i itself.
|
|
||||||
20 var sumOfDivisors = new ExprArray(n+1,1);
|
|
||||||
21 for (var divisor = 2; divisor <= n; divisor++) {
|
|
||||||
22 for (var j = divisor + divisor; j <= n; j += divisor) {
|
|
||||||
23 sumOfDivisors[j] += " + " + divisor;
|
|
||||||
24 }
|
|
||||||
25 // At this point everything up to 'divisor' has its sumOfDivisors
|
|
||||||
26 // expression calculated, so we can determine whether it's perfect
|
|
||||||
27 // already by evaluating.
|
|
||||||
28 if (eval(sumOfDivisors[divisor]) == divisor) {
|
|
||||||
29 print("" + divisor + " = " + sumOfDivisors[divisor]);
|
|
||||||
30 }
|
|
||||||
31 }
|
|
||||||
32 delete sumOfDivisors;
|
|
||||||
33 print("That's all.");
|
|
||||||
34 }</tt></pre>
|
|
||||||
The line number to PC and back mappings can be tested using the js program
|
|
||||||
with the following script:
|
|
||||||
<pre><tt> load("perfect.js")
|
|
||||||
print(perfect)
|
|
||||||
dis(perfect)
|
|
||||||
|
|
||||||
print()
|
|
||||||
for (var ln = 0; ln <= 40; ln++) {
|
|
||||||
var pc = line2pc(perfect,ln)
|
|
||||||
var ln2 = pc2line(perfect,pc)
|
|
||||||
print("\tline " + ln + " => pc " + pc + " => line " + ln2)
|
|
||||||
}</tt></pre>
|
|
||||||
The result of the for loop over lines 0 to 40 inclusive is:
|
|
||||||
<pre><tt> line 0 => pc 0 => line 16
|
|
||||||
line 1 => pc 0 => line 16
|
|
||||||
line 2 => pc 0 => line 16
|
|
||||||
line 3 => pc 0 => line 16
|
|
||||||
line 4 => pc 0 => line 16
|
|
||||||
line 5 => pc 0 => line 16
|
|
||||||
line 6 => pc 0 => line 16
|
|
||||||
line 7 => pc 0 => line 16
|
|
||||||
line 8 => pc 0 => line 16
|
|
||||||
line 9 => pc 0 => line 16
|
|
||||||
line 10 => pc 0 => line 16
|
|
||||||
line 11 => pc 0 => line 16
|
|
||||||
line 12 => pc 0 => line 16
|
|
||||||
line 13 => pc 0 => line 16
|
|
||||||
line 14 => pc 0 => line 16
|
|
||||||
line 15 => pc 0 => line 16
|
|
||||||
line 16 => pc 0 => line 16
|
|
||||||
line 17 => pc 19 => line 20
|
|
||||||
line 18 => pc 19 => line 20
|
|
||||||
line 19 => pc 19 => line 20
|
|
||||||
line 20 => pc 19 => line 20
|
|
||||||
line 21 => pc 36 => line 21
|
|
||||||
line 22 => pc 53 => line 22
|
|
||||||
line 23 => pc 74 => line 23
|
|
||||||
line 24 => pc 92 => line 22
|
|
||||||
line 25 => pc 106 => line 28
|
|
||||||
line 26 => pc 106 => line 28
|
|
||||||
line 27 => pc 106 => line 28
|
|
||||||
line 28 => pc 106 => line 28
|
|
||||||
line 29 => pc 127 => line 29
|
|
||||||
line 30 => pc 154 => line 21
|
|
||||||
line 31 => pc 154 => line 21
|
|
||||||
line 32 => pc 161 => line 32
|
|
||||||
line 33 => pc 172 => line 33
|
|
||||||
line 34 => pc 172 => line 33
|
|
||||||
line 35 => pc 172 => line 33
|
|
||||||
line 36 => pc 172 => line 33
|
|
||||||
line 37 => pc 172 => line 33
|
|
||||||
line 38 => pc 172 => line 33
|
|
||||||
line 39 => pc 172 => line 33
|
|
||||||
line 40 => pc 172 => line 33</tt></pre>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<h4>
|
|
||||||
jsconfig.h</h4>
|
|
||||||
Various configuration macros defined as 0 or 1 depending on how <tt>JS_VERSION</tt>
|
|
||||||
is defined (as 10 for JavaScript 1.0, 11 for JavaScript 1.1, etc.). Not
|
|
||||||
all macros are tested around related code yet. In particular, JS 1.0 support
|
|
||||||
is missing from JSRef. JS 1.2 support will appear in a future JSRef release.
|
|
||||||
<br>
|
|
||||||
<h4>
|
|
||||||
js.c</h4>
|
|
||||||
The "JS shell", a simple interpreter program that uses the JS API and more
|
|
||||||
than a few internal interfaces (some of these internal interfaces could
|
|
||||||
be replaced by <tt>jsapi.h</tt> calls). The js program built from this
|
|
||||||
source provides a test vehicle for evaluating scripts and calling functions,
|
|
||||||
trying out new debugger primitives, etc.
|
|
||||||
<h4>
|
|
||||||
jsarray.*, jsbool.*, jdsdate.*, jsfun.*, jsmath.*, jsnum.*, jsstr.*</h4>
|
|
||||||
These file pairs implement the standard classes and (where they exist)
|
|
||||||
their underlying primitive types. They have similar structure, generally
|
|
||||||
starting with class definitions and continuing with internal constructors,
|
|
||||||
finalizers, and helper functions.
|
|
||||||
<h4>
|
|
||||||
jsobj.*, jsscope.*</h4>
|
|
||||||
These two pairs declare and implement the JS object system. All of the
|
|
||||||
following happen here:
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
creating objects by class and prototype, and finalizing objects;</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
defining, looking up, getting, setting, and deleting properties;</li>
|
|
||||||
|
|
||||||
<li>
|
|
||||||
creating and destroying properties and binding names to them.</li>
|
|
||||||
</ul>
|
|
||||||
The details of a native object's map (scope) are mostly hidden in
|
|
||||||
<tt>jsscope.[ch]</tt>.
|
|
||||||
<h4>
|
|
||||||
jsatom.c, jsatom.h</h4>
|
|
||||||
The atom manager. Contains well-known string constants, their atoms, the
|
|
||||||
global atom hash table and related state, the js_Atomize() function that
|
|
||||||
turns a counted string of bytes into an atom, and literal pool (<tt>JSAtomMap</tt>)
|
|
||||||
methods.
|
|
||||||
<h4>
|
|
||||||
jsgc.c, jsgc.h</h4>
|
|
||||||
[TBD]
|
|
||||||
<h4>
|
|
||||||
jsinterp.*, jscntxt.*</h4>
|
|
||||||
The bytecode interpreter, and related functions such as Call and AllocStack,
|
|
||||||
live in <i>jsinterp.c</i>. The JSContext constructor and destructor are
|
|
||||||
factored out into <i>jscntxt.c</i> for minimal linking when the compiler
|
|
||||||
part of JS is split from the interpreter part into a separate program.
|
|
||||||
<h4>
|
|
||||||
jsemit.*, jsopcode.tbl, jsopcode.*, jsparse.*, jsscan.*, jsscript.*</h4>
|
|
||||||
Compiler and decompiler modules. The <i>jsopcode.tbl</i> file is a C preprocessor
|
|
||||||
source that defines almost everything there is to know about JS bytecodes.
|
|
||||||
See its major comment for how to use it. For now, a debugger will use it
|
|
||||||
and its dependents such as <i>jsopcode.h</i> directly, but over time we
|
|
||||||
intend to extend <i>jsdbgapi.h</i> to hide uninteresting details and provide
|
|
||||||
conveniences. The code generator is split across paragraphs of code in
|
|
||||||
<i>jsparse.c</i>,
|
|
||||||
and the utility methods called on <tt>JSCodeGenerator</tt> appear in <i>jsemit.c</i>.
|
|
||||||
Source notes generated by <i>jsparse.c</i> and
|
|
||||||
<i>jsemit.c</i> are used
|
|
||||||
in <i>jsscript.c</i> to map line number to program counter and back.
|
|
||||||
<h4>
|
|
||||||
jstypes.h, jslog2.c</h4>
|
|
||||||
Fundamental representation types and utility macros. This file alone among
|
|
||||||
all .h files in JSRef must be included first by .c files. It is not nested
|
|
||||||
in .h files, as other prerequisite .h files generally are, since it is
|
|
||||||
also a direct dependency of most .c files and would be over-included if
|
|
||||||
nested in addition to being directly included. The one "not-quite-a-macro
|
|
||||||
macro" is the <tt>JS_CeilingLog2()</tt> function in <i>jslog2.c</i>.
|
|
||||||
<h4>
|
|
||||||
jsarena.c, jsarena.h</h4>
|
|
||||||
Last-In-First-Out allocation macros that amortize malloc costs and allow
|
|
||||||
for en-masse freeing. See the paper mentioned in prarena.h's major comment.
|
|
||||||
<h4>
|
|
||||||
jsutil.c, jsutil.h</h4>
|
|
||||||
The <tt>JS_ASSERT</tt> macro is used throughout JSRef source as a proof
|
|
||||||
device to make invariants and preconditions clear to the reader, and to
|
|
||||||
hold the line during maintenance and evolution against regressions or violations
|
|
||||||
of assumptions that it would be too expensive to test unconditionally at
|
|
||||||
run-time. Certain assertions are followed by run-time tests that cope with
|
|
||||||
assertion failure, but only where I'm too smart or paranoid to believe
|
|
||||||
the assertion will never fail...
|
|
||||||
<h4>
|
|
||||||
jsclist.h</h4>
|
|
||||||
Doubly-linked circular list struct and macros.
|
|
||||||
<h4>
|
|
||||||
jscpucfg.c</h4>
|
|
||||||
This standalone program generates <i>jscpucfg.h</i>, a header file containing
|
|
||||||
bytes per word and other constants that depend on CPU architecture and
|
|
||||||
C compiler type model. It tries to discover most of these constants by
|
|
||||||
running its own experiments on the build host, so if you are cross-compiling,
|
|
||||||
beware.
|
|
||||||
<h4>
|
|
||||||
prdtoa.c, prdtoa.h</h4>
|
|
||||||
David Gay's portable double-precision floating point to string conversion
|
|
||||||
code, with Permission To Use notice included.
|
|
||||||
<h4>
|
|
||||||
prhash.c, prhash.h</h4>
|
|
||||||
Portable, extensible hash tables. These use multiplicative hash for strength
|
|
||||||
reduction over division hash, yet with very good key distribution over
|
|
||||||
power of two table sizes. Collisions resolve via chaining, so each entry
|
|
||||||
burns a malloc and can fragment the heap.
|
|
||||||
<h4>
|
|
||||||
prlong.c, prlong.h</h4>
|
|
||||||
64-bit integer emulation, and compatible macros that use C's long long
|
|
||||||
type where it exists (my last company mapped long long to a 128-bit type,
|
|
||||||
but no real architecture does 128-bit ints yet).
|
|
||||||
<h4>
|
|
||||||
jsprf.*</h4>
|
|
||||||
Portable, buffer-overrun-resistant sprintf and friends. For no good reason
|
|
||||||
save lack of time, the %e, %f, and %g formats cause your system's native
|
|
||||||
sprintf, rather than <tt>JS_dtoa()</tt>, to be used. This bug doesn't affect
|
|
||||||
JSRef, because it uses its own <tt>JS_dtoa()</tt> call in <i>jsnum.c</i>
|
|
||||||
to convert from double to string, but it's a bug that we'll fix later,
|
|
||||||
and one you should be aware of if you intend to use a <tt>JS_*printf()</tt>
|
|
||||||
function with your own floating type arguments - various vendor sprintf's
|
|
||||||
mishandle NaN, +/-Inf, and some even print normal floating values inaccurately.
|
|
||||||
<h4>
|
|
||||||
prmjtime.c, prmjtime.h</h4>
|
|
||||||
Time functions. These interfaces are named in a way that makes local vs.
|
|
||||||
universal time confusion likely. Caveat emptor, and we're working on it.
|
|
||||||
To make matters worse, Java (and therefore JavaScript) uses "local" time
|
|
||||||
numbers (offsets from the epoch) in its Date class.
|
|
||||||
|
|
||||||
|
|
||||||
<h2>
|
|
||||||
<a NAME="Resources"></a>Additional Resources (links, API docs, and newsgroups)</h2>
|
|
||||||
<ul>
|
|
||||||
<li><a href ="http://developer.mozilla.org/en/docs/JavaScript">http://developer.mozilla.org/en/docs/JavaScript</a>
|
|
||||||
<li><a href ="http://developer.mozilla.org/en/docs/SpiderMonkey">http://developer.mozilla.org/en/docs/SpiderMonkey</a>
|
|
||||||
<li><a href ="news://news.mozilla.org/mozilla.dev.tech.js-engine">news://news.mozilla.org/mozilla.dev.tech.js-engine</a>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
|
|
||||||
|
<p>See the
|
||||||
|
<a href="http://developer.mozilla.org/en/docs/SpiderMonkey">SpiderMonkey
|
||||||
|
pages</a> on the Mozilla Developer Center</a>.
|
||||||
|
|
||||||
</body>
|
</body>
|
||||||
</html>
|
</html>
|
||||||
|
|
Загрузка…
Ссылка в новой задаче