• Home
• Download
• API
• Guide
• Wiki
• REPL

• Introduction
• Getting started
• Programming model
• Stack types
• API C types
• Type algorithms
• Duktape built-ins
• Post-ES5 features
• Custom behavior
• Custom JSON formats
• Custom directives
• Buffer objects
• Error objects
• Function objects
• Date and time
• Random numbers
• Debugger
• Modules
• Logging
• Finalization
• Coroutines
• Virtual properties
• Symbols
• Bytecode dump/load
• Threading
• Sandboxing
• Performance
• Memory usage
• Compiling
• Portability
• Compatibility
• Versioning
• Limitations
• Comparison to Lua

Introduction§

Version: 2.6.0(2020-10-13)

Document scope§

This guide provides an introduction to using Duktape in your programs.Once you're familiar with the basics, there is a conciseAPI reference for looking up API details. TheDuktape Wiki provides more detailedexamples and best practices.

This document doesn't cover Duktape internals, see theDuktape repoif you wish to tinker with them.

What is Duktape?§

Duktape is an embeddable ECMAScript® engine with a focus on portabilityand compact footprint. By integrating Duktape into your C/C++ program youcan easily extend its functionality through scripting. You can also buildthe main control flow of your program in ECMAScript and use fast C codefunctions to do heavy lifting.

Embeddability means that Duktape makes minimal assumptions about theunderlying platform and its capabilities; instead, the application whichembeds Duktape is in control of which native bindings are provided andin what manner. For example, there are no default bindings for printingtext to the console or to interact with the file system. Duktapedistributable package includes example providers which you can easilyintegrate if they suit your needs.

The terms ECMAScript and Javascript are often considered more or lessequivalent, although Javascript and its variants are technically just oneenvironment where the ECMAScript language is used. The line between thetwo is not very clear in practice: even non-browser ECMAScript environmentsoften provide some browser-specific built-ins. Even so, we use the termECMAScript throughout to refer to the language implemented by Duktape.

Conformance§

Duktape conforms to ES5.0/ES5.1 with semantics updated from ES2015 orlater where appropriate:

• ECMAScript Language Specification 5th Edition
• ECMAScript® Language Specification 5.1 Edition

Duktape tracks the latest ECMAScript specification for semantics andbuilt-ins (however support for ES2015 and later is still incomplete), see:

• ECMAScript® 2015 Language Specification
• ECMAScript® 2016 Language Specification

In some specific cases Duktape may follow a specification draft,see work in progress inTC39/ecma262.This is done when a feature in the latest specifications conflictswith real world code (see e.g.RegExp.prototype issues).

TypedArray support is based on ES2016 TypedArray; initial implementationwas based on Khronos TypedArray specification:

• Typed Array Specification (Editor's Draft 18 July 2013) (Note: link is to latest)
• svn co -r 30720 https://cvs.khronos.org/svn/repos/registry/trunk/public/typedarray

Node.js Buffer support is based on:

• Buffer Node.js v6.9.1

TextEncoder() and TextDecoder() bindings are based on:

• Encoding API, WHATWG Encoding Living Standard

Performance.now() binding is based on:

• High Resolution Time Level 2

Features§

Besides standard ECMAScript features, Duktape has the following additionalfeatures (some are visible to applications, while others are internal):

• ES2015TypedArray andNode.js Buffer bindings, plain buffer type (lightweight Uint8Array)
• From ECMAScript 2015 (ES6):setPrototypeOf/__proto__, a subset ofProxy objects,Reflect, computed property names, and minimalconst support
• From ECMAScript 2016 (ES7): exponentiation operator (**,**=)
• Encoding API bindings based on the WHATWG Encoding Living Standard
• Duktape specific built-ins: provided by theDuktape global object
• Extended types: custom "buffer" and "pointer" types, extended string type which supports arbitary binary strings and non-BMP strings (standard ECMAScript only supports 16-bit codepoints)
• Combined reference counting and mark-and-sweep garbage collection, with finalizers and emergency garbage collection (you can also build with just mark-and-sweep)
• Coroutine support
• Tail call support
• Built-in debugger framework based on a debugger protocol
• Built-in regular expression engine with no platform dependencies
• Built-in Unicode support with no platform dependencies
• Built-in number parsing and formatting with no platform dependencies
• Built-in CBOR binding for binary serialization
• Additional custom JSON formats (JX and JC)
• Bytecode dump/load mechanism for caching compiled functions

Goals§

Compliance. ECMAScript E5/E5.1 and real world compliance.ECMAScript compliance requires regular expression and Unicode support.When possible, implement features from latest or draft ECMAScriptspecifications to minimize Duktape custom features.

Portability. Minimal system dependencies are nice when porting,so Duktape depends on very few system libraries. For example, numberformatting and parsing, regular expressions, and Unicode are all implementedinternally by Duktape. One of the few dependencies that cannot be fullyeliminated is system date/time integration in theDate built-in.Duktape supports major platforms directly but you can also use an externalDate provider on exotic platforms.

Easy C interface. The interface between Duktape and C programsshould be natural and error-tolerant. As a particular issue, stringrepresentation should be UTF-8 with automatic NUL terminators to matchcommon C use.

Small footprint. Code and data footprint should be as small aspossible, even for small programs. Duktape is portable even to "bare metal"targets with no standard libraries. This is more important than performance,as there are already several very fast engines but fewer very compact,portable engines.

Reasonable performance. Small footprint (and portability, to someextent) probably eliminates the possibility of a competitive JIT-based engine,so there is no practical way of competing with very advanced JIT-based engineslike SpiderMonkey (and its optimized variants) or Google V8. Performanceshould still be reasonable for typical embedded programs.Lua is a good benchmark in this respect.(Adding optional, modular support for JITing or perhaps off-line compilationwould be nice.)

ASCII string performance. It's important that operations dealingwith plain ASCII strings be very fast: ASCII dominates most embedded use.Operations dealing with non-ASCII strings need to perform reasonably but arenot critical. This is a necessary trade-off: using C-compatible strings meansessentially using UTF-8 string representation which makes string indexing andmany other operations slower than with fixed size character representations.It's still important to support common idioms like iterating strings sequentially(in either direction) efficiently.

Document organization§

Getting started guides you through downloading,compiling, and integrating Duktape into your program. It also provides concreteexamples of how you can integrate scripting capabilities into your program.

Programming model,Stack types,andC typesdiscuss core Duktape concepts such asheap,context,value stacks,Duktape API, andDuktape/C functions. Duktape stack types and C typewrappers are discussed in detail.

Duktape specific ECMAScript features are discussed in multiple sections:Type algorithms (for custom types),Duktape built-ins (additional built-ins),Post-ES5 features (features implemented from ES2016 and beyond),Custom behavior (behavior differing from standard),Custom JSON formats,Custom directives,Buffer objects,Error objects (properties and traceback support),Function objects (properties),Date and time,Random numbers,Debugger,Modules,Finalization,Coroutines,Virtual properties,Symbols,Bytecode dump/load,Threading,Sandboxing.

Performance provides a few Duktape-specific tipsfor improving performance and avoiding performance pitfalls.Memory usage summarizes Duktape memory usage andgives pointers for minimizing it.Compiling describes how to configure and compile Duktapeas part of your application.Portability covers platform and compiler specificissues and other portability issues.Compatibility discusses Duktape's compatibilitywith ECMAScript dialects, extensions, and frameworks.Versioning describes Duktape versioning and what versioncompatibility to expect.Limitations summarizes currently known limitationsand provides possible workarounds.

Comparison to Lua discusses some differencesbetween Lua and Duktape; it may be useful reading if you're already familiar with Lua.

Getting started§

Downloading§

Download the source distributable from theDownload page.

Command line tool for testing§

Unpack the distributable:

$ cd /tmp$ tar xvfJ duktape-<version>.tar.xz

Compile the command line tool using the provided Makefile:

$ cd /tmp/duktape-<version>/$ make -f Makefile.cmdline

The Makefile assumes you havegcc installed. If you don't,you can just edit the Makefile to match your compiler (the Makefile isquite simple).

You can now run ECMAScript code interactively:

$ ./duk((o) Duktape 2.6.0 (v2.6.0)duk> print('Hello world!')Hello world!= undefined

You can also run ECMAScript code from a file which is useful for playing withfeatures and algorithms. As an example, createfib.js:

// fib.jsfunctionfib(n){if(n==0){return0;}if(n==1){return1;}returnfib(n-1)+fib(n-2);}functiontest(){var res=[];for(i=0; i<20; i++){        res.push(fib(i));}print(res.join(' '));}test();

Test the script from the command line:

$ ./duk fib.js0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 2584 4181

Integrating Duktape into your program§

The command line tool is simply an example of a program which embedsDuktape. Embedding Duktape into your program is very simple:

• Runduktape-N.N.N/tools/configure.py to configure Duktape for build. The result is a directory containingduktape.c,duktape.h, andduk_config.h.
• Addduktape.c,duktape.h, andduk_config.h to your build, and call the Duktape API from elsewhere in your program.

The Duktape distributable (duktape-N.N.N.tar.xz)src/ directorycontains preconfigured header and source files for the Duktape default configurationwhich can usually be used as is. If needed, the configuration tool allows you to customizeDuktape options, such as optimizing Duktape for low memory targets andenable/disable features. SeeCompiling andConfiguring Duktape for buildfor more details and examples.

The distributable contains a very simple example program,hello.c,which illustrates this process. Compile the test program with the preconfiguredDuktape header and source files e.g. as follows:

$ cd /tmp/duktape-<version>/$ gcc -std=c99 -o hello -Isrc src/duktape.c examples/hello/hello.c -lm

To customize Duktape configuration useconfigure.py:

$ cd /tmp/duktape-<version>/# Here we disable ECMAScript 6 Proxy object support$ python2 tools/configure.py --output-directory duktape-src -UDUK_USE_ES6_PROXY$ gcc -std=c99 -o hello -Iduktape-src duktape-src/duktape.c examples/hello/hello.c -lm

The test program creates a Duktape context and uses it to run someECMAScript code:

$ ./helloHello world!2+3=5

Because Duktape is an embeddable engine, you don't need to changethe basic control flow of your program. The basic approach is:

• Create a Duktape context e.g. in program initialization (or even on-demand when scripting is needed). Usually you would also load your scripts during initialization, though that can also be done on-demand.
• Identify points in your code where you would like to use scripting and insert calls to script functions there.
• To make a script function call, first push call arguments to the Duktape context'svalue stack using the Duktape API. Then, use another Duktape API call to initiate the actual call.
• Once script execution is finished, control is returned to your program (the API call returns) and a return value is left on the Duktape context's value stack. C code can then access the return value using the Duktape API.

More broadly, there are several approaches to how you can use Duktapewith native code; for example:

• Run the main application in C/C++ code but call into Duktape for extending base functionality (e.g. plugins or configuration).
• Run the main application in ECMAScript code, and call into simple C/C++ native bindings for I/O, performance intensive operations, etc. The native bindings are often kept stateless so that state logic remains in view of script code.
• Run the main application in ECMAScript code, but use more complex, stateful C/C++ native bindings for performance intensive operations. For example, a graphics engine can be implemented as a native object.

See the following Wiki articles for detailed examples:

• Getting started: line processing
• Getting started: primality testing

Programming model§

Overview§

Programming with Duktape is quite straightforward:

• Add Duktape source (duktape.c) and headers (duktape.h andduk_config.h) to your build. If the default configuration is not appropriate, usepython2 tools/configure.py to prepare Duktape sources and headers for a custom configuration.
• Create a Duktapeheap (a garbage collection region) and an initialcontext (essentially a thread handle) in your program.
• Load the necessary ECMAScript script files, and register your Duktape/C functions. Duktape/C functions are C functions you can call from ECMAScript code for better performance, bindings to native libraries, etc.
• Use the Duktape API to call ECMAScript functions whenever appropriate. Duktape API is used to pass values to and from functions. Values are converted between their C representation and the Duktape internal (ECMAScript compatible) representation.
• Duktape API is also used by Duktape/C functions (called from ECMAScript) to access call arguments and to provide return values.

Let's look at all the steps and their related concepts in more detail.

Heap and context§

A Duktapeheap is a single region for garbage collection. A heapis used to allocate storage for strings, ECMAScript objects, and othervariable size, garbage collected data. Objects in the heap have an internalheap header which provides the necessary information for reference counting,mark-and-sweep garbage collection, object finalization, etc.Heap objects can reference each other, creating a reachability graph froma garbage collection perspective. For instance, the properties of an ECMAScriptobject reference both the keys and values of the object's property set. You canhave multiple heaps, but objects in different heaps cannot reference each otherdirectly; you need to use serialization to pass values between heaps.

A Duktapecontext is an ECMAScript "thread of execution" which livesin a certain Duktape heap. A context is represented by aduk_context *in the Duktape API, and is associated with an internal Duktape coroutine (a formof a co-operative thread). Each context is also associated with an environmentconsisting of global objects; contexts may share the same global environment butcan also have different environments. The context handle is given to almost everyDuktape API call, and allows the caller to interact with thevalue stack ofthe Duktape coroutine: values can be inserted and queries, functions can be called,and so on.

Each coroutine has acall stack which controls execution, keepingtrack of function calls, native or ECMAScript, within the ECMAScript engine.Each coroutine also has avalue stack which stores all the ECMAScriptvalues of the coroutine's active call stack. The value stack always has anactivestack frame for the most recent function call (when no functioncalls have been made, the active stack frame is the value stack as is).The Duktape API calls operate almost exclusively in the currently activestack frame. There's also internal book-keeping for error catching sitesestablished using e.g.try-catch-finally.

Multiple contexts can share the same Duktapeheap. In more concreteterms this means that multiple contexts can share the same garbage collectionstate, and can exchange object references safely. Contexts in different heapscannot exchange direct object references; all values must be serialized in oneway or another.

Almost every API call provided by the Duktape API takes a context pointeras its first argument: no global variables or states are used, and there areno restrictions on running multiple, independent Duktape heaps and contextsat the same time. There are multi-threading restrictions, however: only onenative thread can execute any code within a single heap at any time, seeThreading.

To create a Duktape heap and an initial context inside the heap, you cansimply use:

duk_context*ctx=duk_create_heap_default();if(!ctx){exit(1);}

If you wish to provide your own memory allocation functions and a fatalerror handler function (recommended), use:

duk_context*ctx=duk_create_heap(my_alloc,                                   my_realloc,                                   my_free,                                   my_udata,                                   my_fatal);if(!ctx){exit(1);}

To create a new context inside the same heap, with the context sharing thesame global objects:

duk_context*new_ctx;(void)duk_push_thread(ctx);new_ctx=duk_get_context(ctx,-1/*index*/);

To create a new context inside the same heap, but with a fresh set of globalobject:

duk_context*new_ctx;(void)duk_push_thread_new_globalenv(ctx);new_ctx=duk_get_context(ctx,-1/*index*/);

Contexts are automatically garbage collected when they become unreachable.This also means that if your C code holds aduk_context *, thecorresponding Duktape coroutine MUST be reachable from a garbage collectionpoint of view.

A heap must be destroyed explicitly when the caller is done with it:

duk_destroy_heap(ctx);

This frees all heap objects allocated, and invalidates any pointers tosuch objects. In particular, if the calling program holds string pointersto values which resided on the value stack of a context associated with theheap, such pointers are invalidated and must never be dereferenced afterthe heap destruction call returns.

Call stack (of a context)§

The call stack of a context is not directly visible to the caller.It keeps track of the chain of function calls, either C or ECMAScript,currently executing in a context. The main purpose of this book-keeping isto facilitate the passing of arguments and results between function callersand callees, and to keep track of how the value stack is divided betweenfunction calls. The call stack also allows Duktape to construct a tracebackfor errors.

Because Duktape supports tail calls, the call stack does not alwaysaccurately represent the true call chain: tail calls will be "squashed"together in the call stack.

Value stack (of a context) and value stack index§

The value stack of a context is an array of tagged type values relatedto the current execution state of a coroutine. The tagged types used are:undefined,null, boolean, number, string, object,buffer, pointer, and lightfunc. For a detailed discussion of the availabletagged types, seeTypes.

The value stack is divided between the currently active function calls(activations) on the coroutine's call stack. At any time, there is an activestack frame which provides an origin for indexing elements on the stack.More concretely, at any time there is abottom which is referredto with the index zero in the Duktape API. There is also a conceptualtop which identifies the stack element right above the highestcurrently used element. The following diagram illustrates this:

 Value stack of 15 entries (absolute indices).----.| 15 || 14 || 13 || 12 |      Active stack frame (indices| 11 |      relative to stack bottom)| 10 ||  9 |      .---.   Stack top is 6 (relative to stack bottom).|  8 | <--- | 5 |   API index 5 is highest used (at value stack index 8).|  7 |      | 4 ||  6 |      | 3 ||  5 |      | 2 ||  4 |      | 1 ||  3 | <--- | 0 |   API index 0 is bottom (at value stack index 3).|  2 |      `---'|  1 ||  0 |`----'

There is no direct way to refer to elements in the internal value stack:Duktape API always deals with the currently active stack frame. Stack framesare shown horizontally throughout the documentation for space reasons. Forexample, the active stack frame in the figure above would be shown as:

Avalue stack index is a signed integer index used in the DuktapeAPI to refer to elements in currently active stack frame, relative to thecurrent frame bottom.

Non-negative (>= 0) indices refer to stack entries in thecurrent stack frame, relative to the frame bottom:

Negative (< 0) indices refer to stack entries relative to the top:

The special constantDUK_INVALID_INDEX is a negative integerwhich denotes an invalid stack index. It can be returned from API callsand can also be given to API calls to indicate a "no value".

Thevalue stack top (or just "top") is the non-negative index ofan imaginary element just above the highest used index. For instance, abovethe highest used index is 5, so the stack top is 6. The top indicates thecurrent stack size, and is also the index of the next element pushed to thestack.

Growing the value stack§

At any time, the value stack of a context is allocated for a certainmaximum number of entries. An attempt to push values beyond the allocatedsize will cause an error to be thrown, it willnot cause the valuestack to be automatically extended. This simplifies the internalimplementation and also improves performance by minimizing reallocationswhen you know, beforehand, that a certain number of entries will be neededduring a function.

When a value stack is created or a Duktape/C function is entered, thevalue stack is always guaranteed to have space for the call arguments andDUK_API_ENTRY_STACK (currently 64) elements. In the typicalcase this is more than sufficient so that the majority of Duktape/Cfunctions don't need to extend the value stack. Only functions that needmore space or perhaps need an input-dependent amount of space need to growthe value stack.

You can extend the stack allocation explicitly withduk_check_stack()or (usually more preferably)duk_require_stack().Once successfullyextended, you are again guaranteed that the specified number of elements canbe pushed to the stack. There is no way to shrink the allocation except byreturning from a Duktape/C function.

Consider, for instance, the following function which will uppercase aninput ASCII string by pushing uppercased characters one-by-one on the stackand then concatenating the result. This example illustrates how the numberof value stack entries required may depend on the input (otherwise this isnot a very good approach for uppercasing a string):

/* uppercase.c */#include<stdio.h>#include<stdlib.h>#include"duktape.h"staticintdummy_upper_case(duk_context*ctx){size_t sz;constchar*val=duk_require_lstring(ctx,0,&sz);size_t i;/* We're going to need 'sz' additional entries on the stack. */duk_require_stack(ctx, sz);for(i=0; i< sz; i++){char ch= val[i];if(ch>='a'&& ch<='z'){            ch= ch-'a'+'A';}duk_push_lstring(ctx,(constchar*)&ch,1);}duk_concat(ctx, sz);return1;}intmain(int argc,char*argv[]){duk_context*ctx;if(argc<2){exit(1);}    ctx=duk_create_heap_default();if(!ctx){exit(1);}duk_push_c_function(ctx, dummy_upper_case,1);duk_push_string(ctx, argv[1]);duk_call(ctx,1);printf("%s -> %s\n", argv[1],duk_to_string(ctx,-1));duk_pop(ctx);duk_destroy_heap(ctx);return0;}

In addition to user reserved elements, Duktape keeps an automatic internalvalue stack reserve to ensure all API calls have enough value stack space towork without further allocations. The value stack is also extended and shrunkin somewhat large steps to minimize memory reallocation activity. As a resultthe internal number of value stack elements available beyond the callerspecified extra varies considerably. The caller does not need to take thisinto account and should never rely on any additional elements being available.

ECMAScript array index§

ECMAScript object and array keys can only be strings or Symbols. Arrayindices (e.g. 0, 1, 2) are represented as canonical string representations ofthe respective numbers (e.g. "0", "1", "2"). More technically, all canonicalstring representations of the integers in the range [0, 2**32-2] are validarray indices.

To illustrate the ECMAScript array index handling, consider the followingexample:

var arr=['foo','bar','quux'];print(arr[1]);// refers to 'bar'print(arr["1"]);// refers to 'bar'print(arr[1.0]);// refers to 'bar', canonical encoding is "1"print(arr["1.0"]);// undefined, not an array index

Some API calls operating on ECMAScript arrays accept numeric array indexarguments. This is really just a short hand for denoting a string conversionof that number. For instance, if the API is given the integer 123, thisreally refers to the property name "123".

Internally, Duktape tries to avoid converting numeric indices to actualstrings whenever possible, so it is preferable to use array index API callswhen they are relevant. Similarly, when writing ECMAScript code it ispreferable to use numeric rather than string indices, as the same fast pathapplies for ECMAScript code.

Duktape API§

Duktape API is the collection of user callable API calls defined induktape.h and documented in theAPI reference.

The Duktape API calls are generally error tolerant and will check allarguments for errors (such asNULL pointers). However, tominimize footprint, thectx argument is not checked, and thecaller MUST NOT call any Duktape API calls with aNULL context.

All Duktape API calls are potentially macros. Calling code must not relyon any Duktape API call being available as a function pointer. Theimplementation of a certain API call may change between a macro and anactual function even between compatible releases. The Duktape API providesthe following guarantees for macros:

• Arguments are never evaluated more than once (unless explicitly mentioned). However, an argument may not be evaluated at all if an argument is ignored in the current version.
• An API call with a return value can be used as an expression. If the API macro contains multiple statements, it is implemented as a comma expression (e.g.(foo, bar, quux)).
• An API call with avoid return value may not necessarily work as part of an expression. The API macro may be implemented as a block statement or as a dummydo {...} while (0) loop.

Duktape/C function§

A C function with a Duktape/C API signature can be associated with anECMAScript function object, and gets called when the ECMAScript functionobject is called. A Duktape/C API function looks as follows:

duk_ret_tmy_func(duk_context*ctx){duk_push_int(ctx,123);return1;}

The function gets ECMAScript call arguments in the value stack ofctx, withduk_get_top()indicating the number ofarguments present on the value stack. Thethis binding is notautomatically pushed to the value stack; useduk_push_this()to access it if necessary. When creating an ECMAScript function objectassociated with a Duktape/C function, one can select the desired numberof arguments. Extra arguments are dropped and missing arguments are replacedwithundefined. A function can also be registered as a varargfunction (by givingDUK_VARARGS as the argument count) inwhich case call arguments are not modified prior to C function entry.

The function can return one of the following:

• Return value 1 indicates that the value on the stack top is to be interpreted as a return value.
• Return value 0 indicates that there is no explicit return value on the value stack; anundefined is returned to caller.
• A negative return value indicates that an error is to be automatically thrown. Error codes namedDUK_RET_xxx map to specific kinds of errors (do not confuse these withDUK_ERR_xxx which are positive values). This is an optional shorthand which has a small footprint but also some drawbacks (e.g. no error message).
• A return value higher than 1 is currently undefined, as ECMAScript doesn't support multiple return values in Edition 5.1. (Values higher than 1 may be taken into to support multiple return values in ECMAScript Edition 6.)

When a Duktape/C function returns, the value stack is automaticallyunwound so there is no need to manually clean up the value stack whenthe function returns.

A negative error return value is intended to simplify common errorhandling, and is an alternative to constructing and throwing an errorexplicitly with Duktape API calls. No error message can be given; amessage is automatically constructed by Duktape. For example:

duk_ret_tmy_func(duk_context*ctx){if(duk_get_top(ctx)==0){/* throw TypeError if no arguments given */return DUK_RET_TYPE_ERROR;}/* ... */}

All Duktape/C functions are consideredstrict in theECMAScript sense.Duktape API calls always obey ECMAScript strict mode semantics, even when the API callsare made outside of any Duktape/C function, i.e. with an empty call stack.For instance, attempt to delete a non-configurable property usingduk_del_prop()will cause an error to be thrown. This is the case with a strict ECMAScript function too:

functionf(){'use strict';var arr=[1,2,3];returndelete arr.length;// array 'length' is non-configurable}print(f());// this throws an error because f() is strict

Another consequence of Duktape/C function strictness is that thethisbinding given to Duktape/C functions is notcoerced.This is also the case for strict ECMAScript code:

functionstrictFunc(){'use strict';print(typeofthis);}functionnonStrictFunc(){print(typeofthis);}strictFunc.call('foo');// prints 'string' (uncoerced)nonStrictFunc.call('foo');// prints 'object' (coerced)

Duktape/C functions are currently alwaysconstructable, i.e. theycan always be used innew Foo() expressions. You can check whethera function was called in constructor mode as follows:

staticduk_ret_tmy_func(duk_context*ctx){if(duk_is_constructor_call(ctx)){printf("called as a constructor\n");}else{printf("called as a function\n");}}

To save memory, Duktape/C functions don't have aprototypeproperty by default, so the default object instance (given to the constructorasthis) inherits fromObject.prototype. To use acustom prototype you can defineprototype for the Duktape/Cfunction explicitly. Another approach is to ignore the default object instanceand construct one manually within the Duktape/C call: as with ECMAScriptfunctions, if a constructor returns an object value, that value replaces thedefault object instance and becomes the value of thenewexpression.

Storing state for a Duktape/C function§

Sometimes it would be nice to provide parameters or additional stateto a Duktape/C function out-of-band, i.e. outside explicit call arguments.There are several ways to achieve this.

Properties of function§

First, a Duktape/C function can use its Function object to store stateor parameters. A certain Duktape/C function (the actual C function)is always represented by an ECMAScript Function object which isinternally associated with the underlying C function. The Functionobject can be used to store properties related to that particularinstance of the function. Note that a certain Duktape/C function canbe associated with multiple independent Function objects and thusindependent states.

Accessing the ECMAScript Function object related to a Duktape/C functionis easy:

duk_push_current_function(ctx);duk_get_prop_string(ctx,-1,"my_state_variable");

'this' binding§

Another alternative for storing state is to call the Duktape/C functionas a method and then use thethis binding for storing state. Forinstance, consider a Duktape/C function called as:

foo.my_c_func()

When called, the Duktape/C function getsfoo as itsthisbinding, and one could store state directly infoo. The differenceto using the Function object approach is that the same object is shared by allmethods, which has both advantages and disadvantages.

Accessing thethis binding is easy:

duk_push_this(ctx);duk_get_prop_string(ctx,-1,"my_state_variable");

Hidden Symbol properties§

If data needs to be associated with an object, but hidden from ECMAScriptcode, hiddenSymbols can be used as a property key. Thekey is only accessible via the C API, unless passed to ECMAScript code from theC API. A common use case is to associated backing pointers/data to C memory.Symbols are created as a string, but are differentiated with macros that markthem as Symbols.

For example, setting and getting a hidden symbol onthis:

my_context_data_t*my_context_data=malloc(sizeof(my_context_data_t));duk_push_this(ctx);duk_push_pointer(ctx, my_context_data);duk_put_prop_string(ctx,-2,DUK_HIDDEN_SYMBOL("my_context_data"));/* ... */duk_push_this(ctx);duk_get_prop_string(ctx,-1,DUK_HIDDEN_SYMBOL("my_context_data"));my_context_data_t*my_context_data=duk_get_pointer(ctx,-1);

Magic value of function§

Duktape/C function objects can store an internal 16-bit signed integer "magic"value (zero by default) with no extra memory cost. The magic value can be usedto pass flags and/or small values to a Duktape/C function at minimal cost, sothat a single native function can provide slightly varied behavior for multiplefunction objects:

/* Magic value example: two lowest bits are used for a prefix index, bit 2 (0x04) * is used to select newline style for a log write helper. */constchar*prefix[4]={"INFO","WARN","ERROR","FATAL"};duk_int_t magic=duk_get_current_magic(ctx);printf("%s: %s", prefix[magic&0x03],duk_safe_to_string(ctx,0));if(magic&0x04){printf("\r\n");}else{printf("\n");}

For an API usage example, see the test casetest-get-set-magic.c.Duktape uses magic values a lot internally to minimize size of compiled code, see e.g.duk_bi_math.c.

Heap stash§

The heap stash is an object visible only from C code. It is associatedwith the Duktape heap, and allows Duktape/C code to store "under the hood"state data which is not exposed to ECMAScript code. It is accessed with theduk_push_heap_stash()API call.

Global stash§

The global stash is like the heap stash, but is associated with a globalobject. It is accessed with theduk_push_global_stash()API call. There can be several environments with different global objectswithin the same heap.

Thread stash§

The thread stash is like the heap stash, but is associated with a Duktapethread (i.e. actx pointer). It is accessible with theduk_push_thread_stash()API call.

Duktape version specific code§

The Duktape version is available through theDUK_VERSION define,with the numeric value(major * 10000) + (minor * 100) + patch.The same value is available to ECMAScript code throughDuktape.version.Calling code can use this define for Duktape version specific code.

For C code:

#if(DUK_VERSION>=20403)/* Duktape 2.4.3 or later */#elif(DUK_VERSION>=10500)/* Duktape 1.5.0 or later */#else/* Duktape lower than 1.5.0 */#endif

For ECMAScript code (also seeDuktape built-ins):

if(typeof Duktape!=='object'){print('not Duktape');}elseif(Duktape.version>=20403){print('Duktape 2.4.3 or higher');}elseif(Duktape.version>=10500){print('Duktape 1.5.0 or higher (but lower than 2.4.3)');}else{print('Duktape lower than 1.5.0');}

Numeric error codes§

When errors are created or thrown using the Duktape API, the callermust assign a numeric error code to the error. Error codes arepositive integers, with a range restricted to 24 bits at themoment: the allowed error number range is thus [1,16777215]. Built-inerror codes are defined induktape.h, e.g.DUK_ERR_TYPE_ERROR.

The remaining high bits are used internally to carry e.g. additionalflags. Negative error values are used in the Duktape/C API as ashorthand to automatically throw an error.

Error handling§

Error handling in the Duktape API is similar to how ECMAScript handleserrors: errors are thrown either explicitly or implicitly, then caught andhandled. Instead of a try-catch statement application C code usesprotectedDuktape API calls to establish points in C code where errors can be caughtand handled. All Duktape API calls except protected calls may throw errors:most ECMAScript operations may cause error throws in some situations, and anout-of-memory error is possible in almost any situation. The long controltransfer between the throw site and the catch site is based either onsetjmp()/longjmp() (or their platform specificvariants), or a C++ exception throw (whenDUK_USE_CPP_EXCEPTIONSis enabled), seeLong control transfers.

An uncaught error causes the fatal error handler to be called, which isconsidered an unrecoverable situation and should ordinarily be avoided,seeNormal and fatal errors andHow to handle fatal errors. To avoid fatal errors, typical application code should establish anerror catch site before making other Duktape API calls. This is done usingprotected Duktape API calls, for example:

• Use protected calls to evaluate code (duk_peval()), compile code (duk_pcompile()), and call (duk_pcall()) functions.
• Use a singleduk_safe_call() to establish an error catcher so that you can use unsafe primitives freely inside the safe call.

An example of the first technique:

/* Use duk_peval() variant to evaluate a file so that script errors are * handled safely.  Both syntax errors and runtime errors are caught. */push_file_as_string(ctx,"myscript.js");if(duk_peval(ctx)!=0){/* Use duk_safe_to_string() to convert error into string.  This API     * call is guaranteed not to throw an error during the coercion.     */printf("Script error: %s\n",duk_safe_to_string(ctx,-1));}duk_pop(ctx);

An example of the second technique:

/* Use duk_safe_call() to wrap all unsafe code into a separate C function. * This approach has the advantage of covering all API calls automatically * but is a bit more verbose. */staticduk_ret_tunsafe_code(duk_context*ctx,void*udata){/* Here we can use unprotected calls freely. */(void) udata;/* 'udata' may be used to pass e.g. a struct pointer */push_file_as_string(ctx,"myscript.js");duk_eval(ctx);/* ... */return0;/* success return, no return value */}/* elsewhere: */if(duk_safe_call(ctx, unsafe_code, NULL/*udata*/,0/*nargs*/,1/*nrets */)!=0){/* The 'nrets' argument should be at least 1 so that an error value     * is left on the stack if an error occurs.  To avoid further errors,     * use duk_safe_to_string() for safe error printing.     */printf("Unexpected error: %s\n",duk_safe_to_string(ctx,-1));}duk_pop(ctx);

Even within protected calls there are some rare cases, such as internalerrors, that will either cause a fatal error or propagate an error outwardsfrom a protected API call. These should only happen in abnormal conditionsand are not considered recoverable. To handle also these cases well, aproduction quality application should always have a fatal error handler witha reasonable strategy for dealing with fatal errors. Such a strategy isnecessarily application dependent, but could be something like:

• On an embedded device the fatal error handler could write the fatal error information to a flash file and reboot the device. After the reboot, the fatal error could be reported to a diagnostics server so that it can be investigated.
• On a UNIX system the fatal error handler could simply exit the process (the default fatal handler usesabort()) and let a wrapper script restart the application.

Note that it may be fine for some applications to make API calls withoutan error catcher and risk throwing uncaught errors leading to a fatal error.It's not safe to continue execution after a fatal error, so suchapplications would typically simply exit when a fatal error occurs. Evenwithout an actual recovery strategy, a fatal error handler should be used toe.g. write fatal error information tostderr before process exit.

Normal and fatal errors§

Anordinary error is caused by athrow statement, aduk_throw()API call (or similar), or by an internal, recoverable Duktape error.Ordinary errors can be caught with atry-catch in ECMAScriptcode or e.g.duk_pcall()(see API calls taggedprotected)in C code.

Afatal error is caused by an uncaught error, an assertion failure(if enabled), an explicit call toduk_fatal(), or an unrecoverableerror inside Duktape.

Each Duktape heap has a heap-wide fatal error handler registered induk_create_heap().If no handler is given a built-in default handler is used:

• Default configuration: the built-in default fatal error handler writes a debug log message butwon't write anything tostdout orstderr. Debug logging is disabled by default, so that the fatal error message is not displayed by default. The handler then callsabort(). If the abort() call exits for some reason, the handler then enters an infinite loop to ensure execution doesn't resume after a fatal error.
• DUK_USE_CPP_EXCEPTIONS enabled: the built-in default fatal error handler throws aduk_fatal_exception. This exception inherits fromstd::runtime_error so that it can be easily caught and provides a::what() method to read the fatal error message. It is unsafe to continue execution after catching the fatal error.
• IfDUK_USE_FATAL_HANDLER is defined, it is always used as the built-in default fatal error handler, even if C++ exceptions are enabled.

There's no safe way to resume execution after a fatal error, so that afatal error handler must not return or call into the Duktape API. Instead thehandler should e.g. write out the message to the console or a log file andthen exit the process (or restart an embedded device). This also applies whenusing C++ exceptions as the long control transfer mechanism.If theapplication continues execution after a fatal error all bets are off: memoryleaks are possible, and memory safety may be compromised.

Fatal errors may also happen without any heap context, so that Duktapecan't look up a possible heap-specific fatal error handler. Duktape will thenalways call the built-in default fatal error handler (with the handleruserdata argument set to NULL). Fatal errors handled this way are currentlylimited to assertion failures, so that if you don't enable assertions, no sucherrors will currently occur and all fatal error handling goes through theheap-associated fatal error handler which is in direct application control.

SeeHow to handle fatal errorsfor more detail and examples.

Long control transfers§

The specific long control transfer mechanism Duktape uses internallyfor error throwing and catching is not directly visible to application code:application code uses aprotected call to catcherrors, while errors are thrown by Duktape or by the application using avariety of Duktape API calls, e.g.duk_error().

Default configuration, without DUK_USE_CPP_EXCEPTIONS§

In the default configuration a Duktape API protected call usessetjmp() to establish a catch site. The error throwsite useslongjmp() to unwind the native C stack and returnto the (nearest) catch site. On some platforms variants of the calls, suchassigsetjmp() andsiglongjmp are used. There areminor differences between the call variants e.g. with regards to performanceand signal handling. The variant is chosen byduk_config.h.

Alongjmp() unwinds all the native C stack frames between thelongjmp() and thesetjmp(). However, this unwindingprocess won't invoke C++ automatic destructors which may be a significantlimitation for some C++ applications.

For fatal errors, e.g. uncaught errors, the default fatal error handlerusesabort(), seeNormal and fatal errors.

C++ mode, with DUK_USE_CPP_EXCEPTIONS§

WhenDUK_USE_CPP_EXCEPTIONS is enabled the long control transferis based on a C++ exception throw. The protected call uses a C++ try-catchto establish a catch site; note that this happens inside Duktape, and is notvisible to the application. The error throw site throws aduk_internal_exception which is caught by the (nearest) Duktapecatch site.Application code must not catch (or throw) the exception.To minimize that risk, the exception doesn't inherit from any standard exceptionclass so it won't be caught by a boilerplatestd::exception catchsite.

For fatal errors, e.g. uncaught errors, aduk_fatal_exceptionis thrown by the default fatal error handler. The exception inherits fromstd::runtime_error and is intended to be caught by user code.The exception provides a::what() method returning the fatalerror message. Even though the fatal error is catchable, it is still unsafeto continue execution after catching the error. SeeNormal and fatal errors.

For both C++ exception types the C++ native stack unwind process supportsautomatic destructors for the stack frames between the throw site and the catchsite.

Stack types§

Overview§

Memory allocations§

The following stack types involve additional heap allocations:

• String: a single allocation contains a combined heap and string header, followed by the immutable string data. When external strings are used (not enabled by default, typically in low memory environments) the string data may also be external.
• Object: one allocation is used for a combined heap and object header, and another allocation is used for object properties. The property allocation contains both array entries and normal properties, and if the object is large enough, a hash table to speed up lookups.
• Buffer: for fixed buffers a single allocation contains a combined heap and buffer header, followed by the mutable fixed-size buffer. For dynamic buffers the current buffer is allocated separately. For external buffers a single heap object is allocated and points to a user buffer.

While strings and buffers are considered a primitive (pass-by-value)types, they are a heap allocated type from a memory allocation viewpoint.

Pointer stability§

Heap objects allocated by Duktape have stable pointers: the objects arenot relocated in memory while they are reachable from a garbage collectionpoint of view. This is the case for the main heap object, but notnecessarily for any additional allocations related to the object, such asdynamic property tables or dynamic buffer data area. A heap object isreachable e.g. when it resides on the value stack of a reachable thread oris reachable through the global object. Once a heap object becomesunreachable any pointers held by user C code referring to the object areunsafe and should no longer be dereferenced.

In practice the only heap allocated data directly referenced by user codeare strings, fixed buffers, and dynamic buffers. The data area of stringsand fixed buffers is stable; it is safe to keep a C pointer referring to thedata even after a Duktape/C function returns as long the string or fixedbuffer remains reachable from a garbage collection point of view at all times.Note that this isnot the case for Duktape/C value stack arguments, forinstance, unless specific arrangements are made.

The data area of a dynamic buffer doesnot have a stable pointer.The buffer itself has a heap header with a stable address but the currentbuffer is allocated separately and potentially relocated when the bufferis resized. It is thus unsafe to hold a pointer to a dynamic buffer's dataarea across a buffer resize, and it's probably best not to hold a pointerafter a Duktape/C function returns (as there would be no easy way of beingsure that the buffer hadn't been resized).

For external buffers the stability of the data pointer is up to the usercode which sets and updates the pointer.

Type masks§

Type masks allows calling code to easily check whether a type belongs toa certain type set. For instance, to check that a certain stack value isa number, string, or an object:

if(duk_get_type_mask(ctx,-3)&(DUK_TYPE_MASK_NUMBER|                                  DUK_TYPE_MASK_STRING|                                  DUK_TYPE_MASK_OBJECT)){printf("type is number, string, or object\n");}

There is a specific API call for matching a set of types even moreconveniently:

if(duk_check_type_mask(ctx,-3, DUK_TYPE_MASK_NUMBER|                                 DUK_TYPE_MASK_STRING|                                 DUK_TYPE_MASK_OBJECT)){printf("type is number, string, or object\n");}

These are faster and more compact than the alternatives:

// alt 1if(duk_is_number(ctx,-3)||duk_is_string(ctx,-3)||duk_is_object(ctx,-3)){printf("type is number, string, or object\n");}// alt 2int t=duk_get_type(ctx,-3);if(t== DUK_TYPE_NUMBER|| t== DUK_TYPE_STRING|| t== DUK_TYPE_OBJECT){printf("type is number, string, or object\n");}

None§

Thenone type is not actually a type but is used in the API toindicate that a value does not exist, a stack index is invalid, etc.

Undefined§

Theundefined type maps to ECMAScriptundefined, which isdistinguished from anull.

Values read from outside the active value stack range read back asundefined.

Null§

Thenull type maps to ECMAScriptnull.

Boolean§

Theboolean type is represented in the C API as an integer: zero for false,and non-zero for true.

Whenever giving boolean values as arguments in API calls, any non-zero value isaccepted as a "true" value. Whenever API calls return boolean values, the value1 is always used for a "true" value. This allows certain C idioms to beused. For instance, a bitmask can be built directly based on API call return values,as follows:

/* this works and generates nice code */int bitmask=(duk_get_boolean(ctx,-3)<<2)|(duk_get_boolean(ctx,-2)<<1)|duk_get_boolean(ctx,-1);/* more verbose variant not relying on "true" being represented by 1 */int bitmask=((duk_get_boolean(ctx,-3)?1:0)<<2)|((duk_get_boolean(ctx,-2)?1:0)<<1)|(duk_get_boolean(ctx,-1)?1:0);/* another verbose variant */int bitmask=(duk_get_boolean(ctx,-3)?(1<<2):0)|(duk_get_boolean(ctx,-2)?(1<<1):0)|(duk_get_boolean(ctx,-1)?1:0);

Number§

Thenumber type is an IEEE double, including +/- Infinity and NaN values.Zero sign is also preserved. An IEEE double represents all integers up to 53 bitsaccurately.

IEEE double allows NaN values to have additional signaling bits. Because thesebits are used by Duktape internal tagged type representation (when using 8-bytepacked values), NaN values in the Duktape API are normalized. Concretely, if youpush a certain NaN value to the value stack, another (normalized) NaN value maycome out. Don't rely on NaNs preserving their exact form.

String§

Thestring stack type is used to represent both plain strings andplain Symbols (introduced in ES2015). A string is an arbitrary byte sequenceof a certain length which may contain internal NUL (0x00) values. Strings arealways automatically NUL terminated for C coding convenience. The NUL terminatoris not counted as part of the string length. For instance, the string"foo" has byte length 3 and is stored in memory as{ 'f', 'o', 'o', '\0' }. Because of the guaranteed NUL termination,strings can always be pointed to using a simpleconst char * as longas internal NULs are not an issue for the application; if they are, the explicitbyte length of the string can be queried with the API. Calling code can referdirectly to the string data held by Duktape. Such string data pointers are valid(and stable) for as long as a string is reachable in the Duktape heap.

Strings areinternedfor efficiency: only a single copy of a certain string ever exists at a time.Strings are immutable and must NEVER be changed by calling C code. Doing so willlead to very mysterious issues which are hard to diagnose.

Calling code most often deals with ECMAScript strings, which may containarbitrary 16-bit codepoints in the range U+0000 to U+FFFF but cannot representnon-BMPcodepoints. This is how strings are defined in the ECMAScript standard.In Duktape, ECMAScript strings are encoded withCESU-8 encoding. CESU-8matchesUTF-8 except that itallows codepoints in the surrogate pair range (U+D800 to U+DFFF) to be encodeddirectly (prohibited in UTF-8). CESU-8, like UTF-8, encodes all 7-bit ASCIIcharacters as-is which is convenient for C code. For example:

• U+0041 ("A") encodes to41.
• U+1234 (ETHIOPIC SYLLABLE SEE) encodes toe1 88 b4.
• U+D812 (high surrogate) encodes toed a0 92. This would beinvalid UTF-8.

Duktape also uses extended strings internally. Codepoints up to U+10FFFFcan be represented with UTF-8, and codepoints above that up to full 32 bitscan be represented withextended UTF-8.The extended UTF-8 encoding used by Duktape is described in the table below.The leading byte is shown in binary (with "x" marking data bits) whilecontinuation bytes are marked with "C" (indicating the bit sequence 10xxxxxx):

The downside of the encoding for codepoints above U+7FFFFFFF is thatthe leading byte will be0xFE which conflicts with Unicode byte ordermarker encoding. This is not a practical concern in Duktape's internal use.

Finally, invalid extended UTF-8 byte sequences are used for special purposessuch as representing Symbol values. Invalid extended UTF-8/CESU-8 byte sequencesnever conflict with standard ECMAScript strings (which are CESU-8) and will remaincleanly separated within object property tables. For more information seeSymbols andsymbols.rst.

Strings with invalid extended UTF-8 sequences can be pushed on the value stackfrom C code and also passed to ECMAScript functions, with two caveats:

• If the invalid byte sequence matches the internal format used to represent Symbols, the value will appear as a Symbol rather than a string for ECMAScript code. For example,typeof val will besymbol.
• Behavior of string operations on invalid byte sequences if not well defined and results may vary, and change even in minor Duktape version updates.

Object§

Theobject type includes ECMAScript objects and arrays, functions,threads (coroutines), and buffer objects. In other words, anything withproperties is an object. Properties are key-value pairs with a string keyand an arbitrary value (includingundefined).

Objects may participate in garbage collection finalization.

Buffer§

The plainbuffer type is a raw buffer for user data. It's morememory efficient than standard buffer object types like Uint8Arrayor Node.js Buffer. There are three plain buffer sub-types:

Unlike strings, buffer data areas are not automatically NUL-terminatedand calling code must never access bytes beyond the currently allocatedbuffer size. The data pointer of a zero-size dynamic or external buffermay be NULL; fixed buffers always have a non-NULL data pointer.

Fixed and dynamic buffers are automatically garbage collected. Thisalso means that C code must not hold onto a buffer data pointer unless thebuffer is reachable to Duktape, e.g. resides in an active value stack.The data area of an external buffer is not automatically garbage collectedso user code is responsible for managing its life cycle. User code must alsomake sure that no external buffer value is accessed when the external bufferis no longer (or not yet) valid.

Plain buffers mimic Uint8Array objects to a large extent, so they area non-standard, memory efficient alternative to working with e.g. ArrayBufferand typed arrays. The standard buffer objects are implemented on top of plainbuffers, so that e.g. an ArrayBuffer will be backed by a plain buffer. SeeBuffer objects for more discussion.

A few notes:

• Because the value written to a buffer index is number coerced, assigninga one-character value does not work as often expected. For instance,buf[123] = 'x' causes zero to be written to the buffer, asToNumber('x') = 0. For clarity, you should only assign number values,e.g.buf[123] = 0x78.
• There is a fast path for reading and writing numeric indices of plain buffervalues, e.g.x = buf[123] orbuf[123] = x. A similarfast path exists for the different buffer object values.
• Buffer virtual properties are not currently implemented indefineProperty(), so you can't write to buffer indices orbufferlength withdefineProperty() now (attemptto do so results in aTypeError).

Pointer§

Thepointer type is a raw, uninterpreted C pointer, essentiallyavoid *. Pointers can be used to point to native objects (memoryallocations, handles, etc), but because Duktape doesn't know their use, theyare not automatically garbage collected. You can, however, put one or morepointers inside an object and use the object finalizer to free thenative resources related to the pointer(s).

Lightfunc§

Thelightfunc type is a plain Duktape/C function pointer and a smallset of control flags packed into a single tagged value which requires no separateheap allocations. The control flags (16 bits currently) encode:(1) number of stack arguments expected by the Duktape/C function (0 to 14 orvarargs), (2) virtuallength property value (0 to 15), and(3) a magic value (-128 to 127).

Lightfuncs are a separate tagged type in the Duktape C API, but behave mostlylike Function objects for ECMAScript code. They have significant limitationscompared to ordinary Function objects, the most important being:

• Lightfuncs cannot hold own properties. They have a fixed virtual.name property which appears in tracebacks, and a virtual.length property. Other properties are inherited fromFunction.prototype.
• Lightfuncs can be used as constructor functions, but cannot have a.prototype property. If you need to construct objects which don't inherit fromObject.prototype (the default), you need to either (a) construct and return an instance explicitly in the constructor or (b) explicitly override the internal prototype of the default instance in the constructor.
• Lightfuncs can be used as accessor properties (getters/setters), but they get converted to actual functions so that their memory advantage is lost. Seetest-dev-lightfunc-accessor.js.
• Lightfuncs cannot have a finalizer as they are a primitive type and don't have a reference count field or otherwise participate in garbage collection. Seetest-dev-lightfunc-finalizer.js.

Lightfuncs are useful for very low memory environments where the memoryimpact of ordinary Function objects matters. SeeFunction objects for more discussion.

API C types§

Duktape API uses typedef-wrapped C types such asduk_int_t,duk_idx_t, andduk_ret_t almost exclusively to ensureportability to exotic platforms. On most platforms these map directly to signedor unsignedint; the wrappers make it possible to support platformswhere usual type assumptions (like having a 32-bitint) don't hold.See Wiki articleAPI C typesfor a detailed discussion.

Summary of best practices:

• Use Duktape API types such asduk_idx_t andduk_ret_t when declaring variables for maximum portability. Alternatively you may use plain types (likelong) but your code will be less portable and you may need to use casts to avoid warnings.
• Inprintf() andduk_push_sprintf() formatting cast Duktape types to a wide integer type and use a standard format specifier. Example:printf("Result: %ld\n", (long) duk_get_int(ctx, -3));.
• Use theL (orUL) suffix for constants which are larger than 16 bits to maximize portability. Like theint type, integer constants without a suffix are only guaranteed to be 16 bits wide. With theL suffix constants are guaranteed to be at least 32 bits wide. Example:duk_push_int(ctx, 1234567L);.

Type algorithms§

This section describes how type-related ECMAScript algorithmslike comparisons and coercions are extended to Duktape custom types.Duktape specific type algorithms (ToBuffer() andToPointer())are also discussed.

Notation§

The following shorthand is used to indicate how values are compared:

Note that Boolean objects, String objects, and Number objects compare as anyother objects instead of being automatically unboxed. For example, non-strictequality compares plain string values with a byte-by-byte comparison, but Stringobjects are compared by object reference (like any other objects).

Equality (non-strict)§

Non-strict equality comparison is specified inThe Abstract Equality Comparison Algorithmfor standard types. Custom type behavior is as follows:

• Buffer: plain buffers are compared by their heap pointer (reference), no content comparison is done. This matches Uint8Array behavior.
• Pointer: comparison against any other type returns false. Comparison to a pointer returns true if and only if the pointer values are the same. Note in particular that comparing a number to a pointer returns false. This seems a bit unintuitive, but numbers cannot represent 64-pointers accurately, comparing numbers and pointers might be error prone.
• Lightfunc: comparison against any other type returns false. Comparison to a lightfunc returns true if and only if both the Duktape/C function pointers and internal control flags (including the "magic" value) match. Note that a lightfunc never compares equal to an ordinary Function object, even when the Function object was created by coercing a lightfunc to an object.

The standard behavior as well as behavior for Duktape custom types is summarized in the table below:

Strict equality§

Strict equality is much more straightforward and preferable wheneverpossible for simplicity and performance. It is described inThe Strict Equality Comparison Algorithmfor standard types. Custom type behavior is as follows:

• Buffer: like non-strict equality.
• Pointer: like non-strict equality.
• Lightfunc: like non-strict equality.

The standard behavior as well as behavior for Duktape custom types is summarized in the table below:

SameValue§

TheSameValue algorithm is not easy to invoke from user code.It is used by e.g.Object.defineProperty() when checking whethera property value is about to change. SameValue is even stricter than astrict equality comparison, and most notably differs in how numbers are compared.It is specified inThe SameValue algorithmfor standard types. Custom type behavior is as follows:

• Buffer: like non-strict (and strict) equality.
• Pointer: like non-strict (and strict) equality.
• Lightfunc: like non-strict (and strict equality).

The standard behavior as well as behavior for Duktape custom types is summarized in the table below:

Type conversion and testing§

The custom types behave as follows for ECMAScript coercions describedType Conversion and Testing(except SameValue which was already covered above):

When a buffer is string coerced it behaves like an Uint8Array, with theresult usually being"[object Uint8Array]". This behavior waschanged in Duktape 2.0. To create a string from buffer contents you can usee.g. the Node.js Buffer binding or the Encoding API.

When a buffer is object coerced a new Uint8Array object is created, witha new ArrayBuffer backing to the plain buffer (no copy is made).

When a lightfunc is coerced with ToPrimitive() it behaves like an ordinaryfunction: it gets coerced withFunction.prototype.toString() withthe result (normally) being the same as ToString() coercion.

When a lightfunc is object coerced, a new Function object is createdand the virtual properties (name andlength andthe internal "magic" value are copied over to the Function object.

Custom coercions (ToBuffer, ToPointer)§

ToBuffer() coercion is used when a value is forced into a buffertype e.g. with theduk_to_buffer() API call. The coercionis as follows:

• A buffer coerces to itself (identity). The same buffer value is returned.
• Any other type (including pointer and lightfunc) is first string coerced withToString, and the resulting string is then copied, byte-by-byte, into a fixed-size buffer.

ToPointer() coercion is used e.g. by theduk_to_pointer()call. The coercion is as follows:

• A pointer coerces to itself.
• Heap-allocated types (string, object, buffer) coerce to a pointer value pointing to theirinternal heap header. This pointer has only a diagnostic value. Note, in particular, that the pointer returned for a buffer or a stringdoes not point to the buffer/string data area. (This coercion is liable to change even in minor versions, avoid relying on it.)
• Any other types (including number) coerce to a NULL pointer.
• Lightfunc coerces to a NULL pointer. This is the case because C function pointers cannot be coerced to avoid * in a portable manner.

The following table summarizes how different types are handled:

Addition§

The ECMAScript addition operator is specified inThe Addition operator (+).Addition behaves specially if either argument is a string: the other argumentis coerced to a string and the strings are then concatenated. This behavioris extended to custom types as follows:

• As for standard types, object values are first coerced withToPrimitive(); plain buffers and lightfuncs are normally coerced withToString(). For plain buffers the result is usually"[object Uint8Array]" and for lightfuncs"[object Function]".
• Pointer values fall into the default number addition case. They are coerced withToNumber() and then added as numbers. NULL pointers coerce to 0, non-NULL pointers to 1, so addition results may not be very intuitive.

Addition is not generally useful for custom types. For example, if two plainbuffers are added, the result is usually"[object Uint8Array][object Uint8Array]",which matches how standard addition behaves for two Uint8Array instances.

Property access§

If a plain buffer or pointer is used as a property access base value,properties are looked up from the (initial) built-in prototype object(Uint8Array.prototype orDuktape.Pointer.prototype).This mimics the behavior of standard types.

For example:

duk> buf = Duktape.dec('hex', '414243');  // plain buffer= ABCduk> buf.subarray();= function subarray() {"native"}duk> typeof buf.toString();= string

Lightfuncs have a few non-configurable and non-writable virtual properties(name andlength) and inherit their remainingproperties fromFunction.prototype, which allows ordinary inheritedFunction methods to be called:

var bound= myLightFunc.bind('dummy',123);

Duktape built-ins§

This section summarizes Duktape-specific and non-ECMAScript built-inobjects, methods, and values.

Additional global object properties§

globalThis§

References the global object itself, seeproposal-global.(The binding was initially named 'global' but this was changed due tosome web sites breaking.).

The Duktape object§

version§

Theversion property allows version-based feature detection andbehavior. Version numbers can be compared directly: a logically higher versionwill also be numerically higher. For example:

if(typeof Duktape!=='object'){print('not Duktape');}elseif(Duktape.version>=20403){print('Duktape 2.4.3 or higher');}elseif(Duktape.version>=10500){print('Duktape 1.5.0 or higher (but lower than 2.4.3)');}else{print('Duktape lower than 1.5.0');}

The value ofversion for pre-releases is one less than theactual release, e.g. 1199 for a 0.12.0 pre-release and 10299 for a 1.3.0pre-release. SeeVersioning.

Remember to check for existence ofDuktape when doing featuredetection. Your code should typically work on as many engines as possible.Avoid the common pitfall of using a direct identifier reference in the check:

// Bad idea: ReferenceError if missingif(!Duktape){print('not Duktape');}// Better: check through 'this' (bound to global)if(!this.Duktape){print('not Duktape');}// Better: use typeof to check also type explicitlyif(typeof Duktape!=='object'){print('not Duktape');}

env§

env summarizes the most important effective compile optionsin a version specific, quite cryptic manner. The format is version specificand is not intended to be parsed programmatically. This is mostly useful fordevelopers (seeduk_hthread_builtins.c for the code which setsthe value).

Example from Duktape 1.1.0:

ll u n p2 a4 x64 linux gcc// l|b|m integer endianness, l|b|m IEEE double endianness// p|u packed/unpacked tval// n|various, memory optimization options (n = none)// p1|p2|p3 prop memory layout// a1|a4|a8: align target// x64|x86|arm|etc: architecture// linux|windows|etc: operating system// gcc|clang|msvc|etc: compiler

For endianness, "l" stands for little endian, "b" for big endian, and "m"for mixed endian (legacy ARM devices, see e.g.The FPA architecture).

fin()§

When called with a single argument, gets the current finalizer of an object:

var currFin= Duktape.fin(o);

When called with two arguments, sets the finalizer of an object (returns undefined):

Duktape.fin(o,function(x){print('finalizer called');});Duktape.fin(o, undefined);// disable

enc()§

enc() encodes its argument value into chosen format.The first argument is a format (currently supported are "hex", "base64","jx" and "jc"), second argument is the value to encode, and any furtherarguments are format specific.

For "hex" and "base64", buffer values are encoded as is, other valuesare string coerced and the internal byte representation (extended UTF-8)is then encoded. The result is a string. For example, to encode a stringinto base64:

var result= Duktape.enc('base64','foo');print(result);// prints 'Zm9v'

For "jx" and "jc" the argument list following the format name is thesame as forJSON.stringify(): value, replacer (optional),space (optional). For example:

var result= Duktape.enc('jx',{ foo:123},null,4);print(result);// prints JX encoded {foo:123} with 4-space indent

dec()§

dec() provides the reverse function ofenc().

For "hex" and "base64" the input value is first string coerced (it onlyreally makes sense to decode strings). The result is always a plain buffer.For example:

var result= Duktape.dec('base64','Zm9v');print(typeof result, result);// prints 'object foo'

If you prefer a fullUint8Array over a plain buffer, you cancoerce the result as follows:

var result=Object(Duktape.dec('base64','Zm9v'));print(typeof result, result);// prints 'object foo'

If you wish to get back a string value, you can coerce the plain buffer toa string e.g. as follows:

// Use TextDecoder which decodes the input as UTF-8.  You can also use// the Node.js Buffer binding to achieve a similar result.var result=newTextDecoder().decode(Duktape.dec('base64','Zm9v'));print(typeof result, result);// prints 'string foo'

For "jx" and "jc" the argument list following the format name is the sameas forJSON.parse(): text, reviver (optional). For example:

var result= Duktape.dec('jx',"{foo:123}");print(result.foo);// prints 123

info()§

Duktape.info() returns an object exposing internal informationrelated to its argument value. Seeduk_inspect_value()for description of current fields.

act()§

Get information about a call stack entry. Takes a single number argumentindicating depth in the call stack: -1 is the top (innermost) entry, -2 is theone below that etc. Returns an object describing the call stack entry, orundefined if the entry doesn't exist. Seeduk_inspect_callstack_entry()for description of current fields.

Example:

functiondump(){var i, t;for(i=-1;; i--){        t= Duktape.act(i);if(!t){break;}print(i, t.lineNumber, t.function.name, Duktape.enc('jx', t));}}dump();

The example, when executed with the command line tool, currently printssomething like:

-1 0 act {lineNumber:0,pc:0,function:{_func:true}}-2 4 dump {lineNumber:4,pc:16,function:{_func:true}}-3 10 global {lineNumber:10,pc:5,function:{_func:true}}

The interesting entries arelineNumber andfunctionwhich provides e.g. the function name.

You can also implement a helper to get the current line number usingDuktape.act():

functiongetCurrentLine(){'use duk notail';/* Tail calls are prevented to ensure calling activation exists.     * Call stack indices: -1 = Duktape.act, -2 = getCurrentLine, -3 = caller     */var a= Duktape.act(-3)||{};return a.lineNumber;}print('running on line:',getCurrentLine());

gc()§

Trigger a forced mark-and-sweep collection. The call takes an optionalinteger flags field, seeduktape.h for constants.

compact()§

Minimize the memory allocated for a target object. Same as the C API callduk_compact() but accessible from ECMAScript code. If called witha non-object argument, this call is a no-op. The argument value is returned bythe function, which allows code such as:

var obj={    foo: Duktape.compact({ bar:123})}

This call is useful when you know that an object is unlikely to gain newproperties, but you don't want to seal or freeze the object in case it does.

errCreate() and errThrow()§

These can be set by user code to process/replace errors when they are created(errCreate) or thrown (errThrow). Both values areinitially non-existent.

SeeError handlers (errCreate and errThrow) fordetails.

Duktape.Pointer (constructor)§

The Pointer constructor is a function which can be called both as anordinary function and as a constructor:

• When called as a function, coerces the first argument to a pointer using the customToPointer coercion. The return value is a plain pointer (not a Pointer object).
• When called as a constructor, coerces the first argument to a pointer using the customToPointer coercion. Returns a Pointer object whose internal value is the pointer resulting from the coercion. The internal prototype of the newly created Pointer will be theDuktape.Pointer.prototype object.

Duktape.Pointer.prototype§

toString() andvalueOf accept both plain pointers andPointer objects as theirthis binding. This allows code such as:

var plain_ptr= Duktape.Pointer({ test:'object'});print(plain_ptr.toString());

Duktape.Thread (constructor)§

The Thread constructor is a function which can be called both as anordinary function and as a constructor. The behavior is the same in bothcases:

• The first argument is checked to be a function (if not, aTypeError is thrown). The function must be an ECMAScript function (bound or non-bound). The return value is a new thread whose initial function is recorded to be the argument function (this function will start executing when the new thread is first resumed). The internal prototype of the newly created Thread will be theDuktape.Thread.prototype object.

Duktape.Thread.prototype§

CBOR§

CBOR (Concise Binary Object Representation) is a compact binary encodingfor arbitrary structured values. It is faster than JSON and can encode someECMAScript values more accurately. It is suitable as an alternative to JSONfor state serialization, IPC, etc. See:

• CBOR — Concise Binary Object Representation (cbor.io)
• Concise Binary Object Representation (CBOR) (RFC 7049)

TheCBOR object provides encode/decode functions to convertarbitrary ECMAScript values to CBOR and vice versa. There's no officialCBOR API yet, so the API is based, for now, oncbor-js.There's also aC API for CBOR.

Example:

var enc= CBOR.encode(['foo','bar',{ quux:true}]);print(Duktape.enc('hex', enc));// = 8363666f6f63626172a16471757578f5var dec= CBOR.decode(enc);print(Duktape.enc('jx', dec));// = ["foo","bar",{quux:true}]

TextEncoder§

TextEncoder() is part of theWHATWG Encoding APIand provides a clean way of encoding a string into a buffer (Uint8Array)using UTF-8 encoding. Surrogate pairs are combined during the process.For example:

var str='\u{1f4a9}';// non-BMP codepointprint(str.length);// length is 2, represented as a surrogate pairvar u8=newTextEncoder().encode(str);print(u8.length);// length is 4, a single UTF-8 codepointprint(Duktape.enc('jx', u8));// |f09f92a9|, UTF-8 bytes F0 9F 92 A9

TextDecoder§

TextDecoder() is part of theWHATWG Encoding APIand provides a clean way of decoding a buffer into a string using UTF-8encoding. Non-BMP codepoints are represented as surrogate pairs in theresulting string. For example:

var u8=newUint8Array([0xf0,0x9f,0x92,0xa9]);// a single non-BMP codepointvar str=newTextDecoder().decode(u8);print(str.length);// length is 2, represented as a surrogate pairprint(str.charCodeAt(0));// 55357, high surrogateprint(str.charCodeAt(1));// 56489, low surrogate

performance§

performance.now() provides a monotonic time in milliseconds (includingfractions if available) from an unspecified origin. The return value isfrom DUK_USE_GET_MONOTONIC_TIME() with a fallback to DUK_USE_DATE_GET_NOW().If an actual monotonic time provider is available, the return value isguaranteed to advance in real time without "time jumps" caused by date/timeadjustments. This is useful for performance measurement, scheduling eventsrelative to current time instead of wall clock time, rate limiting, etc.Example:

functiontestFunction(){for(var i=0; i<1e6; i++){}}var t1= performance.now();testFunction();var t2= performance.now();print('test took:',(t2- t1),'milliseconds');

performance.timeOrigin is currently (Duktape 2.2.0) absent on purpose,until its semantics for Duktape are decided.

Navigation Timingbindings like performance.timing are not currently supported.

Post-ES5 features§

Duktape implements features from ES2015 (ES6), ES2016 (ES7), and laterspecification drafts. See Wiki articlePost-ES5 featuresfor current status.

Duktape status is also updated for new releases inkangax/compat-table.

Custom behavior§

This section summarizes Duktape behavior which deviates from the E5.1 orother relevant specifications.

Duktape built-in and custom types§

TheDuktape built-in is (of course) non-standard and providesaccess to Duktape specific features. Also the buffer, pointer, and lightfunctypes are custom.

Hidden Symbols§

Objects may have properties withhidden Symbol keys.These are similar to ES2015 Symbols but won't be enumerated or returned from evenObject.getOwnPropertySymbols(). Ordinary ECMAScript code cannotrefer to such properties because the keys intentionally use an invalid (extended)UTF-8 representation.

"use duk notail" directive§

The"use duk notail" directive is non-standard.It prevents a function from being tail called.

"const" treated mostly like "var"§

Theconst keyword is supported with minimal non-standardsemantics (officially defined in ECMAScript 6). SeeConst variables for more detail.

Additional Error and Function object properties§

SeeError objects andFunction objects.

Non-strict function instances don't have acaller property in theE5/E5.1 specification. Some real world code expects to have this property, so itcan be enabled with the config optionDUK_USE_NONSTD_FUNC_CALLER_PROPERTY.

Function statements§

E5.1 does not allow a function declaration to appear outside program orfunction top level:

functiontest(){// point Atry{thrownewError('test');}catch(e){// This is a SyntaxError in E5.1functionfunc(){print(typeof e);}// point B}// point C}

These declarations are also referred to as "function statements", and appearquite often in real world code (including the test262 test suite), so they areallowed by Duktape. Unfortunately there are several semantics used by differentJavascript engines (ES2015unfortunately doesn't specify semantics for function statements either).Duktape follows the V8 behavior for function statements:

• Strict function: a SyntaxError is thrown (standard behavior).
• Non-strict function: treat a function statement like an ordinary function declaration, conceptually "hoisting" it to the top of the function.

As an illustration, the above example would behave as the following:

functiontest(){functionfunc(){print(typeof e);}try{thrownewError('test');}catch(e){}}

func() in the above example would already be declaredand callable in point A, and would not have access to theebinding in any of the points A, B, or C.

RegExp leniency§

Most ECMAScript engines support more syntax than guaranteed by theECMAScriptE5.1 specification (Section 15.10.1 Patterns). As a result there's quitea lot of code that won't work with strict ECMAScript E5.1 regexp syntax. Muchof the additional syntax expected of web browser engines is documented inES2015 Annex B.1.4 Regular Expression Patterns.However, note that features inAnnex B Additional ECMAScript Features for Web Browsers arenot recommended for new code:"These features are not considered part of the core ECMAScript language.Programmers should not use or assume the existence of these features andbehaviours when writing new ECMAScript code. ECMAScript implementationsare discouraged from implementing these features unless the implementationis part of a web browser or is required to run the same legacy ECMAScriptcode that web browsers encounter."

Duktape also allows some ES2015 Annex B syntax to better support existingcode. You can turn this non-standard behavior off using config options ifyou prefer. Some examples of additional syntax supported:

  /{(\d+)}/    // unescaped left curly, digits, unescaped right curly; ES2015 Annex B  /\{(\d+)\}/  // same, ES5 compliant  /]/          // unescaped right bracket; ES2015 Annex B  /\]/         // same, ES5 compliant  /\$/         // literal dollar using escape; ES2015 Annex B  /\u0024/     // same, ES5 compliant

Setter/getter key argument§

ECMAScript standard behavior is that setters and getters are not giventhe name of the property being accessed. This prevents reusing a singlesetter or a getter for multiple properties; separate functions are neededfor each property which is sometimes inconvenient and wastes memory.

Duktape provides the property key name as a non-standard additionalargument to setter and getter functions. Seetest-dev-nonstd-setget-key-argument.jsandProperty virtualizationfor more discussion. The strict standards compliant behavior can be enabledby disabling the config optionsDUK_USE_NONSTD_GETTER_KEY_ARGUMENTandDUK_USE_NONSTD_SETTER_KEY_ARGUMENT.

Object.setPrototypeOf and Object.prototype.__proto__ (ES2015)§

SeeObject.setPrototypeOf and Object.prototype.__proto__.

Proxy object (ES2015)§

SeeProxy object (subset).

JSON.stringify() escapes U+2028 and U+2029§

JSON.stringify() standard behavior is to output U+2028 andU+2029 without escaping. This leads to counterintuitive behavior when theoutput is used in a web page or parsed witheval(): the U+2028and U+2029 characters are considered line terminators which leads to a syntaxerror (unterminated string). Duktape escapes U+2028 and U+2029 by defaultto avoid this issue; you can turn on the compliant behavior by disabling theconfig optionDUK_USE_NONSTD_JSON_ESC_U2028_U2029.

String.fromCharCode() accepts 32-bit codepoints§

String.fromCharCode() standard behavior is to use ToUInt16()coercion for codepoint values. Duktape uses ToUint32() by default to bettersupport non-BMP strings. You can force the compliant behavior by disablingthe config optipnDUK_USE_NONSTD_STRING_FROMCHARCODE_32BIT.

Array instance numeric index writes§

By default Duktape provides a fast path for writing to Array instances.The fast path is active when numeric indices are used (e.g.arr[7] = 'foo')and a few internal conditions are met. When the fast path is taken, Duktapedoesn't check Array.prototype for conflicting properties (these are very rare inpractical code), which makes common array writes faster. The behavior isnon-compliant, but there's no outward difference unless Array.prototype hasproperties with numeric keys. You can turn on the compliant behavior bydisaling the config optionsDUK_USE_NONSTD_ARRAY_WRITE andDUK_USE_ARRAY_PROP_FASTPATH. See the following for moredetails on the fast path behavior:test-misc-array-fast-write.js.

TypedArray binding§

Duktape provides the ES2015 TypedArray binding, with some details yetto be fixed, e.g. small differences in argument coercion e.g. for offsetand length values.

The plain buffer custom type behaves mostly like an Uint8Array objectfor ECMAScript code, but has a separate type in the Duktape C API.

Node.js Buffer binding§

Duktape provides a Node.js-likeBuffer binding. There aresome differences between the Node.js behavior and Duktape behavior. Thesedifferences include:

• Interoperability with other buffer types: ArrayBuffer, DataView, or a typed array (Uint8Array etc) is usually allowed wherever a Node.js Buffer would be allowed.
• Buffer data is always zeroed on allocation and when concatenationtotalLength exceeds combined size of input buffers.
• Read/write offset and length arguments are always validated to ensure memory safe behavior, even whennoAssert is true. Failed reads return NaN and failed writes return 0.
• Partial read/writes are never done: if a read/write is partially outside the valid buffer, it is rejected.
• Small differences in argument coercion for e.g. offset and length values.
• Write calls coerce their value argument like TypedArray, e.g. when writing 0x100 usingwriteUInt8() silently coerces to 0x00 rather than throwing a TypeError.
• Duktape only supports the"utf8" encoding (and accepts no spelling variants). Most API calls ignore an encoding argument, and use UTF-8 implicitly for string-to-buffer coercion.
• UTF-8 decoding replacement character approach followsUnicode Technical Committee Recommended Practice for Replacement Characters which matches WHATWG Encoding API specification but differs from Node.js (at least up to version v6.9.1).

Shebang comment support§

duk_compile() flagDUK_COMPILE_SHEBANG allows shebangcomment parsing:#! on the first column of the first line causes theline to be treated as a comment. For example:

#!/usr/bin/dukprint('Hello world!');

The feature can be disabled by undefiningDUK_USE_SHEBANG_COMMENTS.

Custom JSON formats§

ECMAScript JSON shortcomings§

The standard JSON format has a number of shortcomings when used withECMAScript:

• undefined and function values are not supported
• NaN and infinity values are not supported
• Duktape custom types are, of course, not supported
• Codepoints above BMP cannot be represented except as surrogate pairs
• Codepoints above U+10FFFF cannot be represented even as surrogate pairs
• The output is not printable ASCII which is often inconvenient

These limitations are part of the ECMAScript specification whichexplicitly prohibits more lenient behavior. Duktape provides two moreprogrammer friendly custom JSON format variants:JX andJC,described below.

Custom JX format§

JX encodes all values in a very readable manner and parses backalmost all values in a faithful manner (function values being the mostimportant exception). Output is pure printable ASCII, codepoints aboveU+FFFF are encoded with a custom escape format, and quotes around objectkeys are omitted in most cases. JX is not JSON compatible but a veryreadable format, most suitable for debugging, logging, etc.

JX is used as follows:

var obj={ foo:0/0, bar:[1, undefined,3]};print(Duktape.enc('jx', obj));// prints out: {foo:NaN,bar:[1,undefined,3]}var dec= Duktape.dec('jx','{ foo: 123, bar: undefined, quux: NaN }');print(dec.foo, dec.bar, dec.quux);// prints out: 123 undefined NaN

Custom JC format§

JC encodes all values into standard JSON. Values not supported bystandard JSON are encoded as objects with a marker key beginning with anunderscore (e.g.{"_ptr":"0xdeadbeef"}). Such values parseback as ordinary objects. However, you can revive them manually more orless reliably. Output is pure printable ASCII; codepoints above U+FFFFare encoded as plain string data with the format "U+nnnnnnnn"(e.g.U+0010fedc).

JC is used as follows:

var obj={ foo:0/0, bar:[1, undefined,3]};print(Duktape.enc('jc', obj));// prints out: {"foo":{"_nan":true},"bar":[1,{"_undef":true},3]}var dec= Duktape.dec('jc','{ "foo": 123, "bar": {"_undef":true}, "quux": {"_nan":true} }');print(dec.foo, dec.bar, dec.quux);// prints out: 123 [object Object] [object Object]

The JC decoder is essentially the same as the standard JSON decoderat the moment: all JC outputs are valid JSON and no custom syntax is needed.As shown in the example, custom values (like{"_undef":true})arenot revived automatically. They parse back as ordinary objectsinstead.

Codepoints above U+FFFF and invalid UTF-8 data§

All standard ECMAScript strings are valid CESU-8 data internally, sobehavior for codepoints above U+FFFF never poses compliance issues. However,Duktape strings may containextended UTF-8codepoints and may even contain invalid UTF-8 data.

The Duktape JSON implementation, including the standard ECMAScript JSON API,use replacement characters to deal with invalid UTF-8 data. The resultingstring may look a bit odd, but this behavior is preferable to throwing anerror.

JSON format examples§

The table below summarizes how different values encode in eachencoding:

Limitations§

Some limitations include:

• Only enumerable own properties are serialized in any of the formats.
• Array properties (other than the entries) are not serialized. This would be useful in e.g. logging, e.g. as[1,2,3,"type":"point"].
• Array gaps are not preserved, and parse back asundefined.
• There is no automatic revival of special values when parsing JC data.
• There is no canonical encoding. This would be easy to arrange with a simple option to sort object keys during encoding.

(See internal documentation for more future work issues.)

Custom directives§

ECMAScript E5/E5.1 employs adirective prologueto allow version or implementation specific features be activated.The standard only provides one such directive,"use strict", whileasm.js uses"use asm". Duktape custom directives are discussedin this section.

use duk notail§

Theuse duk notail directive indicates that the function shouldnever be tail called. Tail calls affect the call stack so they are visible instack traces (usually harmless) and affect functions which inspect the call stackusing e.g.Duktape.act(). This directive may be useful in specialcases to ensure call stack has a known shape. Example:

functionnoTailCall(){'use duk notail';// ...}

Native functions are never tailcalled, so a corresponding declaration is notnecessary for them.

Buffer objects§

Overview of buffer types§

Duktape provides the following buffer and buffer-related types:

Seebuffers.rstfor a detailed discussion, including adetailed table of buffer types and their properties.

Plain buffers§

Plain buffers are a non-standard memory efficient way of representingbuffer data. Plain buffers mimic Uint8Array objects so that they inheritfromUint8Array.prototype, are accepted as typed arrayconstructor arguments, and so on. While plain buffers don't have a propertytable and can't hold properties of their own, they have the followingvirtual or inherited properties (example values are for a 24-byte buffer):

Buffer objects like ArrayBuffer and Node.js Buffer are implemented on topof plain buffer values and provide additional functionality like view/slicesupport, typed accessors, and methods to manipulate data in different endianness.However, they have more overhead than plain buffers.

For more details, see:

• How to work with buffers
• Type algorithms
• buffers.rst

Working with buffers§

Buffer values work in both C and ECMAScript code:

• For ECMAScript code most of the behavior is defined in the relevant API standards, with exceptions for Duktape-specific features like mixing different buffer types.
• For C code there are API calls to work withplain buffers andbuffer objects.

SeeHow to work with buffersfor examples.

Current limitations§

• SeeTypedArray binding custom behavior.
• SeeNode.js Buffer binding custom behavior.

Error objects§

Property summary§

ECMAScript Error objects have very few standard properties, so manyECMAScript implementations have added quite a few custom properties.Duktape uses standard Error properties but also borrows the most usefulproperties used by other implementations. The number of "own" propertiesof error objects is minimized to keep error objects as small as possible.

Error objects have the following properties (mostly inherited):

If Duktape is compiled with traceback support:

• stack,fileName, andlineNumber are accessor properties inherited fromError.prototype. You can override the properties by simply assigning over them: an inherited setter will capture the write but will create an own property as if a normal assignment was done. This behavior was changed in Duktape 1.4.0 to better match other engines.
• The raw traceback data needed by the accessor properties is stored in an internal property (\x82Tracedata) which is not normally accessible from ECMAScript code.

If Duktape is compiled without traceback support:

• Thestack accessor will be equivalent toError.prototype.toString(), so that printing the stacktrace always produces a useful, human readable result.
• fileName andlineNumber will be own properties of the Error object. You can override the properties using assignment.

When error objects are created using the Duktape API from C code and thecaller does not give a format string for amessage, themessageproperty is set to a numeric error code given in the API call. The type ofmessage will be number in this case; normally error messages arestrings. In minimized Duktape builds all errors generated internally byDuktape use numeric error codes only.

An object is considered an "error object" if its internal prototypechain contains the (original)Error.prototype object. Onlyobjects matching this criteria get augmented with e.g. traceback data.

Traceback§

Thestack property is an accessor (setter/getter) propertywhich provides a printable traceback related to an error. The tracebackreflects the call stack when the error object was created (not thrown).Traceback data is automatically collected and added to an object:

• when an Error instance is constructed;
• when an error is thrown from C code using the Duktape API;
• when an error is thrown from inside Duktape.

The data used to create the traceback is stored in an internal property(\x82Tracedata), in an internal and version-dependent formatdescribederror-objects.rst.You shouldn't access the traceback data directly.

The printable traceback format is intended to be human readable only.You shouldn't rely on an exact traceback format as it may change betweenversions (for example,tracebacks were improved for the 1.5.0 release).As an example of the current traceback format, the program:

// shortened from tests/ecmascript/test-dev-traceback-example.jstry{decodeURIComponent('%e1%a9%01');// invalid utf-8}catch(e){print(e.stack);}

would print something like:

URIError: invalid input    at [anon] (duk_bi_global.c:343) internal    at decodeURIComponent () native strict preventsyield    at global (test.js:3) preventsyield

In builds where tracebacks are disabled, thestack accessorwill return the same value as callingtoString() on the errorwould. This means you can always printe.stack and get a usefuloutput.

The most portable traceback printing approach is something like:

try{decodeURIComponent('%e1%a9%01');// invalid utf-8}catch(e){// Print stacktrace on at least Duktape and V8, or a standard error// string otherwise.print(e.stack|| e);}

An attempt to write tostack is captured by an inheritedsetter which will create an own property as if a normal assignment was done.This behavior differs from V8 wherestack is an own propertyof the Error instance.

Error handlers (errCreate and errThrow)§

IfDuktape.errCreate has been set, it is called right afterDuktape has added traceback information to an object, and can process theerror further or even replace the error value entirely. The error handleronly gets called withError instances, and its return value isused as the final error value. If the error handler throws an error, thaterror replaces the original error. The error handler is usually called only onceper error. However, in corner cases related to constructors, the error handlercan be called multiple times for a single error value.

An error handler should avoid overwriting any properties alreadypresent in an object, as that would be quite confusing for other code.In general, an error handler should always avoid throwing an error, as thaterror replaces the original error and would also be confusing. As a specificexample, an error handler must not try to add a new property to a non-extensibleobject, as that would cause aTypeError.

Below is an example error handler for adding a creation timestamp toerrors at their creation:

Duktape.errCreate=function(e){if(!(einstanceof Error)){// this check is not really needed because errCreate only gets// called with Error instancesreturn e;}if('created'in e){// already augmented or conflicting property presentreturn e;}if(!Object.isExtensible(e)){// object not extensible, don't try to add a new propertyreturn e;}    e.created=newDate();return e;}

To remove the handler, delete the property (setting it to e.g.nulldoes not work and causes aTypeError when Duktape attempts tocall thenull value):

// Remove error handler for error creationdelete Duktape.errCreate;

Similarly, ifDuktape.errThrow has been set, it is calledright before an error is thrown, and can process or replace the error value.Because ECMAScript allows any value type to be thrown, the error handlermay get called with arbitrary input values (not justErrorinstances). It may also be called more than once for the same value becausean error can be re-thrown multiple times.

For example, to add a throw timestamp (recording the first time the objecthas been thrown) to errors:

Duktape.errThrow=function(e){if(!(einstanceof Error)){// refuse to touch anything but Error instancesreturn e;}if('thrown'in e){// already augmented or conflicting property presentreturn e;}if(!Object.isExtensible(e)){// object not extensible, don't try to add a new propertyreturn e;}    e.thrown=newDate();return e;}

Again, to remove the handler, delete the property:

// Remove error handler for error throwingdelete Duktape.errThrow;

Current limitations§

• There is no cause chain support. Cause chains would be useful but there are no cause chains in ECMAScript, nor does there seem to be a de facto standard for them.
• These is currently no way to access traceback elements programmatically in a version compatible manner. However, you can access the_Tracedata hidden Symbol (DUK_HIDDEN_SYMBOL("Tracedata") from C code), but the raw tracedata format may change even in minor versions. You can also overwrite the.stack property directly.
• If an error is created with a non-constructor function call to a custom error class (MyError('msg') instead ofnew MyError('msg')) it won't get augmented with custom fields such as traceback data. When called as a constructor custom errors inheriting fromError get augmented normally. Built-in standard errors (likeTypeError) always get augmented, even when created with a non-constructor function call (the tracebacks look slightly different depending on how the error is created, though).

Function objects§

ECMAScript functions§

Duktape Function objects add a few properties to standard ECMAScriptproperties. The table below summarizes properties assigned to newlycreated function instances (properties can of course be added or removedafterwards):

Thename property is assigned to all functions and is alsothe name used in tracebacks. It is assigned as follows:

functionfuncDecl(){/* Function declaration: 'name' is declaration name, here 'funcDecl'. */}var foo=functionnamedFunc(){/* Named function expression: 'name' is the name used in expression,     * here 'namedFunc' (not 'foo').     */}var bar=function(){/* Anonymous function expression: 'name' is the empty string. */}

Duktape/C functions§

User-created Duktape/C functions (duk_push_c_function()) havea different set of properties to reduce Function object memory footprint:

Note in particular that the standardprototype,caller,andarguments properties are missing by default. This is not strictlycompliant but is important to reduce function footprint. User code can of courseassign these properties but is not required to do so.

There's also no (non-standard)name property. Setting it manuallyis useful because it affects how a function appears in tracebacks.

Lightweight Duktape/C functions§

Lightweight Duktape/C functions (lightfuncs) are a very memory efficient wayof representing a native function in the ECMAScript environment. Lightfuncsdon't have a property table so they can't hold properties. However, they inheritfromFunction.prototype and have the following virtual properties(which are non-configurable and non-writable):

Thename property is an automatically generated virtualfunction name. <PTR> is a platform dependent dump of the Duktape/Cfunction pointer, and <FLAGS> is a raw hex dump of the 16-bit internalcontrol fields (the format is Duktape internal). You shouldn't rely on aspecific format. For example:

duk> print(myLightFunc.name);light_0805b94c_0511

As for ordinary functions, a lightfunc coerces to an implementationdependent string. You shouldn't rely on a specific format. For example:

duk> print(myLightFunc);function light_0805b94c_0511() {"light"}

For more details, see:

• How to work with lightfuncs
• Type algorithms
• lightweight-functions.rst

Date and time§

Date and time handling is often a portability issue when adapting Duktapeto more exotic environments. Theduk_config.h configurationheader selects platform specific providers needed to implement theDate built-in. Duktape has built-in providers for mainstreamplatforms (Linux, Windows, OS X) which should usually work without changes.You can also write anexternal Date providerfor more exotic environments. An external Date provider can also be used e.g.when a time offset needs to be applied to the platform time, or when usingtime virtualization.

ECMAScript code interacts with date/time through the standardDate built-in which is, by specification, limited to millisecondresolution. There are currently no Duktape specific ECMAScript date/time APIs.(A custom API may be added later to deal with sub-millisecond resolution.)

C code can of course use platform date/time APIs directly, but the DuktapeC API also provides date/time API calls. These calls see the same time valuesas ECMAScript code which may matter when e.g. time virtualization is used.Using these calls makes your code platform neutral and thus more portable.The Duktape C API allows sub-millisecond resolution for time values. SeeHow to work with time valuesfor more details.

Random numbers§

Random numbers are used internally forMath.random().They are also used currently for random pivot selection in theArray.prototype.sort() implementation.

The default internal random number generator isxoroshiro128+ withSplitMix64 seed mixing.Shamir's three-op PRNGis used on low memory targets and when the compiler doesn't have 64-bittypes. The generators are not suitable for serious statistics algorithmsdue to e.g. limited quality of the seed material, and are not at allsuitable for cryptography.

You can replace the internal random number generator using theDUK_USE_GET_RANDOM_DOUBLE config option.

Debugger§

Duktape has built-in debugger support as an option you can enable duringcompilation. Debugger support adds about 15-20kB of code footprint (dependingon what debugger features are enabled) and has very minimal memory footprint.Debugger features include:

• Execution status information such as running/paused at file/line, callstack, local variables for different callstack levels
• Execution control including pause/resume, step over/into/out, breakpoints targeted at file/line, debugger statement
• Generic Eval at any callstack level, get/put variable at any callstack level
• A mechanism for application-defined requests (AppRequest) and notifications (AppNotify)
• Heap object in-depth inspection, Duktape heap walking, and getting a full heap dump

The debugger is based on the following main concepts:

• Duktape provides a built-indebug protocol which is the same for all applications. The application doesn't need to parse or understand the debug protocol. The debug protocol is a compact binary protocol so that it works well on low memory targets with low speed connectivity. There is aJSON mapping for the debug protocol and aJSON debug proxy to make it easier to integrate a debug client.
• The debug protocol runs over a reliable, stream-baseddebug transport. To maximize portability, the concrete transport is provided by application code as a set of callbacks implementing a stream interface. A streamed transport allows unbuffered streaming of debug messages, which keeps memory usage very low.
• Adebug client terminates the transport connection and uses the Duktape debug protocol to interact with Duktape internals: pause/resume, stepping, breakpoints, eval, etc. You can also use the JSON debug proxy for easier integration.
• A very narrowdebug API is used by the application code to attach and detach a debugger, and to provide the callbacks needed to implement the debug transport. All other debug activity happens through the debug protocol which is implemented by Duktape directly with no application involvement.

The most appropriate debug transport varies a lot between debug targets;it can be Wi-Fi, Bluetooth, a serial line, a stream embedded into a custommanagement protocol, etc. Although there is no "standard" transport, a TCPconnection is a useful default. The Duktape distributable includes all thepieces you need to get started with debugging using a TCP transport:

• An example implementation of the callbacks needed for a TCP transport:duk_trans_socket_unix.c (there's also a Windows example)
• Debugger support for the Duktape command line tool (duk) using the TCP transport:--debugger option
• A debugger web UI based onNode.js,Express, andsocket.io:duk_debug.js

The Node.js based debugger web UI (duk_debug.js) can connectto the Duktape command line, but can also talk directly with any other targetimplementing a TCP transport. You can also customize it to use a differenttransport or use a proxy which converts between TCP and your custom transport.It's also possible to write your own debug client from scratch and e.g.integrate it to a custom IDE. You can integrate directly with a debug targetusing the binary debug protocol, or use the JSON proxy provided byduk_debug.js(Node.js) orduk_debug_proxy.js(DukLuv).

Debug targets and debug clients are intended to be mixed and matched:apart from the transport (which is usually either TCP or easy to adapt) thedebug protocol is the same. Core functionality will be the same regardlessof the debug client or the debug target, but some optional features may bemissing. Debug clients and debug targets may also implement applicationspecific commands (AppRequest) and notifications (AppNotify) for richerintegration which can be used when both the client and the target supportthem (they're easy and safe to ignore if not supported). Custom commandsand notifications allow e.g. downloading of source files directly from thetarget, deep inspection of the state of a custom memory allocator, rebootingthe target on command, etc.

For more details on the implementation and how to get started, see:

• debugger/README.rst
• debugger.rst
• duk_trans_dvalue.c: example debug transport with local debug protocol decoding/encoding
• duk_debug_proxy.js

Modules§

CommonJS module loading frameworks§

There's no built-in module loading framework because it's difficult for asingle framework to match a wide variety of different module loading use cases.The Duktape distributable includes several optional module loader frameworks,for example:

You can also implement your own module loader from scratch: the aboveloaders are implemented using the Duktape public API with no special accessto internals.

The module loaders provide arequire() function which allowsmodules to be loaded as follows:

var mod=require('foo/bar');mod.hello();

The loaders abstract actual module resolution/loading to user-provided hook(s)to allow the loader to be embedded in wide variety of environments. For example:

• Module loading can be used in environments with no file system by loadingmodules from a set of virtual built-in files.
• On-the-fly transpiling can be done during loading, for example usingBabel.

ES2015 modules§

There's currently no support for ES2015 import/export and ES2015 modules.

C module convention§

There's a recommended (but not mandatory) C module convention which allowsC modules to be loaded and initialized from DLLs:c-module-convention.rst.

Logging§

The Duktape distributable includes alogging frameworkwith a small footprint, reasonable performance, and redirectable output. The frameworkwas a built-in in Duktape 1.x but was moved into an optional extra in Duktape 2.x.

Basic usage example:

var val1='foo';var val2=123;var val3=newDate(123456789e3);var logger=new Duktape.Logger();// or new Duktape.Logger('logger name')logger.info('three values:', val1, val2, val3);

The example would print something like the following tostderr:

2014-10-17T19:26:42.141Z INF test.js: three values: foo 123 1973-11-29 23:33:09.000+02:00

See the Wiki articleHow to use logging andlogging.rstfor more details.

Finalization§

Overview§

Duktape supports object finalization as a custom feature. A finalizeris called when an object is about to be freed, so that application codecan e.g. free native resources associated with the object. The finalizercan be either an ECMAScript function or a Duktape/C function. However,ECMAScript finalizers may interact badly with script timeouts, see below.

SeeHow to use finalizationfor examples.

Getting and setting the current finalizer§

An object which has an internal_Finalizer property in itsprototype chain (or in the object itself) is subject to finalization beforebeing freed. The internal property should not be accessed directly, but canbe read/written using the following:

• Duktape.fin(obj) (ECMAScript) orduk_get_finalizer() (C) gets the current finalizer.
• Duktape.fin(obj, fn) (ECMAScript) orduk_set_finalizer() (C) sets the current finalizer.

Finalizer function arguments and return value§

The finalizer function is called with two arguments:

• The object being finalized.
• A boolean flag indicating if the object is being forcibly freed as part of heap destruction. This argument was added in Duktape 1.4.0:
  • Iffalse (normal case), the finalizer may rescue the object by creating a live reference to the object before returning and the finalizer is guaranteed to be called again later (heap destruction at the latest).
  • Iftrue (forced finalization in heap destruction), the object cannot be rescued and will be forcibly freed after the finalizer finishes. Native resources should be freed without expecting any further calls into the finalizer.

The return value of a finalizer is ignored. Any errors thrown by thefinalizer are also silently ignored.

Finalizer execution guarantees§

The main finalizer guarantees are:

• Finalizers are executed for unreachable objects detected by reference counting or mark-and-sweep. The finalizer may not execute immediately, however, not even when reference counting detects that the object became unreachable.
• Finalizers are also executed for all remaining objects, regardless of their reachability status, when a Duktape heap is destroyed.
• A finalizer is called exactly once, at the latest when the heap is destroyed, unless the object is rescued by making it reachable again. An object may be rescued by its own finalizer, or by another object's finalizer when mark-and-sweep finalizes a set of objects. For example, ifX.ref = Y, and both X and Y become unreachable, it's possible for Y's finalizer to run, and later on X's finalizer to rescue both X and Y.
• An object may be rescued an arbitrary number of times; the finalizer is called exactly once for each "rescue cycle". Even with this guarantee in place, it's best practice for a finalizer to be re-entrant and carefully avoid e.g. freeing a native resource multiple times if re-entered.
• A finalizer is not executed for a Proxy object, but is executed for the plain target object. This ensures that a finalizer isn't executed multiple times when Proxy objects are created.

Together these guarantee that a finalizer gets executed at some pointbefore a heap is destroyed, which allows native resources (such as socketsand files) to be freed reliably. There are a few exceptions to this guarantee,see below for more discussion:

• Heap destruction finalizer sanity limit may cause a finalizer not to be executed.
• When a script timeout is being propagated out of the current callstack, ECMAScript finalizers will immediately rethrow the script timeout error. Duktape/C finalizers will execute normally.
• If Duktape runs out of memory (despite emergency GC) when trying to call a finalizer, the call error is silently ignored and the finalizer will be skipped.
• When an object is finalized by mark-and-sweep but becomes unreachable before the next mark-and-sweep round has a change to detect the rescue, the object's finalizer will not be executed.

When the Duktape heap is being destroyed there are a few limitations forfinalizer behavior:

• Finalizers are executed for all finalizable objects in the heap, including reachable objects.
• Finalizers cannot rescue objects; the semantics for a "rescue" would be ambiguous. The finalizer's second argument istrue when called during heap destruction to indicate rescue is not possible.
• A finalizer can create new finalizable objects and these objects will also be finalized. For example, a finalizer may post a HTTP notification of an object destruction which may use native network resources with their own finalizers. However, there's a sanity limit to this process to ensure runaway finalizers cannot prevent a heap from being destroyed.
• The finalizer sanity algorithm is version specific, seeHow to use finalization. The algorithm allows the number of finalizable objects to grow initially, but it must decrease in a reasonable time or the finalization process is aborted, which may cause some native resource leaks.

Other current limitations§

• When script execution timeout(DUK_USE_EXEC_TIMEOUT_CHECK)is used and a timeout occurs, it's possible for an ECMAScript finalizer to startrunning but immediately fail due to a script timeout. If this is a concreteconcern, use a Duktape/C native finalizer instead which will run normally evenwhen propagating a timeout.
• The context (Duktape thread) executing the finalizer can currently be any coroutine in the heap. This must be taken into account in sandboxing.
• Finalizers cannot currently yield.

Coroutines§

Duktape has a support for simple coroutines. Execution is strictly nesting:coroutine A resumes or initiates coroutine B, coroutine B runs until it yieldsor finishes (either successfully or through an uncaught error), after whichcoroutine A continues execution with the yield result.

Coroutines are created withnew Duktape.Thread(), which gets as itssole argument the initial function where the new coroutine begins execution onits first resume. The resume argument becomes the initial function's first (andonly) argument value.

A coroutine is resumed usingDuktape.Thread.resume() which takes thefollowing arguments: the coroutine to resume, the resume value, and (optionally)a flag indicating whether the resume value is an ordinary value or an error tobe injected into the target coroutine. Injecting an error means that the resumevalue will be "thrown" at the site of the target coroutine's last yield operation.In other words, instead of returning with an ordinary value, the yield willseemingly throw an error.

A coroutine yields its current execution usingDuktape.Thread.yield()which takes as its arguments: the value to yield, and (optionally) a flag indicatingwhether the yield value is an ordinary value or an error to be thrown in thecontext of the resuming coroutine. In other words, an error value causes theresume operation to seemingly throw an error instead of returning an ordinaryvalue.

If a coroutine exists successfully, i.e. the initial function finishes byreturning a value, it is handled similarly to a yield with the return value.If a coroutine exists because of an uncaught error, it is handled similarlyto a yield with the error: the resume operation will rethrow that error inthe resuming coroutine's context. In either case the coroutine which hasfinished can no longer be resumed; attempt to do so will cause a TypeError.

There are currently strict limitations on when a yield is possible.In short, a coroutine can only yield if its entire active call stack consistsof plain ECMAScript-to-ECMAScript calls. The following prevent a yield ifthey are present anywhere in the yielding coroutine's call stack:

• a Duktape/C function call
• a getter/setter call
• a proxy trap call
• aneval() call
• a finalizer call

SeeHow to use coroutinesfor examples.

Virtual properties§

Duktape provides two mechanisms for interacting with property accessesprogrammatically:

• Accessor properties (setters and getters)
• TheProxy object

SeeHow to use virtual propertiesfor examples.

Symbols§

Duktape supports ES2015 Symbols and also provides a Duktape specifichidden Symbol variant similar to internal strings in Duktape 1.x.Hidden Symbols differ from ES2015 Symbols in that they're hidden fromordinary ECMAScript code: they can't be created from ECMAScript code,won't be enumerated or JSON-serialized, and won't be returned fromObject.getOwnPropertyNames() or evenObject.getOwnPropertySymbols(). Properties with hidden Symbolkeys can only be accessed by a direct property read/write when holding areference to the hidden Symbol.

Symbols of all kinds are represented internally using invalid UTF-8 bytesequences, seesymbols.rstfor the current formats in use. Application hidden Symbols begin with a 0xFFbyte prefix and are followed by an arbitrary, application selected string. WhenC code pushes a string using e.g.duk_push_string() and the bytesequence matches an internal Symbol format, the string value is automaticallyinterpreted as a Symbol.

Duktape also uses hidden Symbols for various implementation specific purposes,such as storing an object's finalizer reference. As of Duktape 2.2 a differentbyte prefix is used for Duktape's hidden Symbols, so the 0xFF prefix is nowreserved entirely for application use. Application code should never try toaccess Duktape's hidden Symbol keyed properties: the set of such properties canchange arbitrarily between versions.

Creating a Symbol is straightforward from C code:

/* Create a hidden Symbol which can then be used to read/write properties. * The Symbol can be passed on to ECMAScript code like any other string or * Symbol. */duk_push_string(ctx,DUK_HIDDEN_SYMBOL("mySymbol"));

Before Duktape 2.2DUK_HIDDEN_SYMBOL() and other symbolliteral macros were not available and the internal representation would beused directly:

/* Terminating a string literal after a hex escape is safest to avoid some * ambiguous cases like "\xffab".  For more discussion, see: *https://github.com/svaarala/duktape/blob/master/misc/c_hex_esc.c */duk_push_string(ctx,"\xff""mySymbol");

Hidden Symbols cannot be created from ECMAScript code using the defaultbuilt-ins alone. Standard ES2015 Symbols can be created using theSymbol built-in, e.g. asSymbol.for('foo').When sandboxing, ensure that application C bindings don't accidentally providea mechanism to create hidden Symbols by e.g. converting an input buffer as-isto a string without applying an encoding.

There's currently no special access control for properties with hiddenSymbol keys: if user code has access to the Symbol, it can read/write theproperty value. This will most likely change in future major versions sothat ECMAScript code cannot access a property with a hidden Symbol key,even when holding a reference to the hidden Symbol value.

Bytecode dump/load§

The API callsduk_dump_function() andduk_load_function() allowcalling C code to (1) serialize an ECMAScript function into a portablebytecode and then (2) load the bytecode to reconstitute the function.

The bytecode format is Duktape version specific and it's unsafe toload bytecode from a different Duktape minor version (patch versiondoesn't affect bytecode compatibility). Duktape configuration optionsmay also affect bytecode compatibility, so dump/load source and targetmust be compiled with the same options. The bytecode format is platformneutral so that you can compile bytecode on one platform and then load iton another, which is useful for cross-platform builds. Duktape does notvalidate loaded bytecode so calling code must ensure bytecode is intactand valid for the running Duktape version.

Seebytecode.rstfor more details.

Threading§

Duktape supports a limited form of multithreading:

• A particular Duktape heap created withduk_create_heap() is single threaded: only one native thread can execute code in the heap at a time. The native thread can change over time, as long as two native threads are not active at the same time in the same Duktape heap.
• It is possible to suspend Duktape execution in a Duktape/C call usingduk_suspend() and later resume it withduk_resume(). Between these calls another thread may call into the same Duktape heap. Application code must manage any locking necessary to ensure only one native thread calls into Duktape at a time.
• Duktape heaps are completely isolated from each other. Multiple native threads can execute code at the same time, as long as there is only one active native thread per Duktape heap.

For some background, a Duktape heap is a single memory management regionregardless of how many Duktape threads exist in the heap (don't confuse nativethreads and Duktape threads). Because the Duktape threads in a heap can shareobject references, multithreading support would need synchronization for garbagecollection and all object handling. Synchronization would be a majorportability issue, so a practical approach is to limit a Duktape heap to besingle threaded. Duktape heaps don't share anything so there are no threadinglimitations between them as a general rule. However, when some platform featuresare not available (such as variadic preprocessor macros or re-entrant system calls)there are some limitations.

Seethreading.rstandHow to use multiple native threadsfor a detailed discussion of threading limitations and best practices.

Sandboxing§

Sandboxed environments allow execution of untrusted code with two broadgoals in mind:

• Security: prevent untrusted code from doing unsafe operations such as accessing memory directly, causing segfaults, etc.
• Availability: prevent untrusted code from hogging resources, e.g. consuming all available memory or entering an infinite loop.

Duktape provides mechanisms to achieve these goals for untrusted ECMAScriptcode. All C code is expected to be trusted.Seesandboxing.rstfor a detailed discussion of how to implement sandboxing.

Performance§

Duktape is an interpreted engine with currently no JIT support. It usesreference counting which makes memory usage tight at the cost of some executionperformance. Overall Duktape performance should be similar to other interpretedlanguages.

SeeHow to optimize performancefor discussion of Duktape performance characteristics and hints to optimize codefor performance.

Profile guided optimization (PGO) is strongly recommended if performance isa major concern. For example, GCC -O2 with PGO can be around 20% faster thanGCC -O2 without PGO.

Memory usage§

Duktape allocates memory on demand and doesn't require a pre-allocated heap.When you create a heap on a 32-bit system, Duktape needs about 80kB for thebuilt-in ECMAScript objects. With specificlow memory options initial memoryusage is about 27kB. This can be further reduced to about 3kB when movingbuilt-in objects and strings to ROM (read-only data section). It's alsopossible to move custom native bindings fully into ROM.

After heap creation additional memory is then allocated as needed forexecuting application scripts. Reference counting ensures there is verylittle unused allocated memory, the only major exception being objects whichparticipate in reference loops; these are collected eventually by mark-and-sweep.

The memory allocations needed by Duktape fall into two basic categories.First, there are a lot of small allocations between roughly 16 to 128 byteswhich are needed for strings, buffers, objects, object property tables, etc.Second, there are much fewer larger allocations needed for e.g. ECMAScriptfunction bytecode, large strings and buffers, value stacks, the global stringtable, and the Duktape heap object.

For most systems memory usage or the memory allocation pattern is not anissue. On low memory environments, e.g. less than 1MB of system RAM, you maywant to use a custom allocator to optimize memory usage. A pool-basedallocator deals well with the small allocation churn without fragmentationissues. The downside is that you need to tune the memory pool sizes to matchthe concrete allocation patterns. You may want to use a pool allocator or ahybrid allocated if the platform allocation primitives perform poorly witha lot of small allocations.

Seelow memory options andlow-memory.rstfor more discussion on what low memory features exists and how to tune thememory pools for low memory systems.

With default options Duktape uses a 32-bit refcount field which maytechnically wrap on 64-bit systems with very large memory sizes. Inpractice this is unlikely to happen and requires the Duktape heap to belarger than 64GB. DisableDUK_USE_REFCOUNT32 to usesize_t for refcount fields.

Compiling§

Overview§

There are two basic steps to compiling Duktape:

• Configuration. Usetools/configure.py to prepare Duktape source and header files for compilation. The requested Duktape configuration is described using configure.py command line options, seeConfiguring Duktape for build. For example:

  $ python2 tools/configure.py --output-directory /tmp/output -DDUK_USE_FASTINT -UDUK_USE_ES6_PROXY$ ls /tmp/output/duk_config.h  duk_source_meta.json  duktape.c  duktape.h

• Compilation. Ensure that the generated header files are in the compiler include search path, and include the generate source file(s) in your application build; there's no official Duktape build script or Makefile. For example:

  $ gcc -O2 -Wall -otest -I/tmp/output /tmp/output/duktape.c my_application.c -lm

While Duktape is usually compiled together with your application, you canalso build it into a static or shared library. Duktape can also be installedas a system-wide library, seesystem-install.rst.

Configuring§

Preconfigured sources and default configuration§

The Duktape distributable contains preconfigured sources and headers witha few variants:

• src/: a single source file version which consists ofduk_config.h,duktape.h, andduktape.c.
• src-noline/: same assrc/ but with no#line directives in the combined source file; this matters in some environments, seehttps://github.com/svaarala/duktape/pull/363.
• src-separate/: a separate source files version which consists ofduk_config.h,duktape.h, and a set of separate source files. The single source file version is preferred, but separate files work better with some toolchains.

These preconfigured sources provide automatic platform, compiler, andarchitecture detection and use the Duktape default configuration:

• Full ECMAScript E5/E5.1 compliance (including the optionalAnnex B features), except for intentional real world compatibility deviations (seeCustom behavior)
• ES2015 typed array and Node.js Buffer support
• Some features fromECMAScript 2015 (E6) andECMAScript 2016 (E7)
• Packed value representation (8 bytes per value) when available, unpacked value representation (usually 16 bytes per value) when not
• Reference counting and mark-and-sweep garbage collection
• Full error messages and tracebacks
• No debug printing, no asserts, etc
• All portable fast paths enabled

Running configure.py to customize Duktape configuration§

Theconfigure.py utility prepares Duktape source and headerfiles for a specific configuration described using command line options.For example, to prepare Duktape sources for a DLL build with fastintsupport enabled and ECMAScript 6Proxy object support disabled:

# Default output format is single source file (--separate-sources for separate# sources) and no #line directives (--line-directives to enable them).$ python2 tools/configure.py \      --output-directory /tmp/output \      --dll \      -DDUK_USE_FASTINT \      -UDUK_USE_ES6_PROXY# The output directory /tmp/output contains the header and source files to# be included in your build.$ ls /tmp/outputduk_config.h  duk_source_meta.json  duktape.c  duktape.h

Configuration options given toconfigure.py affect severaldifferent aspects of the prepared header and source files, for example:

• Optional features in Duktape source code are enabled/disabled using config options (DUK_USE_xxx) which are provided by theduk_config.h configuration header. The configuration header also handles platform, architecture, and compiler detection, and all other aspects of platform portability.
• Built-in objects and strings are read in from metadata files and bit-packed built-in initialization data is generated. It's also possible to supply custom metadata files to add custom built-in bindings or modify standard built-ins such asMath andJSON.
• When using "ROM built-ins", built-in objects and strings are placed into the read-only code section to reduce RAM footprint. The necessary source code for built-in object/string initializers is autogenerated by configure.py. Also custom built-ins can be placed in the read-only code section.
• Unicode data files (UnicodeData.txt and SpecialCasing.txt) are converted into bit-packed run-time Unicode tables. The Unicode data files can also be overridden e.g. to reduce Unicode table footprint.

Theconfigure.py utility requires Python 2.x support. If yourbuild environment doesn't support Python 2.x, you can runconfigure.pyon a different platform and compile the resulting files in your build environment.

Even if the default options are OK, it's recommended that you runconfigure.py as part of your build instead of using thepreconfigured sources. Custom options may be necessary on e.g. low memoryplatforms. SeeConfiguring Duktape for buildfor more practical details.

Commonly needed configuration options§

Some commonly needed configuration options are:

• DUK_USE_FATAL_HANDLER, strongly recommended. The built-in default fatal error handler will write a debug log message (butwon't write anything tostdout tostderr), and will then callabort(). If that fails, it enters an infinite loop to ensure execution doesn't resume after a fatal error. This is usually not the best behavior for production applications which may already have better fatal error recovery mechanisms. To replace the default fatal handler, seeHow to handle fatal errors.
• Long control transfer: setjmp/longjmp and C++ exceptions. By default Duktape usessetjmp() andlongjmp() (or their variants) for internal long control transfers. If you're compiling with a C++ compiler you may want to useDUK_USE_CPP_EXCEPTIONS which causes Duktape to use C++ exceptions for long control transfers and allows scope-based resource management (automatic destructors, etc; sometimes referred to asRAII) in Duktape/C functions to work as expected. With MSVC be careful to avoid the/EHsc exception model (use e.g./EHs instead) because the "c" option causes MSVC to assume extern C functions cannot throw C++ exceptions.
• Windows DLL build. Windows DLL build requires somedeclspec() declarations for DLL library symbols. Use the--dll option when runningconfigure.py to enable them for Duktape symbols.
• Forced byte order or alignment. If you're using Duktape on a platform where Duktape's automatic feature detection doesn't (yet) work, you may need to force a specific byte order or alignment requirements during the configuration step.
• Date built-in on exotic platforms. When porting to new or exotic platforms the Duktape built-in Date support may not work on the platform. In such a case you can implement an external "Date provider" which allows you to provide the necessary date/time primitives without Duktape changes. Seedatetime.rst.
• Native stack check macro. When the target has a small stack, it may be useful to defineDUK_USE_NATIVE_STACK_CHECK() macro which provides a better safeguard against stack exhaustion than stack depth limits which can't account for the size of stack frames.

Memory management alternatives§

There are two supported memory management alternatives:

• Reference counting and mark-and-sweep (default): heap objects are freed immediately when they become unreachable except for objects participating in unreachable reference cycles. Such objects are freed by a periodic voluntary, stop the world mark-and-sweep collection. Mark-and-sweep is also used as the emergency garbage collector if memory allocation fails.
• Mark-and-sweep only: reduces code footprint and memory footprint (heap headers don't need to store a reference count), but there is more memory usage variance than in the default case. The frequency of voluntary, stop the world mark-and-sweep collections is also higher than in the default case where reference counting is expected to handle almost all memory management. Voluntary (non-emergency) mark-and-sweep can be disabled via config options.

Reference counting relies on mark-and-sweep to handle reference cycles.For example, every ECMAScript function instance is required to be in areference loop with an automatic prototype object created for the function.You can break this loop manually if you wish. For internal technical reasons,named function expressions are also in a reference loop; this loop cannot bebroken from user code and only mark-and-sweep can collect such functions.

Compiling§

General guidelines§

Duktape doesn't have an official Makefile or a build script: given thenumber of different portability targets, maintaining an official buildscript would be difficult. Instead, you should add Duktape to your existingbuild process in whatever way is most natural.

Duktape is compiled with a C or C++ compiler (C99 is recommended)and then linked to your program in some way; the exact details vary betweenplatforms and toolchains. For example, you can:

• Compile Duktape together with your program without an explicit linking step.
• Compile Duktape as a static library, and link the static library with your program.
• Compile Duktape as a dynamic library, and link the dynamic library with your program.
• Compile Duktape as a dynamic library, install it system-wide, and use it from several applications; seesystem-install.rst.

All Duktape API functions are potentially macros, and the implementationof a certain API primitive may change between a macro and an actual functioneven between compatible releases. Some Duktape configuration options alsoaffect binary compatibility. To ensure binary compatibility:

• Includeduktape.h in application code. This is good practice in general, but without the header your compiler will incorrectly assume that all Duktape API functions are actual functions which will cause linking to fail.
• Use the same prepared Duktape sources and headers when compiling Duktape and your application. This ensures Duktape and your application are compiled with the exactly same Duktape version and configuration. This is especially important when Duktape is compiled as a library in a separate compilation step.
• Use the same compiler when compiling Duktape and your application. Using a different compiler may affect e.g. type detection in the Duktapeduk_config.h header or function calling convention, and thus compromise binary compatibility. In practice compilers can be mixed to some extent, e.g. GCC and Clang are generally compatible.

Recommended compiler options§

Recommended compiler options for GCC/clang, use similar options foryour compiler:

• -std=c99: recommended to ensure C99 semantics which improve C type detection and allows Duktape to use variadic macros.
• -Wall: recommended to catch potential issues early.
• -Os: optimize for smallest footprint, which is usually desired when embedding Duktape.-O2 is a good compromise for performance optimized builds.
• -fomit-frame-pointer: omit frame pointer, further reduces footprint but may interfere with debugging (leave out from debug builds).
• -fstrict-aliasing: use strict aliasing rules, Duktape is compatible with these and they improve the resulting C code.
• Configure.py with--dll is needed when Duktape is built as a DLL, at least when compiling for Windows.

Compilation warnings§

Duktape usually compiles without warnings when using a mainstream compiler(e.g. GCC, Clang, MSVC, or MinGW) in C99 mode with warnings enabled (e.g.-Wall in gcc/clang), and using default Duktape configurationoptions. There may be some warnings when using a non-mainstream compiler,very strict warning levels (like-Wextra in gcc/clang or/W4 in MSVC), or non-default Duktape configuration options.Eliminating compilation warnings for all compilers and all configurationoption combinations is very difficult and is thus explicitly not a projectgoal. You're still encouraged to report warnings so that they can be fixedif possible.

Using a C++ compiler§

Duktape works with both C and C++ compilers and applications. You cancompile Duktape and the application with a C or a C++ compiler in anycombination. Even so, it is recommended to compile both Duktape and theapplication with the same compiler (i.e. both with a C compiler or bothwith a C++ compiler) and with the same compiler options.

Theduktape.h header contains the necessary glue to make allof these combinations work. Specifically, all symbols needed by Duktapepublic API are inside aextern "C" { ... } wrapper when compiledwith a C++ compiler. This ensures that such symbols are defined and usedwithout C++ name mangling. Specifically:

• When compiling Duktape itself with a C++ compiler, symbols needed by Duktape public API are not mangled. Other Duktape internal symbols will be mangled, but are not externally visible and should thus cause no problems even if the application is compiled with a C compiler.
• When compiling an application with a C++ compiler, the wrapper ensures that Duktape public API symbols used by the application are looked up without mangling.

If you mix C and C++ compilation, you should do the final linking with theC++ toolchain. At least when mixing gcc/g++ you may encounter something like:

$ g++ -c -o duktape.o -Isrc/ src/duktape.c$ gcc -c -o duk_cmdline.o -Isrc/ examples/cmdline/duk_cmdline.c$ gcc -o duk duktape.o duk_cmdline.o -lmduktape.o:(.eh_frame+0x1ab): undefined reference to `__gxx_personality_v0'collect2: error: ld returned 1 exit status

One fix is to useg++ for linking:

$ g++ -c -o duktape.o -Isrc/ src/duktape.c$ gcc -c -o duk_cmdline.o -Isrc/ examples/cmdline/duk_cmdline.c$ g++ -o duk duktape.o duk_cmdline.o -lm

Becauseduk_config.h selects C/C++ data types needed byDuktape and also does other feature detection, mixing C and C++ compilerscould theoretically cause the C and C++ compilers to end up with differentactive features or data types. If that were to happen, Duktape and theapplication would be binary incompatible which would lead to very difficultto diagnose issues. This is usually not an issue, but to avoid the potential,compile Duktape and the application with the same compiler.

By default scope-based resource management (sometimes referred to asRAII)won't work in Duktape/C functions because Duktape useslongjmp() for internal long control transfers, bypassingC++ stack unwind mechanisms. You can useDUK_USE_CPP_EXCEPTIONSto cause Duktape to use C++ exceptions for internal long control transfers,which allows scope-based resource management to work in Duktape/C functions.With MSVC be careful to avoid the/EHsc exception model (use e.g./EHs instead) because the "c" option causes MSVC to assume externC functions cannot throw C++ exceptions. When using MSVC and CMake you can usee.g.:

if (MSVC)    string( REPLACE "/EHsc" "/EHs" CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}" )endif()

Portability§

Duktape is widely portable to platforms with at least a C89 compiler(with a few exceptions like requiring snprintf() and vsnprintf()).Because Duktape has very limited dependency on platform functions, it'spossible to Duktape to very exotic platforms. One major platform dependencyis the Date built-in which may need a custom provider for an exotic platform.

SeePortability forplatform and compiler specific portability issues, porting recommendations,and troubleshooting tips.

Compatibility§

This section discussed Duktape compatibility with ECMAScript dialects,extensions, frameworks, and test suites.

ECMAScript E5 / E5.1§

The main compatibility goal of Duktape is to be ECMAScript E5/E5.1compatible. However, ES5 feature semantics are updated to ES2015 (orlater) where incompatible changes have been made in newer specificationversions. Current level of compatibility should be quite high.

ECMAScript 2015 (E6)§

Duktape implements some features from ECMAScript 2015 (E6), but generally thereis no compatibility with E6 yet.

ECMAScript 2016 (E7)§

Duktape implements some features from ECMAScript 2016 (E7), but generally thereis no compatibility with E7 yet.

ECMAScript E3§

There is no effort to maintainECMAScript E3compatibility, other than required by the E5/E5.1 specification.

CoffeeScript§

CoffeeScript compiles toJavaScript which should be compatible with Duktape. There are no knowncompatibility issues.

Some CoffeeScript examples are included in the distributable. Simplyrunmake inexamples/coffee/. For instance,hello.coffee:

print 'Hello world!'print 'version: ' + Duktape.version

compiles to:

(function(){print('Hello world!');print('version: '+ Duktape.version);}).call(this);

Coco§

Like CoffeeScript,Coco compiles toJavascript. There are no known issues.

LiveScript§

Like CoffeeScript,LiveScript compiles toJavascript. There are no known issues.

TypeScript§

TypeScriptcompiles to Javascript. There are no known issues with compiling TypeScriptusing the Microsoft TypeScript compiler (in the ES5/CommonJS mode) andrunning the resulting Javascript using Duktape. It's also possible torun the TypeScript compiler with Duktape.

Underscore.js§

Underscore.js provides a lot ofuseful utilities to plain ECMAScript. Duktape passes almost all of Underscore'stest cases, seeunderscore-status.rstfor current compatibility status.

Test262§

test262 is a test suite fortesting E5.1 compatibility, although it includes also tests outside of standard E5.1.Duktape passes almost all of test262 cases, seetest262-status.rstfor current compatibility status.

Asm.js§

asm.js is a"strict subset of JavaScript that can be used as a low-level, efficienttarget language for compilers". As a subset of JavaScript, functions usingasm.js type annotations should be fully compatible with Duktape. However,Duktape has no specific support for asm.js and won't optimize asm.js code.In fact, asm.js code will generate unnecessary bytecode and execute slowerthan normal ECMAScript code. The"use asm" directive specifiedby asm.js is ignored by Duktape.

Emscripten§

Emscripten compilesC/C++ into Javascript. Duktape is currently (as of Duktape 1.5.0) Emscriptencompatible and supports ES2015 TypedArray which allows Emscripten fastcompto be used.

Large programs may fail due to Duktape compiler running out of virtualregisters, and performance is somewhat limited as Duktape is an interpretedengine. Seeemscripten-status.rstfor current compatibility status.

Because Duktape itself compiles with Emscripten, it is possible to runDuktape inside a web page for instance, seeDukweb REPL.

Lua.js§

lua.js translates Luacode to Javascript. There are no known issues in running the generatedJavascript, except that Duktape doesn't provideconsole.logwhich lua.js expects. This is easy to remedy, e.g. by prepending thefollowing:

console={ log:function(){print(Array.prototype.join.call(arguments,' '));}};

JS-Interpreter§

JS-Interpreterinterprets Javascript in Javascript. JS-Interpreter works with Duktape,except that Duktape doesn't providewindow which JS-Interpreterexpects. This can be fixed by prepending:

window={};

Versioning§

Semantic versioning§

Duktape followsSemantic Versioning forofficial releases:

• Major version changes when API incompatible changes are made.
• Minor version changes when backwards-compatible functional changes are made.
• Patch version changes when backwards-compatible bug fixes are made.

The "public API" to which these rules apply include:

• The Duktape API calls documented on duktape.org; except those taggedexperimental.
• The global environment visible to ECMAScript code, including theDuktape object and other ECMAScript extensions, as documented on duktape.org; except changes needed to align with latest ECMAScript specifications.

The following are not part of the "public API" versioning guarantees:

• Duktape API calls taggedexperimental, and any other features documented as experimental.
• Internal calls made by API macros. While API calls implemented as macros are part of the public API, any internal calls the macros make are not, even if their symbol visibility is public.
• Changing an API call from a function call to a macro (or vice versa). These are considered compatible changes (but are not done in patch releases).
• Aligning with latest ECMAScript specifications. Duktape tracks the latest ECMAScript specification (currently ES2016). Backwards incompatible changes required to align with the latest specifications may be done in minor versions too (but not in patch versions unless necessary to fix a bug). Typically such changes are relatively minor, for example argument coercion or property inheritance changes.
• Specific behavior which is explicitly noted to potentially change even in minor versions, for example:
  • Behavior of buffer objects when their backing buffer is smaller than the apparent size of the buffer object. Memory safe behavior is guaranteed, but otherwise behavior may vary between versions.
• Duktape config options. Incompatible config option changes are not made in patch releases, but can be made in minor releases. The goal is to cause a compile error (if possible) when a no-longer-supported feature option is used so that any incorrect assumptions can be fixed.
• Extras distributed with Duktape (extras/ directory).

When a patch version is released, the following things are guaranteed:

• API binary compatibility is maintained: constant values don't change, function typing doesn't change, API call function/macro status doesn't change.
• Bytecode dump/load format doesn't change so that you can load bytecode dumped from an older version which only differs in patch version.
• ECMAScript semantics fixes are not included unless necessary to fix a bug.
• Config options won't change in an incompatible manner.

Development builds made from Duktape repo are not official releases anddon't follow strict semantic versioning.

Experimental features§

Some new features and API calls are markedexperimental which meansthat they may change in an incompatible way even in a minor release.

Features may be marked experimental e.g. because they are useful butincomplete, or because the best design is not obvious and it's useful togather some feedback before committing to the design. Typically a featureis experimental for one minor release and then, after the necessary changes,becomes a fully supported feature.

Version naming§

Releases use the form(major).(minor).(patch), e.g.1.0.3.

DUK_VERSION and Duktape.version§

DUK_VERSION andDuktape.version provide versionidentification using a single number computed as:(major * 10000 + minor * 100 + patch),then subtracting one for development builds (not official releases) made fromDuktape repo.

Note the limitations for development builds:

• Development builds for the same upcoming release are not distinguished from one another: for example, all builds from master prior to 1.3.0 release are identified as 10299.
• Development builds for patch releases are not distinguished from the previous patch release: for example, a development build after 1.3.2 but before 1.3.3 is identified as 10302.

Development builds shouldn't be used in production, but the currentDUK_VERSION andDuktape.version number providesa useful approximation for version comparison: a development build willcompare smaller than the actual release, but higher (or equal) than aprevious release.

Examples§

The table below provides some examples, in ascending version order:

Maintenance of stable versions§

There's no long term maintenance policy yet: stable versions will get bugfixes (patch releases) at least until the next stable version has beenreleased, and there has been some time to migrate to it.

Incompatible changes§

The general goal for incompatible changes is that an application relyingon old, unsupported features will fail to build. It is preferable to have thebuild fail rather than to be silently broken. This means for example that:

• When API call semantics are changed, the old API call is removed (causing a build failure if used) and a new one is added.
• When support for an old feature option is removed, an attempt to use it will cause a build failure.

This is not a hard rule, and it cannot be achieved in all cases.

Limitations§

The following is a list of known limitations of the current implementation.Limitations include shortcomings from a semantics perspective, performancelimitations, and implementation limits (which are inevitable).

Trivial bugs are not listed unless they are "long term bugs".

No re-entrancy§

A single Duktape heap, i.e. contexts sharing the same garbage collector,isnot re-entrant. Only one C/C++ thread can call Duktape APIsat a time for a particular Duktape heap (although the calling threadcan change over time). SeeThreading.

String and buffer limits§

The internal representation allows a maximum length of 2**31-1 (0x7fffffff)bytes (not characters) for strings. 16-bit codepoints encode into 3bytes of UTF-8 in the worst case, so the maximum string length which isguaranteed to work is about 0.7G characters.

Buffer values are also limited to 2**31-1 (0x7fffffff) bytes.

Property limits§

An object can have at mostDUK_HOBJECT_MAX_PROPERTIES (aninternal define). Currently this limit is 0x7ffffffff.

Array limits§

When array item indices go over the 2**31-1 limit (0x7fffffff), Duktapehas some known bugs with array semantics.

Regexp quantifier over empty match§

The regexp engine gets stuck when a quantifier is used over anempty match but eventually bails out with an internal recursion(or execution step) limit. For instance, the following should producea "no match" result but hits an internal recursion limit instead:

$ dukduk> t = /(x*)*/.exec('y');RangeError: regexp executor recursion limit    at [anon] (duk_regexp_executor.c:145) internal    at exec () native strict preventsyield    at global (input:1) preventsyield

Duktape does not fully support locales§

Although Duktape supports the concept of a local time, it doesn't supportother locale related features such as: locale specific Date formatting,locale specific string comparison, locale/language specific Unicode rules(such as case conversion rules for Turkish, Azeri, and Lithuanian).

Unicode case conversion is not locale or context sensitive§

E5 Sections 15.5.4.16 to 15.5.4.19 require context and locale processingof UnicodeSpecialCasing.txt. However, Duktape doesn't currentlyhave a notion of "current locale".

Array performance when using non-default property attributes§

All array elements are expected to be writable, enumerable, and configurable(default property attributes for new properties). If this assumption is violated,even temporarily, the entire "array part" of an object is abandoned permanentlyand array entries are moved to the "entry part". This involves interning all usedarray indices as explicit string keys (e.g. "0", "1", etc). This is not acompliance concern, but degrades performance.

Array performance when writing elements using Object.defineProperty()§

When number indexed array elements are written withObject.defineProperty()the current implementation abandons the internal "array part" which makes laterarray access much slower. Write array elements with direct assignments such asa[123] = 321 to avoid this.

Global/eval code is slower than function code§

Bytecode generated for global and eval code cannot assign variablesstatically to registers, and will use explicit name-based variableread/write accesses. Bytecode generated for function code doesn'thave this limitation; most variables are assigned statically to registersand direct register references are used used to access them.

This is a minor issue unless you spend a lot of time running top-levelglobal/eval code. The workaround is simple: put code in a function whichyou call from the top level; for instance:

functionmain(){// ...}main();

There is also a common idiom of using an anonymous function for thispurpose:

(function(){// ...})();

Function temporaries may be live for garbage collection longer than expected§

ECMAScript functions are compiled into bytecode with a fixed set ofregisters. Some registers are reserved for arguments and variablebindings while others are used as temporaries. All registers areconsidered live from a garbage collection perspective, even temporaryregisters containing old values which the function actually cannotreference any more. Such temporaries are considered reachable until theyare overwritten by the evaluation of another expression or until thefunction exits. Function exit is the only easily predicted condition toensure garbage collection.

If you have a function which remains running for a very long time, itshould contain the bare minimum of variables and temporaries that couldremain live. For instance, you can structure code like:

functionrunOnce(){// run one iteration, lots of temporaries}functionforeverLoop(){for(;;){runOnce();}}

This is typically not an issue if there are no long-running functions.

Function instances are garbage collected only by mark-and-sweep§

Every ECMAScript function instance is, by default, in a reference loop withan automatic prototype object created for the function. The function instance'sprototype property points to the prototype object, and the prototype'sconstructor property points back to the function instance. Onlymark-and-sweep is able to collect these reference loops at the moment. If youbuild with reference counting only (not recommended), function instances mayappear to leak memory; the memory will be released when the relevant heap isdestroyed.

You can break the reference loops manually (although this is a bit cumbersome):

var f=function(){};var g=function(){};var h=function(){};Duktape.fin(f,function(){print('finalizer for f');});Duktape.fin(g,function(){print('finalizer for g');});Duktape.fin(h,function(){print('finalizer for h');});// not collected until heap destruction in a reference counting only buildf=null;// not collected immediately// break cycle by deleting 'prototype' reference (alternative 1)g.prototype=null;g=null;// collected immediately, finalizer runs// break cycle by deleting 'constructor' reference (alternative 2)h.prototype.constructor=null;h=null;// collected immediately, finalizer runs// mark-and-sweep triggers finalizer for 'f'Duktape.gc();

For internal technical reasons, named function expressions are also in areference loop with an internal environment record object. This loop cannotbe broken from user code and only mark-and-sweep can collect such functions.Ordinary function declarations and anonymous functions don't have thislimitation. Example:

var fn=functionmyfunc(){// myfunc is in reference loop with an internal environment record,// and can only be collected with mark-and-sweep.}

Since Duktape 2.x mark-and-sweep is always enabled so that objectsparticipating in reference loops are eventually freed. You can disableperiodic "voluntary" (non-emergency) mark-and-sweep via config optionsto reduce collection pauses in time sensitive environments.

Non-standard function 'caller' property limitations§

WhenDUK_USE_NONSTD_FUNC_CALLER_PROPERTY is given, Duktapeupdates thecaller property of non-strict function instancessimilarly to e.g. V8 andSpidermonkey.There are a few limitations, though:

• When a (non-strict) function is called from eval code, Duktape setscaller tonull if the eval code is non-strict, andeval (reference to the eval built-in function) if the eval code is strict. This deviates from e.g. V8 behavior.
• Coroutines andcaller don't mix well:caller may be left in a non-null state even after coroutine call stacks have been fully unwound. Also, if a coroutine is garbage collected before its call stack is unwound, thecaller property of functions in its call stack will not get updated now.

See the internaltest-bi-function-nonstd-caller-prop.js testcase for further details.

Garbage collection during debugger paused state§

When debugger support is activated, a debugger session is active, andDuktape is paused, there are a few current limitations:

• Because garbage collection is disabled during the paused state, calls toDuktape.gc() andduk_gc() will be silently ignored.

Comparison to Lua§

Duktape borrows a lot from Lua conceptually. Below are a few notes onwhat's different in Duktape compared to Lua. This may be useful if you'realready familiar with Lua.

Array and stack indices are zero-based§

All array and stack indices are zero-based, not one-based as in Lua. So,bottom of stack is 0, second element from bottom is 1, and top element is -1.Because 0 is no longer available to denote an invalid/non-existent element,the constantDUK_INVALID_INDEX is used instead in Duktape.

String indices are also zero-based, and slices are indicated with aninclusive start index and an exclusive end index (i.e. [start,end[).In Lua, slices are indicated with inclusive indices (i.e. [start,end]).

Object type represents functions and threads§

In Lua functions and threads are a separate type from objects.In Duktape the object type is used for plain objects, ECMAScript andnative functions, and threads (coroutines). As a result, all of thesehave a mutable and extensible set of properties.

Lua userdata and lightuserdata§

The concept closest to Luauserdata is the Duktapebuffertype, with the following differences:

• Duktape buffers can be resizable, Lua userdata values cannot. If a Duktape buffer is resizable, its data pointer is no longer guaranteed to be stable.
• Duktape buffers are raw byte arrays without any properties, Lua userdata objects can store an environment reference.

Lualightuserdata and Duktapepointer are essentiallythe same.

If you need to associate properties with a Duktape buffer, you can usea buffer object instead (or create your own object and store the plain bufferas its property). You can then add a finalizer to the object to free anyresources related to the buffer. This works reasonably well as long as nothingelse holds a reference to the buffer. If this were the case, the buffer couldget used after the object had already been finalized. To safeguard against this,the native C structure should have a flag indicating whether the data structureis open or closed. This is good practice anyway for robust native code.

Garbage collection§

Duktape has a combined reference counting and non-incremental mark-and-sweepgarbage collector (mark-and-sweep is needed only for reference cycles). Collectionpauses can be avoided by disabling voluntary mark-and-sweep passes(disableDUK_USE_VOLUNTARY_GC). Lua has an incremental collector withno pauses, but has no reference counting.

Duktape has an emergency garbage collector. Lua 5.2 has an emergencygarbage collector while Lua 5.1 does not (there is an emergency GC patchthough).

duk_safe_call() vs. lua_cpcall()§

duk_safe_call() is a protected C function call whichoperates in the existing value stack frame. The function call isnot visible on the call stack all.

lua_cpcall() creates a new stack frame.

Bytecode dump/load§

Starting from Duktape 1.3 Duktape has a bytecode dump/load mechanismsimilar to Lualua_dump(). SeeBytecode dump/load.

Metatables§

There is no equivalent of Lua metatables in ECMAScript E5/E5.1, butECMAScript ES2015 Proxy objectsprovide similar functionality. To allow property virtualization better than available inE5/E5.1, Duktape implements anES2015 Proxy subset.

lua_next() vs. duk_next()§

lua_next() replaces the previous key and value with a new pair,whileduk_next() does not; the caller needs to explicitly pop thekey and/or value.

Raw accessors§

There is no equivalent to Lua raw table access functions likelua_rawget. One can use the following ECMAScript built-insfor a similar effect (though not with respect to performance):Object.getOwnPropertyDescriptor ( O, P ),Object.defineProperty ( O, P, Attributes ).

Coroutines§

There are no primitives for coroutine control in the Duktape API(Lua API has e.g.lua_resume). Coroutines can only be controlledusing the functions exposed by theDuktape built-in. Further,Duktape has quite many coroutine yield restrictions now; for instance,coroutines cannot yield from inside constructor calls or getter/setter calls.

Multiple return values§

Lua supports multiple return values, Duktape (or ECMAScript) currentlydoesn't. This may change with ECMAScript ES2015, which has a syntax formultiple value returns. The Duktape/C API reserves return values above 1so that they may be later used for multiple return values.

Weak references§

Lua supports weak references. Duktape currently doesn't.

Unicode§

Lua has no built-in Unicode support (strings are byte strings), whileDuktape has support for 16-bit Unicode as part of ECMAScript compliance.

Streaming compilation§

Lua has a streaming compilation API which is good when code is read fromthe disk or perhaps decompressed on-the-fly. Duktape currently does notsupport streaming compilation because it needs multiple passes over thesource code.