| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- Created by GNU Texinfo 6.1, http://www.gnu.org/software/texinfo/ --> |
| <head> |
| <title>QuickJS Javascript Engine</title> |
| |
| <meta name="description" content="QuickJS Javascript Engine"> |
| <meta name="keywords" content="QuickJS Javascript Engine"> |
| <meta name="resource-type" content="document"> |
| <meta name="distribution" content="global"> |
| <meta name="Generator" content="makeinfo"> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <link href="#SEC_Contents" rel="contents" title="Table of Contents"> |
| <style type="text/css"> |
| <!-- |
| a.summary-letter {text-decoration: none} |
| blockquote.indentedblock {margin-right: 0em} |
| blockquote.smallindentedblock {margin-right: 0em; font-size: smaller} |
| blockquote.smallquotation {font-size: smaller} |
| div.display {margin-left: 3.2em} |
| div.example {margin-left: 3.2em} |
| div.lisp {margin-left: 3.2em} |
| div.smalldisplay {margin-left: 3.2em} |
| div.smallexample {margin-left: 3.2em} |
| div.smalllisp {margin-left: 3.2em} |
| kbd {font-style: oblique} |
| pre.display {font-family: inherit} |
| pre.format {font-family: inherit} |
| pre.menu-comment {font-family: serif} |
| pre.menu-preformatted {font-family: serif} |
| pre.smalldisplay {font-family: inherit; font-size: smaller} |
| pre.smallexample {font-size: smaller} |
| pre.smallformat {font-family: inherit; font-size: smaller} |
| pre.smalllisp {font-size: smaller} |
| span.nolinebreak {white-space: nowrap} |
| span.roman {font-family: initial; font-weight: normal} |
| span.sansserif {font-family: sans-serif; font-weight: normal} |
| ul.no-bullet {list-style: none} |
| --> |
| </style> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| |
| |
| </head> |
| |
| <body lang="en"> |
| <h1 class="settitle" align="center">QuickJS Javascript Engine</h1> |
| |
| <a name="SEC_Contents"></a> |
| <h2 class="contents-heading">Table of Contents</h2> |
| |
| <div class="contents"> |
| <ul class="no-bullet"> |
| <li><a name="toc-Introduction" href="#Introduction">1 Introduction</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-Main-Features" href="#Main-Features">1.1 Main Features</a></li> |
| </ul></li> |
| <li><a name="toc-Usage" href="#Usage">2 Usage</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-Installation" href="#Installation">2.1 Installation</a></li> |
| <li><a name="toc-Quick-start" href="#Quick-start">2.2 Quick start</a></li> |
| <li><a name="toc-Command-line-options" href="#Command-line-options">2.3 Command line options</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-qjs-interpreter" href="#qjs-interpreter">2.3.1 <code>qjs</code> interpreter</a></li> |
| <li><a name="toc-qjsc-compiler" href="#qjsc-compiler">2.3.2 <code>qjsc</code> compiler</a></li> |
| </ul></li> |
| <li><a name="toc-qjscalc-application" href="#qjscalc-application">2.4 <code>qjscalc</code> application</a></li> |
| <li><a name="toc-Built_002din-tests" href="#Built_002din-tests">2.5 Built-in tests</a></li> |
| <li><a name="toc-Test262-_0028ECMAScript-Test-Suite_0029" href="#Test262-_0028ECMAScript-Test-Suite_0029">2.6 Test262 (ECMAScript Test Suite)</a></li> |
| </ul></li> |
| <li><a name="toc-Specifications" href="#Specifications">3 Specifications</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-Language-support" href="#Language-support">3.1 Language support</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-ES2020-support" href="#ES2020-support">3.1.1 ES2020 support</a></li> |
| <li><a name="toc-ECMA402" href="#ECMA402">3.1.2 ECMA402</a></li> |
| <li><a name="toc-Extensions" href="#Extensions">3.1.3 Extensions</a></li> |
| <li><a name="toc-Mathematical-extensions" href="#Mathematical-extensions">3.1.4 Mathematical extensions</a></li> |
| </ul></li> |
| <li><a name="toc-Modules" href="#Modules">3.2 Modules</a></li> |
| <li><a name="toc-Standard-library" href="#Standard-library">3.3 Standard library</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-Global-objects" href="#Global-objects">3.3.1 Global objects</a></li> |
| <li><a name="toc-std-module" href="#std-module">3.3.2 <code>std</code> module</a></li> |
| <li><a name="toc-os-module" href="#os-module">3.3.3 <code>os</code> module</a></li> |
| </ul></li> |
| <li><a name="toc-QuickJS-C-API" href="#QuickJS-C-API">3.4 QuickJS C API</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-Runtime-and-contexts" href="#Runtime-and-contexts">3.4.1 Runtime and contexts</a></li> |
| <li><a name="toc-JSValue" href="#JSValue">3.4.2 JSValue</a></li> |
| <li><a name="toc-C-functions" href="#C-functions">3.4.3 C functions</a></li> |
| <li><a name="toc-Exceptions" href="#Exceptions">3.4.4 Exceptions</a></li> |
| <li><a name="toc-Script-evaluation" href="#Script-evaluation">3.4.5 Script evaluation</a></li> |
| <li><a name="toc-JS-Classes" href="#JS-Classes">3.4.6 JS Classes</a></li> |
| <li><a name="toc-C-Modules" href="#C-Modules">3.4.7 C Modules</a></li> |
| <li><a name="toc-Memory-handling" href="#Memory-handling">3.4.8 Memory handling</a></li> |
| <li><a name="toc-Execution-timeout-and-interrupts" href="#Execution-timeout-and-interrupts">3.4.9 Execution timeout and interrupts</a></li> |
| </ul></li> |
| </ul></li> |
| <li><a name="toc-Internals" href="#Internals">4 Internals</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-Bytecode" href="#Bytecode">4.1 Bytecode</a></li> |
| <li><a name="toc-Executable-generation" href="#Executable-generation">4.2 Executable generation</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-qjsc-compiler-1" href="#qjsc-compiler-1">4.2.1 <code>qjsc</code> compiler</a></li> |
| <li><a name="toc-Binary-JSON" href="#Binary-JSON">4.2.2 Binary JSON</a></li> |
| </ul></li> |
| <li><a name="toc-Runtime" href="#Runtime">4.3 Runtime</a> |
| <ul class="no-bullet"> |
| <li><a name="toc-Strings" href="#Strings">4.3.1 Strings</a></li> |
| <li><a name="toc-Objects" href="#Objects">4.3.2 Objects</a></li> |
| <li><a name="toc-Atoms" href="#Atoms">4.3.3 Atoms</a></li> |
| <li><a name="toc-Numbers" href="#Numbers">4.3.4 Numbers</a></li> |
| <li><a name="toc-Garbage-collection" href="#Garbage-collection">4.3.5 Garbage collection</a></li> |
| <li><a name="toc-JSValue-1" href="#JSValue-1">4.3.6 JSValue</a></li> |
| <li><a name="toc-Function-call" href="#Function-call">4.3.7 Function call</a></li> |
| </ul></li> |
| <li><a name="toc-RegExp" href="#RegExp">4.4 RegExp</a></li> |
| <li><a name="toc-Unicode" href="#Unicode">4.5 Unicode</a></li> |
| <li><a name="toc-BigInt_002c-BigFloat_002c-BigDecimal" href="#BigInt_002c-BigFloat_002c-BigDecimal">4.6 BigInt, BigFloat, BigDecimal</a></li> |
| </ul></li> |
| <li><a name="toc-License" href="#License">5 License</a></li> |
| |
| </ul> |
| </div> |
| |
| |
| <a name="Introduction"></a> |
| <h2 class="chapter">1 Introduction</h2> |
| |
| <p>QuickJS is a small and embeddable Javascript engine. It supports the |
| ES2020 specification |
| <a name="DOCF1" href="#FOOT1"><sup>1</sup></a> |
| including modules, asynchronous generators, proxies and BigInt. |
| </p> |
| <p>It supports mathematical extensions such as big decimal float float |
| numbers (BigDecimal), big binary floating point numbers (BigFloat), |
| and operator overloading. |
| </p> |
| <a name="Main-Features"></a> |
| <h3 class="section">1.1 Main Features</h3> |
| |
| <ul> |
| <li> Small and easily embeddable: just a few C files, no external dependency, 210 KiB of x86 code for a simple “hello world” program. |
| |
| </li><li> Fast interpreter with very low startup time: runs the 69000 tests of the ECMAScript Test Suite<a name="DOCF2" href="#FOOT2"><sup>2</sup></a> in about 95 seconds on a single core of a desktop PC. The complete life cycle of a runtime instance completes in less than 300 microseconds. |
| |
| </li><li> Almost complete ES2020 support including modules, asynchronous |
| generators and full Annex B support (legacy web compatibility). Many |
| features from the upcoming ES2021 specification |
| <a name="DOCF3" href="#FOOT3"><sup>3</sup></a> are also supported. |
| |
| </li><li> Passes nearly 100% of the ECMAScript Test Suite tests when selecting the ES2020 features. |
| |
| </li><li> Compile Javascript sources to executables with no external dependency. |
| |
| </li><li> Garbage collection using reference counting (to reduce memory usage and have deterministic behavior) with cycle removal. |
| |
| </li><li> Mathematical extensions: BigDecimal, BigFloat, operator overloading, bigint mode, math mode. |
| |
| </li><li> Command line interpreter with contextual colorization and completion implemented in Javascript. |
| |
| </li><li> Small built-in standard library with C library wrappers. |
| |
| </li></ul> |
| |
| <a name="Usage"></a> |
| <h2 class="chapter">2 Usage</h2> |
| |
| <a name="Installation"></a> |
| <h3 class="section">2.1 Installation</h3> |
| |
| <p>A Makefile is provided to compile the engine on Linux or MacOS/X. A |
| preliminary Windows support is available thru cross compilation on a |
| Linux host with the MingGW tools. |
| </p> |
| <p>Edit the top of the <code>Makefile</code> if you wish to select specific |
| options then run <code>make</code>. |
| </p> |
| <p>You can type <code>make install</code> as root if you wish to install the binaries and support files to |
| <code>/usr/local</code> (this is not necessary to use QuickJS). |
| </p> |
| <a name="Quick-start"></a> |
| <h3 class="section">2.2 Quick start</h3> |
| |
| <p><code>qjs</code> is the command line interpreter (Read-Eval-Print Loop). You can pass |
| Javascript files and/or expressions as arguments to execute them: |
| </p> |
| <div class="example"> |
| <pre class="example">./qjs examples/hello.js |
| </pre></div> |
| |
| <p><code>qjsc</code> is the command line compiler: |
| </p> |
| <div class="example"> |
| <pre class="example">./qjsc -o hello examples/hello.js |
| ./hello |
| </pre></div> |
| |
| <p>generates a <code>hello</code> executable with no external dependency. |
| </p> |
| <a name="Command-line-options"></a> |
| <h3 class="section">2.3 Command line options</h3> |
| |
| <a name="qjs-interpreter"></a> |
| <h4 class="subsection">2.3.1 <code>qjs</code> interpreter</h4> |
| |
| <pre class="verbatim">usage: qjs [options] [file [args]] |
| </pre> |
| <p>Options are: |
| </p><dl compact="compact"> |
| <dt><code>-h</code></dt> |
| <dt><code>--help</code></dt> |
| <dd><p>List options. |
| </p> |
| </dd> |
| <dt><code>-e <code>EXPR</code></code></dt> |
| <dt><code>--eval <code>EXPR</code></code></dt> |
| <dd><p>Evaluate EXPR. |
| </p> |
| </dd> |
| <dt><code>-i</code></dt> |
| <dt><code>--interactive</code></dt> |
| <dd><p>Go to interactive mode (it is not the default when files are provided on the command line). |
| </p> |
| </dd> |
| <dt><code>-m</code></dt> |
| <dt><code>--module</code></dt> |
| <dd><p>Load as ES6 module (default=autodetect). A module is autodetected if |
| the filename extension is <code>.mjs</code> or if the first keyword of the |
| source is <code>import</code>. |
| </p> |
| </dd> |
| <dt><code>--script</code></dt> |
| <dd><p>Load as ES6 script (default=autodetect). |
| </p> |
| </dd> |
| <dt><code>--bignum</code></dt> |
| <dd><p>Enable the bignum extensions: BigDecimal object, BigFloat object and |
| the <code>"use math"</code> directive. |
| </p> |
| </dd> |
| <dt><code>-I file</code></dt> |
| <dt><code>--include file</code></dt> |
| <dd><p>Include an additional file. |
| </p> |
| </dd> |
| </dl> |
| |
| <p>Advanced options are: |
| </p> |
| <dl compact="compact"> |
| <dt><code>--std</code></dt> |
| <dd><p>Make the <code>std</code> and <code>os</code> modules available to the loaded |
| script even if it is not a module. |
| </p> |
| </dd> |
| <dt><code>-d</code></dt> |
| <dt><code>--dump</code></dt> |
| <dd><p>Dump the memory usage stats. |
| </p> |
| </dd> |
| <dt><code>-q</code></dt> |
| <dt><code>--quit</code></dt> |
| <dd><p>just instantiate the interpreter and quit. |
| </p> |
| </dd> |
| </dl> |
| |
| <a name="qjsc-compiler"></a> |
| <h4 class="subsection">2.3.2 <code>qjsc</code> compiler</h4> |
| |
| <pre class="verbatim">usage: qjsc [options] [files] |
| </pre> |
| <p>Options are: |
| </p><dl compact="compact"> |
| <dt><code>-c</code></dt> |
| <dd><p>Only output bytecode in a C file. The default is to output an executable file. |
| </p></dd> |
| <dt><code>-e</code></dt> |
| <dd><p>Output <code>main()</code> and bytecode in a C file. The default is to output an |
| executable file. |
| </p></dd> |
| <dt><code>-o output</code></dt> |
| <dd><p>Set the output filename (default = <samp>out.c</samp> or <samp>a.out</samp>). |
| </p> |
| </dd> |
| <dt><code>-N cname</code></dt> |
| <dd><p>Set the C name of the generated data. |
| </p> |
| </dd> |
| <dt><code>-m</code></dt> |
| <dd><p>Compile as Javascript module (default=autodetect). |
| </p> |
| </dd> |
| <dt><code>-D module_name</code></dt> |
| <dd><p>Compile a dynamically loaded module and its dependencies. This option |
| is needed when your code uses the <code>import</code> keyword or the |
| <code>os.Worker</code> constructor because the compiler cannot statically |
| find the name of the dynamically loaded modules. |
| </p> |
| </dd> |
| <dt><code>-M module_name[,cname]</code></dt> |
| <dd><p>Add initialization code for an external C module. See the |
| <code>c_module</code> example. |
| </p> |
| </dd> |
| <dt><code>-x</code></dt> |
| <dd><p>Byte swapped output (only used for cross compilation). |
| </p> |
| </dd> |
| <dt><code>-flto</code></dt> |
| <dd><p>Use link time optimization. The compilation is slower but the |
| executable is smaller and faster. This option is automatically set |
| when the <code>-fno-x</code> options are used. |
| </p> |
| </dd> |
| <dt><code>-fno-[eval|string-normalize|regexp|json|proxy|map|typedarray|promise|bigint]</code></dt> |
| <dd><p>Disable selected language features to produce a smaller executable file. |
| </p> |
| </dd> |
| <dt><code>-fbignum</code></dt> |
| <dd><p>Enable the bignum extensions: BigDecimal object, BigFloat object and |
| the <code>"use math"</code> directive. |
| </p> |
| </dd> |
| </dl> |
| |
| <a name="qjscalc-application"></a> |
| <h3 class="section">2.4 <code>qjscalc</code> application</h3> |
| |
| <p>The <code>qjscalc</code> application is a superset of the <code>qjs</code> |
| command line interpreter implementing a Javascript calculator with |
| arbitrarily large integer and floating point numbers, fractions, |
| complex numbers, polynomials and matrices. The source code is in |
| <samp>qjscalc.js</samp>. More documentation and a web version are available at |
| <a href="http://numcalc.com">http://numcalc.com</a>. |
| </p> |
| <a name="Built_002din-tests"></a> |
| <h3 class="section">2.5 Built-in tests</h3> |
| |
| <p>Run <code>make test</code> to run the few built-in tests included in the |
| QuickJS archive. |
| </p> |
| <a name="Test262-_0028ECMAScript-Test-Suite_0029"></a> |
| <h3 class="section">2.6 Test262 (ECMAScript Test Suite)</h3> |
| |
| <p>A test262 runner is included in the QuickJS archive. The test262 tests |
| can be installed in the QuickJS source directory with: |
| </p> |
| <div class="example"> |
| <pre class="example">git clone https://github.com/tc39/test262.git test262 |
| cd test262 |
| patch -p1 < ../tests/test262.patch |
| cd .. |
| </pre></div> |
| |
| <p>The patch adds the implementation specific <code>harness</code> functions |
| and optimizes the inefficient RegExp character classes and Unicode |
| property escapes tests (the tests themselves are not modified, only a |
| slow string initialization function is optimized). |
| </p> |
| <p>The tests can be run with |
| </p><div class="example"> |
| <pre class="example">make test2 |
| </pre></div> |
| |
| <p>The configuration files <code>test262.conf</code> |
| (resp. <code>test262o.conf</code> for the old ES5.1 tests<a name="DOCF4" href="#FOOT4"><sup>4</sup></a>)) |
| contain the options to run the various tests. Tests can be excluded |
| based on features or filename. |
| </p> |
| <p>The file <code>test262_errors.txt</code> contains the current list of |
| errors. The runner displays a message when a new error appears or when |
| an existing error is corrected or modified. Use the <code>-u</code> option |
| to update the current list of errors (or <code>make test2-update</code>). |
| </p> |
| <p>The file <code>test262_report.txt</code> contains the logs of all the |
| tests. It is useful to have a clearer analysis of a particular |
| error. In case of crash, the last line corresponds to the failing |
| test. |
| </p> |
| <p>Use the syntax <code>./run-test262 -c test262.conf -f filename.js</code> to |
| run a single test. Use the syntax <code>./run-test262 -c test262.conf |
| N</code> to start testing at test number <code>N</code>. |
| </p> |
| <p>For more information, run <code>./run-test262</code> to see the command line |
| options of the test262 runner. |
| </p> |
| <p><code>run-test262</code> accepts the <code>-N</code> option to be invoked from |
| <code>test262-harness</code><a name="DOCF5" href="#FOOT5"><sup>5</sup></a> |
| thru <code>eshost</code>. Unless you want to compare QuickJS with other |
| engines under the same conditions, we do not recommend to run the |
| tests this way as it is much slower (typically half an hour instead of |
| about 100 seconds). |
| </p> |
| <a name="Specifications"></a> |
| <h2 class="chapter">3 Specifications</h2> |
| |
| <a name="Language-support"></a> |
| <h3 class="section">3.1 Language support</h3> |
| |
| <a name="ES2020-support"></a> |
| <h4 class="subsection">3.1.1 ES2020 support</h4> |
| |
| <p>The ES2020 specification is almost fully supported including the Annex |
| B (legacy web compatibility) and the Unicode related features. |
| </p> |
| <p>The following features are not supported yet: |
| </p> |
| <ul> |
| <li> Tail calls<a name="DOCF6" href="#FOOT6"><sup>6</sup></a> |
| |
| </li></ul> |
| |
| <a name="ECMA402"></a> |
| <h4 class="subsection">3.1.2 ECMA402</h4> |
| |
| <p>ECMA402 (Internationalization API) is not supported. |
| </p> |
| <a name="Extensions"></a> |
| <h4 class="subsection">3.1.3 Extensions</h4> |
| |
| <ul> |
| <li> The directive <code>"use strip"</code> indicates that the debug information (including the source code of the functions) should not be retained to save memory. As <code>"use strict"</code>, the directive can be global to a script or local to a function. |
| |
| </li><li> The first line of a script beginning with <code>#!</code> is ignored. |
| |
| </li></ul> |
| |
| <a name="Mathematical-extensions"></a> |
| <h4 class="subsection">3.1.4 Mathematical extensions</h4> |
| |
| <p>The mathematical extensions are fully backward compatible with |
| standard Javascript. See <code>jsbignum.pdf</code> for more information. |
| </p> |
| <ul> |
| <li> <code>BigDecimal</code> support: arbitrary large floating point numbers in base 10. |
| |
| </li><li> <code>BigFloat</code> support: arbitrary large floating point numbers in base 2. |
| |
| </li><li> Operator overloading. |
| |
| </li><li> The directive <code>"use bigint"</code> enables the bigint mode where integers are <code>BigInt</code> by default. |
| |
| </li><li> The directive <code>"use math"</code> enables the math mode where the division and power operators on integers produce fractions. Floating point literals are <code>BigFloat</code> by default and integers are <code>BigInt</code> by default. |
| |
| </li></ul> |
| |
| <a name="Modules"></a> |
| <h3 class="section">3.2 Modules</h3> |
| |
| <p>ES6 modules are fully supported. The default name resolution is the |
| following: |
| </p> |
| <ul> |
| <li> Module names with a leading <code>.</code> or <code>..</code> are relative |
| to the current module path. |
| |
| </li><li> Module names without a leading <code>.</code> or <code>..</code> are system |
| modules, such as <code>std</code> or <code>os</code>. |
| |
| </li><li> Module names ending with <code>.so</code> are native modules using the |
| QuickJS C API. |
| |
| </li></ul> |
| |
| <a name="Standard-library"></a> |
| <h3 class="section">3.3 Standard library</h3> |
| |
| <p>The standard library is included by default in the command line |
| interpreter. It contains the two modules <code>std</code> and <code>os</code> and |
| a few global objects. |
| </p> |
| <a name="Global-objects"></a> |
| <h4 class="subsection">3.3.1 Global objects</h4> |
| |
| <dl compact="compact"> |
| <dt><code>scriptArgs</code></dt> |
| <dd><p>Provides the command line arguments. The first argument is the script name. |
| </p></dd> |
| <dt><code>print(...args)</code></dt> |
| <dd><p>Print the arguments separated by spaces and a trailing newline. |
| </p></dd> |
| <dt><code>console.log(...args)</code></dt> |
| <dd><p>Same as print(). |
| </p> |
| </dd> |
| </dl> |
| |
| <a name="std-module"></a> |
| <h4 class="subsection">3.3.2 <code>std</code> module</h4> |
| |
| <p>The <code>std</code> module provides wrappers to the libc <samp>stdlib.h</samp> |
| and <samp>stdio.h</samp> and a few other utilities. |
| </p> |
| <p>Available exports: |
| </p> |
| <dl compact="compact"> |
| <dt><code>exit(n)</code></dt> |
| <dd><p>Exit the process. |
| </p> |
| </dd> |
| <dt><code>evalScript(str, options = undefined)</code></dt> |
| <dd><p>Evaluate the string <code>str</code> as a script (global |
| eval). <code>options</code> is an optional object containing the following |
| optional properties: |
| </p> |
| <dl compact="compact"> |
| <dt><code>backtrace_barrier</code></dt> |
| <dd><p>Boolean (default = false). If true, error backtraces do not list the |
| stack frames below the evalScript. |
| </p></dd> |
| </dl> |
| |
| </dd> |
| <dt><code>loadScript(filename)</code></dt> |
| <dd><p>Evaluate the file <code>filename</code> as a script (global eval). |
| </p> |
| </dd> |
| <dt><code>loadFile(filename)</code></dt> |
| <dd><p>Load the file <code>filename</code> and return it as a string assuming UTF-8 |
| encoding. Return <code>null</code> in case of I/O error. |
| </p> |
| </dd> |
| <dt><code>open(filename, flags, errorObj = undefined)</code></dt> |
| <dd><p>Open a file (wrapper to the libc <code>fopen()</code>). Return the FILE |
| object or <code>null</code> in case of I/O error. If <code>errorObj</code> is not |
| undefined, set its <code>errno</code> property to the error code or to 0 if |
| no error occured. |
| </p> |
| </dd> |
| <dt><code>popen(command, flags, errorObj = undefined)</code></dt> |
| <dd><p>Open a process by creating a pipe (wrapper to the libc |
| <code>popen()</code>). Return the FILE |
| object or <code>null</code> in case of I/O error. If <code>errorObj</code> is not |
| undefined, set its <code>errno</code> property to the error code or to 0 if |
| no error occured. |
| </p> |
| </dd> |
| <dt><code>fdopen(fd, flags, errorObj = undefined)</code></dt> |
| <dd><p>Open a file from a file handle (wrapper to the libc |
| <code>fdopen()</code>). Return the FILE |
| object or <code>null</code> in case of I/O error. If <code>errorObj</code> is not |
| undefined, set its <code>errno</code> property to the error code or to 0 if |
| no error occured. |
| </p> |
| </dd> |
| <dt><code>tmpfile(errorObj = undefined)</code></dt> |
| <dd><p>Open a temporary file. Return the FILE |
| object or <code>null</code> in case of I/O error. If <code>errorObj</code> is not |
| undefined, set its <code>errno</code> property to the error code or to 0 if |
| no error occured. |
| </p> |
| </dd> |
| <dt><code>puts(str)</code></dt> |
| <dd><p>Equivalent to <code>std.out.puts(str)</code>. |
| </p> |
| </dd> |
| <dt><code>printf(fmt, ...args)</code></dt> |
| <dd><p>Equivalent to <code>std.out.printf(fmt, ...args)</code>. |
| </p> |
| </dd> |
| <dt><code>sprintf(fmt, ...args)</code></dt> |
| <dd><p>Equivalent to the libc sprintf(). |
| </p> |
| </dd> |
| <dt><code>in</code></dt> |
| <dt><code>out</code></dt> |
| <dt><code>err</code></dt> |
| <dd><p>Wrappers to the libc file <code>stdin</code>, <code>stdout</code>, <code>stderr</code>. |
| </p> |
| </dd> |
| <dt><code>SEEK_SET</code></dt> |
| <dt><code>SEEK_CUR</code></dt> |
| <dt><code>SEEK_END</code></dt> |
| <dd><p>Constants for seek(). |
| </p> |
| </dd> |
| <dt><code>Error</code></dt> |
| <dd> |
| <p>Enumeration object containing the integer value of common errors |
| (additional error codes may be defined): |
| </p> |
| <dl compact="compact"> |
| <dt><code>EINVAL</code></dt> |
| <dt><code>EIO</code></dt> |
| <dt><code>EACCES</code></dt> |
| <dt><code>EEXIST</code></dt> |
| <dt><code>ENOSPC</code></dt> |
| <dt><code>ENOSYS</code></dt> |
| <dt><code>EBUSY</code></dt> |
| <dt><code>ENOENT</code></dt> |
| <dt><code>EPERM</code></dt> |
| <dt><code>EPIPE</code></dt> |
| </dl> |
| |
| </dd> |
| <dt><code>strerror(errno)</code></dt> |
| <dd><p>Return a string that describes the error <code>errno</code>. |
| </p> |
| </dd> |
| <dt><code>gc()</code></dt> |
| <dd><p>Manually invoke the cycle removal algorithm. The cycle removal |
| algorithm is automatically started when needed, so this function is |
| useful in case of specific memory constraints or for testing. |
| </p> |
| </dd> |
| <dt><code>getenv(name)</code></dt> |
| <dd><p>Return the value of the environment variable <code>name</code> or |
| <code>undefined</code> if it is not defined. |
| </p> |
| </dd> |
| <dt><code>urlGet(url, options = undefined)</code></dt> |
| <dd> |
| <p>Download <code>url</code> using the <samp>curl</samp> command line |
| utility. <code>options</code> is an optional object containing the following |
| optional properties: |
| </p> |
| <dl compact="compact"> |
| <dt><code>binary</code></dt> |
| <dd><p>Boolean (default = false). If true, the response is an ArrayBuffer |
| instead of a string. When a string is returned, the data is assumed |
| to be UTF-8 encoded. |
| </p> |
| </dd> |
| <dt><code>full</code></dt> |
| <dd> |
| <p>Boolean (default = false). If true, return the an object contains |
| the properties <code>response</code> (response content), |
| <code>responseHeaders</code> (headers separated by CRLF), <code>status</code> |
| (status code). <code>response</code> is <code>null</code> is case of protocol or |
| network error. If <code>full</code> is false, only the response is |
| returned if the status is between 200 and 299. Otherwise <code>null</code> |
| is returned. |
| </p> |
| </dd> |
| </dl> |
| |
| </dd> |
| <dt><code>parseExtJSON(str)</code></dt> |
| <dd> |
| <p>Parse <code>str</code> using a superset of <code>JSON.parse</code>. The |
| following extensions are accepted: |
| </p> |
| <ul> |
| <li> Single line and multiline comments |
| </li><li> unquoted properties (ASCII-only Javascript identifiers) |
| </li><li> trailing comma in array and object definitions |
| </li><li> single quoted strings |
| </li><li> <code>\f</code> and <code>\v</code> are accepted as space characters |
| </li><li> leading plus in numbers |
| </li><li> octal (<code>0o</code> prefix) and hexadecimal (<code>0x</code> prefix) numbers |
| </li></ul> |
| </dd> |
| </dl> |
| |
| <p>FILE prototype: |
| </p> |
| <dl compact="compact"> |
| <dt><code>close()</code></dt> |
| <dd><p>Close the file. Return 0 if OK or <code>-errno</code> in case of I/O error. |
| </p></dd> |
| <dt><code>puts(str)</code></dt> |
| <dd><p>Outputs the string with the UTF-8 encoding. |
| </p></dd> |
| <dt><code>printf(fmt, ...args)</code></dt> |
| <dd><p>Formatted printf. |
| </p> |
| <p>The same formats as the standard C library <code>printf</code> are |
| supported. Integer format types (e.g. <code>%d</code>) truncate the Numbers |
| or BigInts to 32 bits. Use the <code>l</code> modifier (e.g. <code>%ld</code>) to |
| truncate to 64 bits. |
| </p> |
| </dd> |
| <dt><code>flush()</code></dt> |
| <dd><p>Flush the buffered file. |
| </p></dd> |
| <dt><code>seek(offset, whence)</code></dt> |
| <dd><p>Seek to a give file position (whence is |
| <code>std.SEEK_*</code>). <code>offset</code> can be a number or a bigint. Return |
| 0 if OK or <code>-errno</code> in case of I/O error. |
| </p></dd> |
| <dt><code>tell()</code></dt> |
| <dd><p>Return the current file position. |
| </p></dd> |
| <dt><code>tello()</code></dt> |
| <dd><p>Return the current file position as a bigint. |
| </p></dd> |
| <dt><code>eof()</code></dt> |
| <dd><p>Return true if end of file. |
| </p></dd> |
| <dt><code>fileno()</code></dt> |
| <dd><p>Return the associated OS handle. |
| </p></dd> |
| <dt><code>error()</code></dt> |
| <dd><p>Return true if there was an error. |
| </p></dd> |
| <dt><code>clearerr()</code></dt> |
| <dd><p>Clear the error indication. |
| </p> |
| </dd> |
| <dt><code>read(buffer, position, length)</code></dt> |
| <dd><p>Read <code>length</code> bytes from the file to the ArrayBuffer <code>buffer</code> at byte |
| position <code>position</code> (wrapper to the libc <code>fread</code>). |
| </p> |
| </dd> |
| <dt><code>write(buffer, position, length)</code></dt> |
| <dd><p>Write <code>length</code> bytes to the file from the ArrayBuffer <code>buffer</code> at byte |
| position <code>position</code> (wrapper to the libc <code>fread</code>). |
| </p> |
| </dd> |
| <dt><code>getline()</code></dt> |
| <dd><p>Return the next line from the file, assuming UTF-8 encoding, excluding |
| the trailing line feed. |
| </p> |
| </dd> |
| <dt><code>readAsString(max_size = undefined)</code></dt> |
| <dd><p>Read <code>max_size</code> bytes from the file and return them as a string |
| assuming UTF-8 encoding. If <code>max_size</code> is not present, the file |
| is read up its end. |
| </p> |
| </dd> |
| <dt><code>getByte()</code></dt> |
| <dd><p>Return the next byte from the file. Return -1 if the end of file is reached. |
| </p> |
| </dd> |
| <dt><code>putByte(c)</code></dt> |
| <dd><p>Write one byte to the file. |
| </p></dd> |
| </dl> |
| |
| <a name="os-module"></a> |
| <h4 class="subsection">3.3.3 <code>os</code> module</h4> |
| |
| <p>The <code>os</code> module provides Operating System specific functions: |
| </p> |
| <ul> |
| <li> low level file access |
| </li><li> signals |
| </li><li> timers |
| </li><li> asynchronous I/O |
| </li><li> workers (threads) |
| </li></ul> |
| |
| <p>The OS functions usually return 0 if OK or an OS specific negative |
| error code. |
| </p> |
| <p>Available exports: |
| </p> |
| <dl compact="compact"> |
| <dt><code>open(filename, flags, mode = 0o666)</code></dt> |
| <dd><p>Open a file. Return a handle or < 0 if error. |
| </p> |
| </dd> |
| <dt><code>O_RDONLY</code></dt> |
| <dt><code>O_WRONLY</code></dt> |
| <dt><code>O_RDWR</code></dt> |
| <dt><code>O_APPEND</code></dt> |
| <dt><code>O_CREAT</code></dt> |
| <dt><code>O_EXCL</code></dt> |
| <dt><code>O_TRUNC</code></dt> |
| <dd><p>POSIX open flags. |
| </p> |
| </dd> |
| <dt><code>O_TEXT</code></dt> |
| <dd><p>(Windows specific). Open the file in text mode. The default is binary mode. |
| </p> |
| </dd> |
| <dt><code>close(fd)</code></dt> |
| <dd><p>Close the file handle <code>fd</code>. |
| </p> |
| </dd> |
| <dt><code>seek(fd, offset, whence)</code></dt> |
| <dd><p>Seek in the file. Use <code>std.SEEK_*</code> for |
| <code>whence</code>. <code>offset</code> is either a number or a bigint. If |
| <code>offset</code> is a bigint, a bigint is returned too. |
| </p> |
| </dd> |
| <dt><code>read(fd, buffer, offset, length)</code></dt> |
| <dd><p>Read <code>length</code> bytes from the file handle <code>fd</code> to the |
| ArrayBuffer <code>buffer</code> at byte position <code>offset</code>. |
| Return the number of read bytes or < 0 if error. |
| </p> |
| </dd> |
| <dt><code>write(fd, buffer, offset, length)</code></dt> |
| <dd><p>Write <code>length</code> bytes to the file handle <code>fd</code> from the |
| ArrayBuffer <code>buffer</code> at byte position <code>offset</code>. |
| Return the number of written bytes or < 0 if error. |
| </p> |
| </dd> |
| <dt><code>isatty(fd)</code></dt> |
| <dd><p>Return <code>true</code> is <code>fd</code> is a TTY (terminal) handle. |
| </p> |
| </dd> |
| <dt><code>ttyGetWinSize(fd)</code></dt> |
| <dd><p>Return the TTY size as <code>[width, height]</code> or <code>null</code> if not available. |
| </p> |
| </dd> |
| <dt><code>ttySetRaw(fd)</code></dt> |
| <dd><p>Set the TTY in raw mode. |
| </p> |
| </dd> |
| <dt><code>remove(filename)</code></dt> |
| <dd><p>Remove a file. Return 0 if OK or <code>-errno</code>. |
| </p> |
| </dd> |
| <dt><code>rename(oldname, newname)</code></dt> |
| <dd><p>Rename a file. Return 0 if OK or <code>-errno</code>. |
| </p> |
| </dd> |
| <dt><code>realpath(path)</code></dt> |
| <dd><p>Return <code>[str, err]</code> where <code>str</code> is the canonicalized absolute |
| pathname of <code>path</code> and <code>err</code> the error code. |
| </p> |
| </dd> |
| <dt><code>getcwd()</code></dt> |
| <dd><p>Return <code>[str, err]</code> where <code>str</code> is the current working directory |
| and <code>err</code> the error code. |
| </p> |
| </dd> |
| <dt><code>chdir(path)</code></dt> |
| <dd><p>Change the current directory. Return 0 if OK or <code>-errno</code>. |
| </p> |
| </dd> |
| <dt><code>mkdir(path, mode = 0o777)</code></dt> |
| <dd><p>Create a directory at <code>path</code>. Return 0 if OK or <code>-errno</code>. |
| </p> |
| </dd> |
| <dt><code>stat(path)</code></dt> |
| <dt><code>lstat(path)</code></dt> |
| <dd> |
| <p>Return <code>[obj, err]</code> where <code>obj</code> is an object containing the |
| file status of <code>path</code>. <code>err</code> is the error code. The |
| following fields are defined in <code>obj</code>: dev, ino, mode, nlink, |
| uid, gid, rdev, size, blocks, atime, mtime, ctime. The times are |
| specified in milliseconds since 1970. <code>lstat()</code> is the same as |
| <code>stat()</code> excepts that it returns information about the link |
| itself. |
| </p> |
| </dd> |
| <dt><code>S_IFMT</code></dt> |
| <dt><code>S_IFIFO</code></dt> |
| <dt><code>S_IFCHR</code></dt> |
| <dt><code>S_IFDIR</code></dt> |
| <dt><code>S_IFBLK</code></dt> |
| <dt><code>S_IFREG</code></dt> |
| <dt><code>S_IFSOCK</code></dt> |
| <dt><code>S_IFLNK</code></dt> |
| <dt><code>S_ISGID</code></dt> |
| <dt><code>S_ISUID</code></dt> |
| <dd><p>Constants to interpret the <code>mode</code> property returned by |
| <code>stat()</code>. They have the same value as in the C system header |
| <samp>sys/stat.h</samp>. |
| </p> |
| </dd> |
| <dt><code>utimes(path, atime, mtime)</code></dt> |
| <dd><p>Change the access and modification times of the file <code>path</code>. The |
| times are specified in milliseconds since 1970. Return 0 if OK or <code>-errno</code>. |
| </p> |
| </dd> |
| <dt><code>symlink(target, linkpath)</code></dt> |
| <dd><p>Create a link at <code>linkpath</code> containing the string <code>target</code>. Return 0 if OK or <code>-errno</code>. |
| </p> |
| </dd> |
| <dt><code>readlink(path)</code></dt> |
| <dd><p>Return <code>[str, err]</code> where <code>str</code> is the link target and <code>err</code> |
| the error code. |
| </p> |
| </dd> |
| <dt><code>readdir(path)</code></dt> |
| <dd><p>Return <code>[array, err]</code> where <code>array</code> is an array of strings |
| containing the filenames of the directory <code>path</code>. <code>err</code> is |
| the error code. |
| </p> |
| </dd> |
| <dt><code>setReadHandler(fd, func)</code></dt> |
| <dd><p>Add a read handler to the file handle <code>fd</code>. <code>func</code> is called |
| each time there is data pending for <code>fd</code>. A single read handler |
| per file handle is supported. Use <code>func = null</code> to remove the |
| handler. |
| </p> |
| </dd> |
| <dt><code>setWriteHandler(fd, func)</code></dt> |
| <dd><p>Add a write handler to the file handle <code>fd</code>. <code>func</code> is |
| called each time data can be written to <code>fd</code>. A single write |
| handler per file handle is supported. Use <code>func = null</code> to remove |
| the handler. |
| </p> |
| </dd> |
| <dt><code>signal(signal, func)</code></dt> |
| <dd><p>Call the function <code>func</code> when the signal <code>signal</code> |
| happens. Only a single handler per signal number is supported. Use |
| <code>null</code> to set the default handler or <code>undefined</code> to ignore |
| the signal. Signal handlers can only be defined in the main thread. |
| </p> |
| </dd> |
| <dt><code>SIGINT</code></dt> |
| <dt><code>SIGABRT</code></dt> |
| <dt><code>SIGFPE</code></dt> |
| <dt><code>SIGILL</code></dt> |
| <dt><code>SIGSEGV</code></dt> |
| <dt><code>SIGTERM</code></dt> |
| <dd><p>POSIX signal numbers. |
| </p> |
| </dd> |
| <dt><code>kill(pid, sig)</code></dt> |
| <dd><p>Send the signal <code>sig</code> to the process <code>pid</code>. |
| </p> |
| </dd> |
| <dt><code>exec(args[, options])</code></dt> |
| <dd><p>Execute a process with the arguments <code>args</code>. <code>options</code> is an |
| object containing optional parameters: |
| </p> |
| <dl compact="compact"> |
| <dt><code>block</code></dt> |
| <dd><p>Boolean (default = true). If true, wait until the process is |
| terminated. In this case, <code>exec</code> return the exit code if positive |
| or the negated signal number if the process was interrupted by a |
| signal. If false, do not block and return the process id of the child. |
| </p> |
| </dd> |
| <dt><code>usePath</code></dt> |
| <dd><p>Boolean (default = true). If true, the file is searched in the |
| <code>PATH</code> environment variable. |
| </p> |
| </dd> |
| <dt><code>file</code></dt> |
| <dd><p>String (default = <code>args[0]</code>). Set the file to be executed. |
| </p> |
| </dd> |
| <dt><code>cwd</code></dt> |
| <dd><p>String. If present, set the working directory of the new process. |
| </p> |
| </dd> |
| <dt><code>stdin</code></dt> |
| <dt><code>stdout</code></dt> |
| <dt><code>stderr</code></dt> |
| <dd><p>If present, set the handle in the child for stdin, stdout or stderr. |
| </p> |
| </dd> |
| <dt><code>env</code></dt> |
| <dd><p>Object. If present, set the process environment from the object |
| key-value pairs. Otherwise use the same environment as the current |
| process. |
| </p> |
| </dd> |
| <dt><code>uid</code></dt> |
| <dd><p>Integer. If present, the process uid with <code>setuid</code>. |
| </p> |
| </dd> |
| <dt><code>gid</code></dt> |
| <dd><p>Integer. If present, the process gid with <code>setgid</code>. |
| </p> |
| </dd> |
| </dl> |
| |
| </dd> |
| <dt><code>waitpid(pid, options)</code></dt> |
| <dd><p><code>waitpid</code> Unix system call. Return the array <code>[ret, |
| status]</code>. <code>ret</code> contains <code>-errno</code> in case of error. |
| </p> |
| </dd> |
| <dt><code>WNOHANG</code></dt> |
| <dd><p>Constant for the <code>options</code> argument of <code>waitpid</code>. |
| </p> |
| </dd> |
| <dt><code>dup(fd)</code></dt> |
| <dd><p><code>dup</code> Unix system call. |
| </p> |
| </dd> |
| <dt><code>dup2(oldfd, newfd)</code></dt> |
| <dd><p><code>dup2</code> Unix system call. |
| </p> |
| </dd> |
| <dt><code>pipe()</code></dt> |
| <dd><p><code>pipe</code> Unix system call. Return two handles as <code>[read_fd, |
| write_fd]</code> or null in case of error. |
| </p> |
| </dd> |
| <dt><code>sleep(delay_ms)</code></dt> |
| <dd><p>Sleep during <code>delay_ms</code> milliseconds. |
| </p> |
| </dd> |
| <dt><code>setTimeout(func, delay)</code></dt> |
| <dd><p>Call the function <code>func</code> after <code>delay</code> ms. Return a handle |
| to the timer. |
| </p> |
| </dd> |
| <dt><code>clearTimeout(handle)</code></dt> |
| <dd><p>Cancel a timer. |
| </p> |
| </dd> |
| <dt><code>platform</code></dt> |
| <dd><p>Return a string representing the platform: <code>"linux"</code>, <code>"darwin"</code>, |
| <code>"win32"</code> or <code>"js"</code>. |
| </p> |
| </dd> |
| <dt><code>Worker(module_filename)</code></dt> |
| <dd><p>Constructor to create a new thread (worker) with an API close to the |
| <code>WebWorkers</code>. <code>module_filename</code> is a string specifying the |
| module filename which is executed in the newly created thread. As for |
| dynamically imported module, it is relative to the current script or |
| module path. Threads normally don’t share any data and communicate |
| between each other with messages. Nested workers are not supported. An |
| example is available in <samp>tests/test_worker.js</samp>. |
| </p> |
| <p>The worker class has the following static properties: |
| </p> |
| <dl compact="compact"> |
| <dt><code>parent</code></dt> |
| <dd><p>In the created worker, <code>Worker.parent</code> represents the parent |
| worker and is used to send or receive messages. |
| </p></dd> |
| </dl> |
| |
| <p>The worker instances have the following properties: |
| </p> |
| <dl compact="compact"> |
| <dt><code>postMessage(msg)</code></dt> |
| <dd> |
| <p>Send a message to the corresponding worker. <code>msg</code> is cloned in |
| the destination worker using an algorithm similar to the <code>HTML</code> |
| structured clone algorithm. <code>SharedArrayBuffer</code> are shared |
| between workers. |
| </p> |
| <p>Current limitations: <code>Map</code> and <code>Set</code> are not supported |
| yet. |
| </p> |
| </dd> |
| <dt><code>onmessage</code></dt> |
| <dd> |
| <p>Getter and setter. Set a function which is called each time a |
| message is received. The function is called with a single |
| argument. It is an object with a <code>data</code> property containing the |
| received message. The thread is not terminated if there is at least |
| one non <code>null</code> <code>onmessage</code> handler. |
| </p> |
| </dd> |
| </dl> |
| |
| </dd> |
| </dl> |
| |
| <a name="QuickJS-C-API"></a> |
| <h3 class="section">3.4 QuickJS C API</h3> |
| |
| <p>The C API was designed to be simple and efficient. The C API is |
| defined in the header <code>quickjs.h</code>. |
| </p> |
| <a name="Runtime-and-contexts"></a> |
| <h4 class="subsection">3.4.1 Runtime and contexts</h4> |
| |
| <p><code>JSRuntime</code> represents a Javascript runtime corresponding to an |
| object heap. Several runtimes can exist at the same time but they |
| cannot exchange objects. Inside a given runtime, no multi-threading is |
| supported. |
| </p> |
| <p><code>JSContext</code> represents a Javascript context (or Realm). Each |
| JSContext has its own global objects and system objects. There can be |
| several JSContexts per JSRuntime and they can share objects, similar |
| to frames of the same origin sharing Javascript objects in a |
| web browser. |
| </p> |
| <a name="JSValue"></a> |
| <h4 class="subsection">3.4.2 JSValue</h4> |
| |
| <p><code>JSValue</code> represents a Javascript value which can be a primitive |
| type or an object. Reference counting is used, so it is important to |
| explicitly duplicate (<code>JS_DupValue()</code>, increment the reference |
| count) or free (<code>JS_FreeValue()</code>, decrement the reference count) |
| JSValues. |
| </p> |
| <a name="C-functions"></a> |
| <h4 class="subsection">3.4.3 C functions</h4> |
| |
| <p>C functions can be created with |
| <code>JS_NewCFunction()</code>. <code>JS_SetPropertyFunctionList()</code> is a |
| shortcut to easily add functions, setters and getters properties to a |
| given object. |
| </p> |
| <p>Unlike other embedded Javascript engines, there is no implicit stack, |
| so C functions get their parameters as normal C parameters. As a |
| general rule, C functions take constant <code>JSValue</code>s as parameters |
| (so they don’t need to free them) and return a newly allocated (=live) |
| <code>JSValue</code>. |
| </p> |
| <a name="Exceptions"></a> |
| <h4 class="subsection">3.4.4 Exceptions</h4> |
| |
| <p>Exceptions: most C functions can return a Javascript exception. It |
| must be explicitly tested and handled by the C code. The specific |
| <code>JSValue</code> <code>JS_EXCEPTION</code> indicates that an exception |
| occurred. The actual exception object is stored in the |
| <code>JSContext</code> and can be retrieved with <code>JS_GetException()</code>. |
| </p> |
| <a name="Script-evaluation"></a> |
| <h4 class="subsection">3.4.5 Script evaluation</h4> |
| |
| <p>Use <code>JS_Eval()</code> to evaluate a script or module source. |
| </p> |
| <p>If the script or module was compiled to bytecode with <code>qjsc</code>, it |
| can be evaluated by calling <code>js_std_eval_binary()</code>. The advantage |
| is that no compilation is needed so it is faster and smaller because |
| the compiler can be removed from the executable if no <code>eval</code> is |
| required. |
| </p> |
| <p>Note: the bytecode format is linked to a given QuickJS |
| version. Moreover, no security check is done before its |
| execution. Hence the bytecode should not be loaded from untrusted |
| sources. That’s why there is no option to output the bytecode to a |
| binary file in <code>qjsc</code>. |
| </p> |
| <a name="JS-Classes"></a> |
| <h4 class="subsection">3.4.6 JS Classes</h4> |
| |
| <p>C opaque data can be attached to a Javascript object. The type of the |
| C opaque data is determined with the class ID (<code>JSClassID</code>) of |
| the object. Hence the first step is to register a new class ID and JS |
| class (<code>JS_NewClassID()</code>, <code>JS_NewClass()</code>). Then you can |
| create objects of this class with <code>JS_NewObjectClass()</code> and get or |
| set the C opaque point with |
| <code>JS_GetOpaque()</code>/<code>JS_SetOpaque()</code>. |
| </p> |
| <p>When defining a new JS class, it is possible to declare a finalizer |
| which is called when the object is destroyed. A <code>gc_mark</code> method |
| can be provided so that the cycle removal algorithm can find the other |
| objects referenced by this object. Other methods are available to |
| define exotic object behaviors. |
| </p> |
| <p>The Class ID are globally allocated (i.e. for all runtimes). The |
| JSClass are allocated per <code>JSRuntime</code>. <code>JS_SetClassProto()</code> |
| is used to define a prototype for a given class in a given |
| JSContext. <code>JS_NewObjectClass()</code> sets this prototype in the |
| created object. |
| </p> |
| <p>Examples are available in <samp>quickjs-libc.c</samp>. |
| </p> |
| <a name="C-Modules"></a> |
| <h4 class="subsection">3.4.7 C Modules</h4> |
| |
| <p>Native ES6 modules are supported and can be dynamically or statically |
| linked. Look at the <samp>test_bjson</samp> and <samp>bjson.so</samp> |
| examples. The standard library <samp>quickjs-libc.c</samp> is also a good example |
| of a native module. |
| </p> |
| <a name="Memory-handling"></a> |
| <h4 class="subsection">3.4.8 Memory handling</h4> |
| |
| <p>Use <code>JS_SetMemoryLimit()</code> to set a global memory allocation limit |
| to a given JSRuntime. |
| </p> |
| <p>Custom memory allocation functions can be provided with |
| <code>JS_NewRuntime2()</code>. |
| </p> |
| <p>The maximum system stack size can be set with <code>JS_SetMaxStackSize()</code>. |
| </p> |
| <a name="Execution-timeout-and-interrupts"></a> |
| <h4 class="subsection">3.4.9 Execution timeout and interrupts</h4> |
| |
| <p>Use <code>JS_SetInterruptHandler()</code> to set a callback which is |
| regularly called by the engine when it is executing code. This |
| callback can be used to implement an execution timeout. |
| </p> |
| <p>It is used by the command line interpreter to implement a |
| <code>Ctrl-C</code> handler. |
| </p> |
| <a name="Internals"></a> |
| <h2 class="chapter">4 Internals</h2> |
| |
| <a name="Bytecode"></a> |
| <h3 class="section">4.1 Bytecode</h3> |
| |
| <p>The compiler generates bytecode directly with no intermediate |
| representation such as a parse tree, hence it is very fast. Several |
| optimizations passes are done over the generated bytecode. |
| </p> |
| <p>A stack-based bytecode was chosen because it is simple and generates |
| compact code. |
| </p> |
| <p>For each function, the maximum stack size is computed at compile time so that |
| no runtime stack overflow tests are needed. |
| </p> |
| <p>A separate compressed line number table is maintained for the debug |
| information. |
| </p> |
| <p>Access to closure variables is optimized and is almost as fast as local |
| variables. |
| </p> |
| <p>Direct <code>eval</code> in strict mode is optimized. |
| </p> |
| <a name="Executable-generation"></a> |
| <h3 class="section">4.2 Executable generation</h3> |
| |
| <a name="qjsc-compiler-1"></a> |
| <h4 class="subsection">4.2.1 <code>qjsc</code> compiler</h4> |
| |
| <p>The <code>qjsc</code> compiler generates C sources from Javascript files. By |
| default the C sources are compiled with the system compiler |
| (<code>gcc</code> or <code>clang</code>). |
| </p> |
| <p>The generated C source contains the bytecode of the compiled functions |
| or modules. If a full complete executable is needed, it also |
| contains a <code>main()</code> function with the necessary C code to initialize the |
| Javascript engine and to load and execute the compiled functions and |
| modules. |
| </p> |
| <p>Javascript code can be mixed with C modules. |
| </p> |
| <p>In order to have smaller executables, specific Javascript features can |
| be disabled, in particular <code>eval</code> or the regular expressions. The |
| code removal relies on the Link Time Optimization of the system |
| compiler. |
| </p> |
| <a name="Binary-JSON"></a> |
| <h4 class="subsection">4.2.2 Binary JSON</h4> |
| |
| <p><code>qjsc</code> works by compiling scripts or modules and then serializing |
| them to a binary format. A subset of this format (without functions or |
| modules) can be used as binary JSON. The example <samp>test_bjson.js</samp> |
| shows how to use it. |
| </p> |
| <p>Warning: the binary JSON format may change without notice, so it |
| should not be used to store persistent data. The <samp>test_bjson.js</samp> |
| example is only used to test the binary object format functions. |
| </p> |
| <a name="Runtime"></a> |
| <h3 class="section">4.3 Runtime</h3> |
| |
| <a name="Strings"></a> |
| <h4 class="subsection">4.3.1 Strings</h4> |
| |
| <p>Strings are stored either as an 8 bit or a 16 bit array of |
| characters. Hence random access to characters is always fast. |
| </p> |
| <p>The C API provides functions to convert Javascript Strings to C UTF-8 encoded |
| strings. The most common case where the Javascript string contains |
| only ASCII characters involves no copying. |
| </p> |
| <a name="Objects"></a> |
| <h4 class="subsection">4.3.2 Objects</h4> |
| |
| <p>The object shapes (object prototype, property names and flags) are shared |
| between objects to save memory. |
| </p> |
| <p>Arrays with no holes (except at the end of the array) are optimized. |
| </p> |
| <p>TypedArray accesses are optimized. |
| </p> |
| <a name="Atoms"></a> |
| <h4 class="subsection">4.3.3 Atoms</h4> |
| |
| <p>Object property names and some strings are stored as Atoms (unique |
| strings) to save memory and allow fast comparison. Atoms are |
| represented as a 32 bit integer. Half of the atom range is reserved for |
| immediate integer literals from <em>0</em> to <em>2^{31}-1</em>. |
| </p> |
| <a name="Numbers"></a> |
| <h4 class="subsection">4.3.4 Numbers</h4> |
| |
| <p>Numbers are represented either as 32-bit signed integers or 64-bit IEEE-754 |
| floating point values. Most operations have fast paths for the 32-bit |
| integer case. |
| </p> |
| <a name="Garbage-collection"></a> |
| <h4 class="subsection">4.3.5 Garbage collection</h4> |
| |
| <p>Reference counting is used to free objects automatically and |
| deterministically. A separate cycle removal pass is done when the allocated |
| memory becomes too large. The cycle removal algorithm only uses the |
| reference counts and the object content, so no explicit garbage |
| collection roots need to be manipulated in the C code. |
| </p> |
| <a name="JSValue-1"></a> |
| <h4 class="subsection">4.3.6 JSValue</h4> |
| |
| <p>It is a Javascript value which can be a primitive type (such as |
| Number, String, ...) or an Object. NaN boxing is used in the 32-bit version |
| to store 64-bit floating point numbers. The representation is |
| optimized so that 32-bit integers and reference counted values can be |
| efficiently tested. |
| </p> |
| <p>In 64-bit code, JSValue are 128-bit large and no NaN boxing is used. The |
| rationale is that in 64-bit code memory usage is less critical. |
| </p> |
| <p>In both cases (32 or 64 bits), JSValue exactly fits two CPU registers, |
| so it can be efficiently returned by C functions. |
| </p> |
| <a name="Function-call"></a> |
| <h4 class="subsection">4.3.7 Function call</h4> |
| |
| <p>The engine is optimized so that function calls are fast. The system |
| stack holds the Javascript parameters and local variables. |
| </p> |
| <a name="RegExp"></a> |
| <h3 class="section">4.4 RegExp</h3> |
| |
| <p>A specific regular expression engine was developed. It is both small |
| and efficient and supports all the ES2020 features including the |
| Unicode properties. As the Javascript compiler, it directly generates |
| bytecode without a parse tree. |
| </p> |
| <p>Backtracking with an explicit stack is used so that there is no |
| recursion on the system stack. Simple quantifiers are specifically |
| optimized to avoid recursions. |
| </p> |
| <p>Infinite recursions coming from quantifiers with empty terms are |
| avoided. |
| </p> |
| <p>The full regexp library weights about 15 KiB (x86 code), excluding the |
| Unicode library. |
| </p> |
| <a name="Unicode"></a> |
| <h3 class="section">4.5 Unicode</h3> |
| |
| <p>A specific Unicode library was developed so that there is no |
| dependency on an external large Unicode library such as ICU. All the |
| Unicode tables are compressed while keeping a reasonable access |
| speed. |
| </p> |
| <p>The library supports case conversion, Unicode normalization, Unicode |
| script queries, Unicode general category queries and all Unicode |
| binary properties. |
| </p> |
| <p>The full Unicode library weights about 45 KiB (x86 code). |
| </p> |
| <a name="BigInt_002c-BigFloat_002c-BigDecimal"></a> |
| <h3 class="section">4.6 BigInt, BigFloat, BigDecimal</h3> |
| |
| <p>BigInt, BigFloat and BigDecimal are implemented with the <code>libbf</code> |
| library<a name="DOCF7" href="#FOOT7"><sup>7</sup></a>. It weights about 90 |
| KiB (x86 code) and provides arbitrary precision IEEE 754 floating |
| point operations and transcendental functions with exact rounding. |
| </p> |
| <a name="License"></a> |
| <h2 class="chapter">5 License</h2> |
| |
| <p>QuickJS is released under the MIT license. |
| </p> |
| <p>Unless otherwise specified, the QuickJS sources are copyright Fabrice |
| Bellard and Charlie Gordon. |
| </p> |
| <div class="footnote"> |
| <hr> |
| <h4 class="footnotes-heading">Footnotes</h4> |
| |
| <h3><a name="FOOT1" href="#DOCF1">(1)</a></h3> |
| <p><a href="https://tc39.es/ecma262/">https://tc39.es/ecma262/</a></p> |
| <h3><a name="FOOT2" href="#DOCF2">(2)</a></h3> |
| <p><a href="https://github.com/tc39/test262">https://github.com/tc39/test262</a></p> |
| <h3><a name="FOOT3" href="#DOCF3">(3)</a></h3> |
| <p><a href="https://tc39.github.io/ecma262/">https://tc39.github.io/ecma262/</a></p> |
| <h3><a name="FOOT4" href="#DOCF4">(4)</a></h3> |
| <p>The old |
| ES5.1 tests can be extracted with <code>git clone --single-branch |
| --branch es5-tests https://github.com/tc39/test262.git test262o</code></p> |
| <h3><a name="FOOT5" href="#DOCF5">(5)</a></h3> |
| <p><a href="https://github.com/bterlson/test262-harness">https://github.com/bterlson/test262-harness</a></p> |
| <h3><a name="FOOT6" href="#DOCF6">(6)</a></h3> |
| <p>We believe the current specification of tails calls is too complicated and presents limited practical interests.</p> |
| <h3><a name="FOOT7" href="#DOCF7">(7)</a></h3> |
| <p><a href="https://bellard.org/libbf">https://bellard.org/libbf</a></p> |
| </div> |
| <hr> |
| |
| |
| |
| </body> |
| </html> |