Duktape 2.3 release notes

Release overview

Main changes in this release (see RELEASES.rst for full details):

• duk_xxx_literal() API call variants which take a plain C literal argument, for example duk_get_prop_literal(ctx, -2, "myProperty"). The calls are conceptually similar to the duk_xxx_string() variants, but can take advantage of the fact that e.g. string length for a C literal can be determined at compile time using sizeof("myProperty") - 1 (the -1 is for NUL termination). Literal strings used by application code are also automatically pinned between mark-and-sweep rounds, and a small lookup cache makes mapping a C literal to a heap string object quite fast (almost as fast as using a heapptr). For now the calls are experimental.
• More ES2015 support: Symbol.hasInstance, Symbol.toStringTag, Symbol.isConcatSpreadable, Symbol.toPrimitive, Proxy improvements, Number.EPSILON, Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER, Number.isFinite(), Number.isNaN(), Number.isSafeInteger(), Number.parseInt(), Number.parseFloat().
• Other API additions: duk_random(), duk_push_new_target(), duk_get_global_heapptr(), duk_put_global_heapptr().
• When C++ exception support is enabled (DUK_USE_CPP_EXCEPTIONS), Duktape now uses a C++ exception throw also for fatal errors (e.g. uncaught error). The exception thrown has the type duk_fatal_exception which inherits from std::runtime_error so it has a ::what() method and a useful message.
• DUK_USE_ALIGN_BY now always defaults to 8 (natural alignment) to avoid any potentially unsafe assumptions about compiler behavior for unaligned memory accesses and pointers (which may be an issue even on x86).
• A new CBOR encoder/decoder extra which may be eventually merged (in some form) into Duktape itself. CBOR is a useful binary serialization format which is a superset of JSON and has an RFC specification.
• A Promise polyfill which will be used as a basis for the initial native implementation.
• Various fixes and portability improvements.

Upgrading from Duktape 2.2

No action (other than recompiling) should be needed for most users to upgrade from Duktape v2.2.x. Note the following:

• If you are using DUK_USE_CPP_EXCEPTIONS note that fatal errors are now thrown using a C++ exception of the type duk_fatal_exception which inherits from std::runtime_error and will be caught by a boilerplate std::exception catch. In previous versions uncaught errors would propagate out as duk_internal_exceptions, while assertions would default to abort(). As before, it is unsafe to continue after catching a duk_fatal_exception. You can override the new behavior by:
  • Providing an explicit fatal error handler in heap creation. This affects heap related fatal errors (like uncaught exceptions), but won't affect fatal errors without a heap context (like assertions).
  • Providing an explicit default fatal error handler using the DUK_USE_FATAL_HANDLER config option. This affects both types of fatal errors.
• If performance matters, you might consider using duk_xxx_literal() variants in place of duk_xxx_string() variants when the argument is a C literal. With literal pinning and the literal lookup cache this improves property access performance around 20% with minimal application changes. Make sure that the arguments are C literals, e.g. duk_get_prop_literal(ctx, "mykey") and not pointers to strings like duk_get_prop_literal(ctx, strptr).
• If you're using the duk_xxx_heapptr() API call variants, you might consider switching to the duk_xxx_literal() variants. They are less error prone, and with literal pinning and the literal lookup cache almost as fast as using a borrowed heap pointer.
• If you're working with a low memory target or any other target where memory usage matters, you may want to ensure UDK_USE_LITCACHE_SIZE is undefined in configure.py configuration (this is included in low_memory.yaml base config).
• If you're working with a low memory target or any other target where memory usage matters, you may want to force DUK_USE_ALIGN_BY to a lower value (4 or 1) to reduce memory overhead. For most targets the memory overhead is not important.
• Base-64 and hex encoding/decoding support is now configurable and disabled by default in the example low_memory.yaml configuration. Enable them manually if necessary using DUK_USE_BASE64_SUPPORT and DUK_USE_HEX_SUPPORT.
• The built-in base64 decoder is now more lenient. If you're relying on strictness or specific behavior of the base64 decoder, you should use an external decoder with the exact behavior desired (base64 decoders differ quite a lot with respect to various decoding corner cases).
• Several -fsanitize=undefined warnings have been fixed in the default configuration using explicit checks to avoid undefined behavior. For example, floating point division by zero is avoided and behavior in that case is implemented explicitly, at some cost in footprint and performance. For many compilers the undefined behavior assumptions in Duktape source are fine, and you can remove the extra overhead by enabling the DUK_USE_ALLOW_UNDEFINED_BEHAVIOR option in configure.py (this option is enabled in the low_memory.yaml and performance_sensitive.yaml example configurations). Note, however, that recent gcc/clang versions are optimizing around undefined behavior so while relying on undefined behavior may work in one version, it may break with newer compiler versions.
• The console extra (extras/console) now by default uses stdout for log levels up to info, and stderr for warn and above. To restore previous behavior (stdout only) use the DUK_CONSOLE_STDOUT_ONLY flag in duk_console_init().