Not so long ago I got burned for a second time during the last 6 months by a horrible MSVC pitfall called the _HAS_EXCEPTIONS macro. The second time it took me about an hour to realize the problem — the first time it took me almost three days — including the time the write my previous story about using the Google address sanitizer in a Node.js addon on Windows [#7]. Should you be interested in the particular problem of exceptions on Windows for Node.js addons, I have included some links at the very end of the story.

This story focuses on whether disabling C++ exceptions when building is actually a valid optimization.

There is no such thing as C++ without exceptions

No more than there is C++ without const variables or C++ without switch statements. This horrible compiler option has been born out of necessity and inherited from the early days when the compilers had very poor exceptions implementations. A 2006 industry study, without any factual benchmarks, but with some very big names on its committee, including Bjarne Stroustrup, came to the conclusion that thanks to advances in compilation, the early performance problems of using C++ exceptions were more or less completely solved [#5].

I will cover the few still valid reasons not to use them in a later section.

Exceptions are one of the greatest advances in computer languages

This is not an overstatement. Exceptions enable structured error handling that greatly simplifies the code. Every single modern high level language has them. And C++, being this unique language that is both high level and low level at the same time, is not an exception (pun intended).

However, exceptions in C++ have bad reputation. There is a very famous Google coding style document from the 2000s that forbids using them in Google code [#1]. There is also the browser mafia, very inclined to cut corners during the second browser wars, that famously decided to skip them. C++ exceptions are also controversial. A C++ compiler engineer, when asked about exceptions, is wary of starting a flame war [#2]. It seems that the LLVM team itself, the C++ compiler engineers, avoid using them! Novice C++ programmers are told that C++ exceptions are dangerous and slow. C++ exceptions are scary.

If you are new to C++ memory management — learn one simple rule — always catch exceptions by const reference — and throw only std::exception objects. You will never ever worry about memory.

Yeah, but exceptions are slow, right?

Are they?

Show me the code and the benchmarks

There are already quite a lot of benchmarks that deal with throwing exceptions [#3] [#4]. And in case you didn’t know it — throwing an exception is expensive — it is orders of magnitude more expensive that returning an error code.

So if you plan to have a 10% exception rate, as it is the case in the second benchmark from the two cited above, then exceptions are not for you. Exceptions are about exceptional situations. When you have a 10% rate, this is not an error, this is part of the nominal mode and you need another error-handling mechanism.

This story is especially about the compiler option -fno-exceptions and its benefits.

So, before diving in the numbers, lets clarify what does -fno-exceptions do? When a C++ function gets compiled, the compiler must produce the so-called stack unwinding code — code that gets called to destroy all the local objects. As an exception must propagate through a certain number of function calls, it must follow this stack unwinding chain in order to destroy all the local objects. Code compiled with -fno-exceptions lacks part of this information, which means that if an exception reaches it, it is transformed into a std::terminate and terminates the program.

In order to stress the function calling, we will be using the following horrible program which does nothing but function calls:

Note the branch prediction optimization. The differences will be measuring are so small, that unless you get this correctly, you will be measuring mostly the branch prediction performance. It outweighs any impact from stack unwinding by a very wide margin.

We want to measure the impact of compiling with exceptions enabled. Also note that we are not actually throwing any exceptions — we consider throwing to be a very rare event — we want to measure the impact of simply using exceptions.

We will be compiling in a few different modes (you can find a link to the repository with the full code with all #ifdef at the end of story):

• no_unwind : without exceptions at all, throwing manually replaced by a std::abort through a compile time macro, compiling with:

-fno-exceptions -fno-rtti -fno-unwind-tables -fomit-frame-pointer

• unwind_dontcare : without exceptions at all, throwing manually replaced by a std::abort through a compile time macro but exceptions enabled in the compiler — a very important test for everyone who is disabling exceptions for performance benefits in code that does not use them
• unwind_noexcept : without exceptions at all, throwing manually replaced by a std::abort through a compile time macro but exceptions enabled in the compiler and the fibonacci function marked as noexcept
• unwind_throwing : with throwing exceptions but without a catch block in fibonacci — only a single catch block in main
• unwind_catching : the full deal as you see it
• and a plain old C test — for everyone who firmly believes that the world lost a little bit of performance when we started switching to C++ compilers

I did all of the tests using gcc , clang and Intel OneAPI — without any significant differences — except for the -funroll-loops option which is not enabled by default in clang . We will be discussing mainly the gcc results on x86–64. Keep in mind that x86-64 has very good hardware support for exceptions and stack unwinding and the results might be slightly different on other architectures.

Let’s try to analyze those results:

No optimization (-O0)

If you do not throw and do not catch, having or not having exceptions enabled comes down to nothing. Throwing has a small cost, catching at each recursion level has a more significant cost. In this case, there is real work to do — saving a handler before each call.

When it comes to the plain old C — the answer is — no, most of the time, compiling C in C++ mode does not lead to a performance loss.

What is absolutely remarkable is that the -fomit-frame-pointer binary is very slightly larger. How can omitting the frame pointer lead to a larger binary??

Well, this is lesson number 1

-fomit-frame-pointer, another not-so-great “optimization” idea.

Omitting the frame pointer saves one instruction in the beginning. However this also forces the compiler to access all the local variables using the slightly larger instruction based on the stack pointer %rsp instead of the more efficient %rbp instruction:

Normal optimization (-O2)

Recursion unrolling, an optimization quite similar to loop unrolling, has kicked in. The functions are much bigger and run slightly faster. However, the above cited LLVM compiler engineer was right — throwing and catching gets in the way of compiler optimization and renders unrolling the recursion impossible.

Lesson number 2

A very important thing to note: our puny efforts at saving several dozen bytes from the function size have been completely dwarfed by the 500 byte increase from the recursion unrolling and now look totally ridiculous. Something to consider in the future.

Aggressive optimization (-O3)

Well, with -O3 gcc has now the upper hand versus the exception handling. Recursion unrolling is possible for all cases. Not only throwing and catching are now completely free — by pure chance — because of the better utilization of the CPU pipelining, catching at each recursion level is actually faster then compiling without exceptions. Just look at the stalled-cycles-backend counter to see the problem:

 Performance counter stats for './test-cc-O3-unwind_catching':

         19 565,33 msec task-clock                       #    1,000 CPUs utilized             
               184      context-switches                 #    9,404 /sec                      
                 0      cpu-migrations                   #    0,000 /sec                      
               110      page-faults                      #    5,622 /sec                      
    66 614 649 139      cycles                           #    3,405 GHz                         (49,99%)
     6 001 820 007      stalled-cycles-frontend          #    9,01% frontend cycles idle        (50,01%)
       862 867 946      stalled-cycles-backend           #    1,30% backend cycles idle         (50,02%)
   146 312 773 990      instructions                     #    2,20  insn per cycle            
                                                  #    0,04  stalled cycles per insn     (50,01%)
    26 776 756 708      branches                         #    1,369 G/sec                       (49,99%)
       414 037 604      branch-misses                    #    1,55% of all branches             (49,98%)

      19,568759571 seconds time elapsed

      19,566978000 seconds user
       0,000000000 seconds sys

 Performance counter stats for './test-cc-O3-no_unwind':

         21 431,10 msec task-clock                       #    1,000 CPUs utilized             
               157      context-switches                 #    7,326 /sec                      
                 0      cpu-migrations                   #    0,000 /sec                      
                52      page-faults                      #    2,426 /sec                      
    72 985 918 854      cycles                           #    3,406 GHz                         (50,00%)
     6 651 978 854      stalled-cycles-frontend          #    9,11% frontend cycles idle        (50,00%)
     9 548 404 958      stalled-cycles-backend           #   13,08% backend cycles idle         (50,00%)
   134 993 845 095      instructions                     #    1,85  insn per cycle            
                                                  #    0,07  stalled cycles per insn     (50,00%)
    19 862 285 441      branches                         #  926,797 M/sec                       (50,00%)
       788 489 544      branch-misses                    #    3,97% of all branches             (50,00%)

      21,433689694 seconds time elapsed

      21,428887000 seconds user
       0,003999000 seconds sys

I don’t want to dive into this 700 bytes function to see why and the results — which once again are the product of pure coincidence — might be different on a different CPU — as this is on an older AMD CPU for which the optimization might not be perfect. But still, the lesson stands and it is a very important one:

Lesson number 3

Simply avoid fiddling with compiler options. The compiler authors usually know what they are doing and it is unlikely they left out any hidden magical performance increasing options.

Adding code to the stack unwinding

As we already said, the job of the stack unwinding code is to destroy the local variables. However, in this first test, the function did not contain any local variables with destructors. We will see that adding even a single variable will make any execution time difference impossible to measure — as this difference is so tiny. However this will allow to see the code size difference. Here is the code for the second test:

We have added an artificial object construction that cannot be optimized away and has a non-trivial destructor that must be called when the exception travels up the stack. Although I have been very careful to avoid any memory allocation, this was more than enough to become the dominant part of the execution — now the execution time difference is (almost) impossible to measure.

However the code size experiment results remain the same — slight code size increase in the unoptimized case, that is completely dwarfed by the various loop/recursion unrolling optimizations:

Stack unwinding under the hood

We can use the last example to see the additional code needed for stack unwinding:

This is the raw unoptimized version. The unwinding code is a small subroutine at the end of the function that calls the destructors of the local objects. The new x86-64 endbr64 instruction — a security feature called Indirect Branch Tracking — marks valid jump locations and makes it particularly easy to spot the beginning of the function and the beginning of the stack unwinding routine. When the function exits normally, a jmp allows to bypass the unwinding. try / catch statements save its entry points in a special memory section which works as a second parallel stack. Sometimes — especially for the standard library — static tables allow for greater efficiency. You can find a more detailed description in [#6].

Alternatives to exceptions

There are few cases where not using exceptions is probably the right answer. For example, in the world of embedded software — where code size may be very important— this allows to skip parts of the compiler runtime — if the compiler supports it.

Do not forget that most normal C++ compilers will always use the same precompiled C++ runtime which uses exceptions.

Also, in very low-level routines, especially when very high error rates are expected, alternative constructs such as Result in Rust or the new std::expected in C++ can offer a better alternative.

It is worth noting that Rust — which does not have exceptions, but relies only on the higher performance Result — is trying to be a successor of C and not C++.

Because of its special status as both high- and low-level language, C++ offers both mechanisms.

Conclusions

1. If you don’t use exceptions, and you decide to disable them at the compilation level, you can expect some very small execution times gains in some cases, but generally they tend to completely disappear in an optimized build
2. The code size gains from reducing the stack unwinding code are on the order of 5% to 10% but these are completely dwarfed by loop unrolling when using optimizations
3. If you decide to actually use exceptions — without throwing that much — every try and catch block has a small cost, that tends to disappear in an optimized build
4. A throw statement might get in the way of compiler optimization, don’t use it in tight loops
5. If you throw a lot, you should try one of the alternative error handling mechanisms

If you feel tempted to disable exceptions when building your C++ project, think again. Take the time to actually test it. Check if actually improves anything, because it definitely breaks things.

If it is a standalone application, then this will probably affect only yourself — when you start debugging it. But if you are building a target that people will be linking with, I very strongly recommend you to avoid doing this. Otherwise, sooner or later, you will have an user that will spend countless hours debugging a very bizarre problem.

You can find all the code used for this story at:

GitHub - mmomtchev/cpp-exceptions-cost: The true cost of C++ exceptions

References:

1. Google C++ Style Guide https://google.github.io/styleguide/cppguide.html#Exceptions
2. Exceptions and performance, LLVM discussion https://discourse.llvm.org/t/exceptions-and-performance/56185
3. Investigating the Performance Overhead of C++ Exceptions: https://pspdfkit.com/blog/2020/performance-overhead-of-exceptions-in-cpp/
4. P2544R0 C++ exceptions are becoming more and more problematic https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2544r0.html
5. Technical Report on C++ Performance
   https://www.open-std.org/jtc1/sc22/wg21/docs/TR18015.pdf
6. An Introduction to Stack Unwinding and Exception Handling https://www.zyma.me/post/stack-unwind-intro/
7. Debugging random memory corruption with ASAN in a Node.js addon on Windows with MSVC
   https://mmomtchev.medium.com/debugging-random-memory-corruption-with-asan-in-a-node-js-addon-on-windows-with-msvc-6246af0c22c7

The problem that inspired this story:

Using C++ exceptions in Node.js addons on Windows

Or the horrible _HAS_EXCEPTIONS pitfall in Node.js addons on Windows

If you are building Node.js addons, Microsoft and the Node.js core team have conspired to create a truly horrible landmine waiting for you. MSVC carries two distinct std::exception implementations that differ in memory size and behavior. If part of your code is compiled without exceptions enabled, while another part has them, you will get an almost working binary with some very subtle memory alignment errors. This is the case of Node.js itself and node-gyp which builds by default with exceptions disabled. Node.js does not use C++ exceptions and cannot trigger the problem — however any Node.js addon that uses them is affected when running on Windows.

It is because of this problem that I decided to investigate the benefits of those two dreaded compiler options: -fno-exceptions and /EH* that caused me so much pain. MSVC is a particularly vicious offender since the default behavior deviates from the C++ standard — which means that almost every single project overrides it.

Here is more information on this subject.

• A note in the SWIG JavaScript Evolution manual:

GitHub & BitBucket HTML Preview

• A note in gdal-async :

node-gdal-async/common.gypi at ad9eea1f8482bd590c9ad77ea0ecab819aad6053 · mmomtchev/node-gdal-async

• A gist with another example of different behavior of std::exception in MSVC depending on the _HAS_EXCEPTIONS macro:

I am an unemployed engineer living on social welfare in France because of a huge judicial scandal that involves a sexually-motivated extortion with the French police and some of the largest IT companies in the world.

My particular area of expertise is linking C++ and JavaScript.

I am the author of SWIG JavaScript Evolution, the hadron build system and I have authored and maintain a large number of bindings of C++ libraries for JavaScript.

mmomtchev - Overview

Using it is as simple as adding the /fsanitize=address option when compiling. Since we are targetting a Node.js addon, this option would go in binding.gyp :

'msvs_settings': {
  'VCCLCompilerTool': {
    'AdditionalOptions': [
      '/fsanitize=address'
    ],
  }
}

Then we have to rebuild everything. Like, literally, everything. On Windows, it is not possible to link release and debug versions. This means that if your addon requires any libraries, you will have to rebuild them with the exactly same options.

Once you have your new magic self-debugging binary addon, you will be up for a very unpleasant surprise. Node.js refuses to load it with the absolutely awesome error message:

File not found

You can double- even triple-check all your path names — everything will be in order. Alas, this is the only excuse Node.js knows for not loading your library — whatever the error is — you will always get this message. Which will probably be the correct one in 99% of the cases.

The problem is that, just like on Linux and macOS, ASAN does not accept not being the very first DLL to be loaded. But unlike on Linux and macOS, it does not get the chance to tell you about it.

Head to https://github.com/microsoft/Detours — a free library for implementing interceptors for Windows by Microsoft Research. Clone the repository, then launch a Visual Studio Code shell and build it by simply launching in its root:

git clone https://github.com/microsoft/Detours
cd Detours
nmake

You need one of its samples, samples\setdll — you will find it in bin.X64\setdll.exe after building the library.

Now find this library:

clang_rt.asan_dbg_dynamic-x86_64.dll

It is usually located in some variation (depending on the exact version) of this path:

C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.37.32822\bin\Hostx64\x64\clang_rt.asan_dbg_dynamic-x86_64.dll

Make a local copy of node.exe — it is usually located in Program Files :

copy "C:\Program Files\nodejs\node.exe" .

Then manually inject the ASAN DLL as a dependency:

setdll /d:clang_rt.asan_dbg_dynamic-x86_64.dll node.exe

Voilà, this custom Node.js will be able to load ASAN-enabled addons.

Or, alternatively, use withdll to simply launch node.exe without modifying it:

withdll /d:clang_rt.asan_dbg_dynamic-x86_64.dll node.exe

If this does not work — which might be the case if you haven’t compiled in debug mode — try with the release version:

setdll /d:clang_rt.asan_dynamic-x86_64.dll node.exe

I am an unemployed IT engineer with a story to tell. I work on open-source software with a particular interest in Node.js addons and JavaScript / C++ interaction. You can find me on Github:

mmomtchev - Overview

(this tutorial will continuously evolve to match SWIG Node-API, the current version is from September 9th 2023 and includes asynchronous execution and TypeScript which still haven’t been merged to the main trunk)

Not so long ago, while working on a Node.js project which generated map tiles, I was very surprised to find out that ImageMagick — the quintessential image processing library, initially released in 1990 — was surprisingly absent from its ecosystem. Sure, there were some wrappers around the CLI tools — but they didn’t even come close to the full scale of features available in it.

Being someone with lots of spare time on my hands — you can check my Github profile for my story — I decided that it was time to right this wrong and do so by working smart instead of working hard.

Now, if you are part of the younger generation of Noders, you probably have never heard of SWIG before. And it is a pity, because this amazing piece of software can easily crash the job market for high-level language bindings writers — by fully automating their jobs.

So I found myself looking at SWIG for Node.js for the second time during the last few years — the first time being when I started maintaining gdal-async — the asynchronous GDAL bindings for Node.js. And once again, I came to the conclusion that the Node.js support was barely usable — it hadn’t been updated for the last 10 years — which in the Node.js world was comparable to the evolution from feudalism to industrial society.

Now, ImageMagick is an absolutely huge C++ project — the SWIG-generated Node.js bindings are about 400,000 lines of code. Hand-writing these would probably have costed upwards of 1 man-year.

With SWIG, it took me two weeks to implement a modern NAPI-based backend — and then one more week to create the ImageMagick bindings. And only because this was the SWIG NAPI testing project and there were some rough edges to polish.

This was the perfect opportunity to kill three birds with one stone:

• Publish full ImageMagick bindings for Node.js
• Write a modern, NAPI-based, Node.js backend for SWIG
• Write a simple tutorial to unleash a torrent of C++ libraries for Node.js

Enter SWIG

SWIG is a C++ header compiler that can produce bindings for interpreted and dynamically typed languages that cannot link directly with C/C++ shared libraries. It supports a large number of languages, including JavaScript.

Now, SWIG is a complicated piece of engineering and no matter what, you won’t be able to avoid delving deep into its huge documentation.

Still, this tutorial’s goal is to allow you to quickly understand some basic concepts and bootstrap your next Node.js addon project.

Learning and using SWIG is definitely not easy. It is an entire computer language with its own C++ transpiler. It eliminates the work that is necessary to write a huge native C++ addon. However, it does not eliminate the requirement of having the necessary skills to do so.

When using SWIG, you will be expected to be able to look and understand the generated code — especially if you will be writing advanced typemaps.

So, if you have never worked on a Node.js binary addon — expect a very steep learning curve.

As of September 9th 2023, the bulk of the Node-API support in SWIG has been merged in the main trunk. It will be available in SWIG 4.2.0. The asynchronous execution and the TypeScript support is still being reviewed and undergoing polishing.

The full SWIG Node-API including asynchronous execution and TypeScript support can be used by checking out my development branch at

https://github.com/mmomtchev/swig#mmom

node-magickwand

You can find the resulting project, which is a real-world Node.js binary addon based on a very complex C++ library with multi-OS support here:

GitHub - mmomtchev/node-magickwand: Territorialing the map

The scaffolding

Create a node-addon-api skeleton:

sudo npm install -g generator-napi-module
mkdir node-magickwand && cd node-magickwand && yo napi-module

SWIG can compile C++ headers, but it usually needs some help with deducing how things work. Its most basic block is the interface .i file. Create its skeleton:

%module magickwand

%{
#include <Magick++.h>
#include <MagickWand/MagickWand.h>
#include <iostream>

using namespace Magick;
%}

%include "cpointer.i"
%include "std_string.i"
%include "typemaps.i"

The very first thing we start with is to tell SWIG how it is supposed to access the C++ library we will be working with. These are the #include statements necessary to bring the ImageMagick definitions into a C++ program. The %{ %} block — called a verbatim block — is a block that SWIG will simply include verbatim in the generated wrappers.

Then, we have the standard JavaScript typemaps — we won’t be writing code that converts v8::String (wrapped in a Napi::String) arguments to std::string arguments — SWIG NAPI comes with the basic types already supported.

%rename(call) operator();
%rename(clone) operator=;
%rename(equal) operator==;
%rename(notEqual) operator!=;
%rename(gt) operator>;
%rename(lt) operator<;
%rename(gte) operator>=;
%rename(lte) operator<=;

This part is almost mandatory in any JavaScript project — JS does not have operator overloading, so we have to rename those methods. The first line means that when dealing with the callable object transparentImage we won’t be calling transparentImage(im) — we will be calling transparentImage.call(im).

The main dish

%nspace;
namespace MagickCore {
  %include "../swig/magickcore.i"
  %include "../swig/magickwand.i"
}
%include "../swig/magick++.i"

Finally, we bring in all the definitions that we will be compiling. This is different than the verbatim block — the verbatim block is a piece of code that will be directly included in the generated code. Here, we are actually compiling in SWIG. SWIG has two ways of absorbing C++ headers — %include which means include and generated wrappers for everything you see — and %import — which means acquaint yourself with the types mentioned there — but do not generate wrappers for them. The second form is typically used for low-level stuff that SWIG needs to be aware of.

For example, ImageMagick has both an old plain C API — called MagickCore and a newer higher-level C++ API called Magick++. As many methods share the same name, in order to avoid collisions, we have to enable the namespaces support — %nspace — and to include the old C API in a separate namespace.

Typically, MagickCore is precisely the type of header files that you might consider using an %import for. They contain some type definitions that are used by the other API, but one will probably never need these from JavaScript.

Normally, here you would have to %include or %import every single header file of your target project. SWIG does not follow #include statements unless specifically told to — and in most normal projects you won’t need this very unusual and hard to use feature. You won’t need the standard class libraries either — SWIG already includes its own definitions for classes such as std::vector or std::string which you have to use. You just have to list all the header files in the exact order of their dependencies. For ImageMagick, with its 120 header files, this is a daunting task and I had to write a dependency analyser and generator — you can check it in src/deps.js— as well as its output in swig/magickcore.i. You won’t need this in most normal projects and I won’t cover it here.

Sweeping the unusable methods under the carpet

Every C++ project has methods that won’t be needed or won’t even be usable from Node.js — and ImageMagick is not an exception.

We start by ignoring the methods that depend on a va_list:

%ignore LogMagickEventList;
%ignore ThrowMagickExceptionList;

We also ignore everything that has custom or special memory allocation — these are spread around the various classes — so we take advantage of the regular expressions support:

%rename("$ignore", regextarget=1) "NoCopy$";
%rename("$ignore", regextarget=1) "Allocator";

The hard methods — returning a container from std::vector

Most complex C++ projects will inevitably include some methods that SWIG will be unable to handle without some help. Take a look at this one:

template <class Container > 
  void coderInfoList( Container *container_, 
                 CoderInfo::MatchType isReadable_   = CoderInfo::AnyMatch, 
                 CoderInfo::MatchType isWritable_   = CoderInfo::AnyMatch, 
                 CoderInfo::MatchType isMultiFrame_ = CoderInfo::AnyMatch 
);

This method allows the user to retrieve the descriptors of all image file formats that have been compiled in. You have to pass a pointer to an std compatible container in which you will receive the resulting list. Here is how you are supposed to use it:

list<CoderInfo> coderList; 
  coderInfoList( &coderList,        // Reference to output list 
              CoderInfo::TrueMatch, // Match readable formats 
              CoderInfo::AnyMatch,  // Don't care about writable formats 
              CoderInfo::AnyMatch); // Don't care about multi-frame support

First of all, C++ templates must be instantiated when compiling. JavaScript won’t be able to call this method unless it has been pre-instantiated.

So this is the very first thing we will need to tell SWIG:

%template(coderInfoArray)
   std::vector<Magick::CoderInfo>;
%template(coderInfoList) 
   Magick::coderInfoList<std::vector<Magick::CoderInfo>>;

Then, we will have to include some hand-written code to transform these input arguments. This is called a SWIG typemap:

%include "std_vector.i"

%typemap(in, numinputs=0)
    std::vector<Magick::CoderInfo> *container_
{
  $1 = new std::vector<Magick::CoderInfo>;
}

%typemap(argout)
    std::vector<Magick::CoderInfo> *container_
{
  $result = SWIG_NAPI_NewPointerObj(env,
                          $1, $1_descriptor, SWIG_POINTER_OWN);
}

%typemap(tsout)
  std::vector<Magick::CoderInfo> *container_
"std.coderInfoArray";

We create three typemaps here.

First, an in typemap, that handles arguments of type std::vector<Magick::CoderInfo> *. We can apply it to all such arguments — or only to arguments named container_ — which is probably safer. This typemap works without expecting any arguments coming from JavaScript — it effectively eliminates this argument for the JavaScript caller — this is what numinputs=0 does. JavaScript callers will call this method without its first argument. Then, we tell SWIG to initialize this first argument — which we use $1 to refer to — with a new statement. We create a an empty std::vector for it.

The second typemap is an argout typemap. SWIG applies it when exiting the method. We use the same type specification as the first one — to make sure that it is applied whenever the first one is applied. Here we assign the method result $result a new wrapped JS object by transferring ownership — because we used new — with the SWIG_POINTER_OWN flag. $1 is the method argument that we assigned in the input typemap. $1_descriptor is its SWIG type descriptor.

The third typemap — tsout— is required only if you enable the TypeScript support — it specifies the TypeScript return type of the method.

If you have never worked on a binary Node.js addon this might not be immediately clear. Every C++ object that will be visible to JavaScript must have a JS wrapper that implements JS-callable methods. Luckily, SWIG already includes a JS-compatible std::vector that we can access by including std_vector.i. SWIG_NAPI_NewPointerObj creates this wrapper.

Voilà, we have effectively transformed this C++ invocation:

list<CoderInfo> coderList; 
coderInfoList( &coderList,        // Reference to output list 
            CoderInfo::TrueMatch, // Match readable formats 
            CoderInfo::AnyMatch,  // Don't care about writable formats 
            CoderInfo::AnyMatch); // Don't care about multi-frame support

to this JS invocation:

const list = coderInfoList(Magick.TrueMatch, Magick.AnyMatch,
    Magick.AnyMatch);

Instead of expecting a pointer to a container, the JS version of this method will simply return a wrapped std::vector that we can access from JavaScript. This SWIG-provided object implements the size() and get() methods.

The hard methods — a void pointer from a Buffer

There are a number of methods in Magick::Blob such as Magick::Blob::update or one of the constructors Magick::Blob::Blob that expect arguments of the form const void *data_, size_t length_. We want to the JavaScript caller to be able to invoke these with a single Buffer.

If we include , SWIG NAPI already provides these typemaps out of the box for arguments named const void *buffer_data, const size_t buffer_len if we include node_buffer.i. We can use an assignment to add a new case:

%include "nodejs_buffer.i"

%typemap(in)        (const void *data_,const size_t length_) =
              (const void *buffer_data, const size_t buffer_len);
%typemap(typecheck) (const void *data_,const size_t length_) =
              (const void *buffer_data, const size_t buffer_len);
%typemap(ts)        (const void *data_,const size_t length_) =
              (const void *buffer_data, const size_t buffer_len);

This kind of typemap is called a multi-argument typemap. It will be applied when a method expects two consecutive arguments of the given type. The name is optional — we can apply it to all pairs of arguments of this type — or only to those named data_ and length_ — which is the safer choice. We haven’t provided a numinputs=1 — this is the default value. This means that those two arguments will be represented by a single JavaScript argument.

The hard methods — a void pointer from a TypedArray

Let’s take a look at another twisted example, one of the Image class constructors:

Image::Image(const size_t width_, 
  const size_t height_,
  std::string map_,
  const StorageType type_,
  const void *pixels_);

It expects a raw pointer to the image data, dimensions and a data type.

We want to make it work with a TypedArray.

First of all, we use a verbatim block to embed a function that converts the NAPI type to Magick::StorageType directly into the final code:

%{
inline Magick::StorageType GetMagickStorageType(
    Napi::Env env, const Napi::TypedArray &array) {

  switch (array.TypedArrayType()) {
    case napi_int8_array:
    case napi_uint8_array:
    case napi_uint8_clamped_array:
      return MagickCore::CharPixel;
    case napi_int16_array:
    case napi_uint16_array:
      return MagickCore::ShortPixel;
    case napi_int32_array:
    case napi_uint32_array:
      return MagickCore::LongPixel;
    case napi_float32_array:
      return MagickCore::FloatPixel;
    case napi_float64_array:
      return MagickCore::DoublePixel;
#if (NAPI_VERSION > 5)
    case napi_bigint64_array:
    case napi_biguint64_array:
#endif  // (NAPI_VERSION > 5)
      return MagickCore::LongLongPixel;
  }
  SWIG_Error(SWIG_ERROR, "Invalid type");
  // Avoid a warning
  return MagickCore::CharPixel;
}
%}

Nothing too complicated, nothing unusual.

Then we create a multi-argument input typemap:

%typemap(in)
  (const Magick::StorageType type_, void *pixels_)
  (Napi::TypedArray _global_typed_array)
{
  if ($input.IsTypedArray()) {
    _global_typed_array = $input.As<Napi::TypedArray>();
    $1 = GetMagickStorageType(env, _global_typed_array);
    $2 = reinterpret_cast<void*>(
      reinterpret_cast<uint8_t *>(
        _global_typed_array.ArrayBuffer().Data()) +
        _global_typed_array.ByteOffset());
  } else {
    SWIG_exception_fail(SWIG_TypeError,
      "in method '$symname', argument $argnum is not a TypedArray");
  }
}

The single input argument coming from JavaScript is referred as $input. It is of type Napi::Value.

Note, that this typemap also creates a local variable in the wrapper method — this is the second expression in parentheses.

First thing first, we check if this argument is a JavaScript TypedArray. If it is not, we throw a TypeError. It is important to throw a TypeError — since this is what the overloading dispatcher uses to determine if it should try another overloaded method signature.

Then we use the previously embedded function to get an ImageMagick-compatible StorageType. Then we proceed to extract the raw pointer to the underlying data of the TypedArray. This is the only correct way to do so. If you have previously used a TypedArray and you got its pointer by simply calling array.ArrayBuffer().Data() — then immediately go back and fix your code before anyone has noticed what a lousy engineer you are. Unless you apply the ByteOffset(), your code will cause terrible destruction when the user passes an argument produced by the subarray() method in JavaScript. Such errors are known to have caused spectacular space launch failures in the past.

And in order to avoid such regrettable disasters, a JavaScript engineer cannot be allowed to access data beyond the end of its allocated array under any circumstances, no matter how hard he tries to do so. Thus, we will also use a check typemap:

%typemap(check)
(const size_t width_, const size_t height_,
    const std::string &map_, const Magick::StorageType type_,
    const void *pixels_),
(const size_t columns_, const size_t rows_,
    const std::string &map_,
    const Magick::StorageType type_, void *pixels_)
{
  if ($1 * $2 * $3->size() != _global_typed_array.ElementLength()) {
    SWIG_exception_fail(SWIG_IndexError,
      "The number of elements in the TypedArray does not match "
      "the number of pixels in the image");
  }
}

This check typemap will be applied to any method having those five arguments. It uses the previously created variable in the wrapper method and its function is to prevent size mismatches.

Note that this typemap is applied to two different cases — one where the image width is called width_ and another one where it is called columns_ — as these are the two argument names found througout ImageMagick. This is different from the previous declaration where the second expression defined a local variable — note the comma between the two expressions.

Finally, if generating TypeScript bindings, we also have to specify the new TypeScript type that the wrapper will require:

%typemap(in)
  (const Magick::StorageType type_, void *pixels_)
"Uint8Array | Uint8ClampedArray | Uint16Array | Uint32Array | "
"Float32Array | Float64Array";

The very hard methods — a method that returns a void pointer

Take a look at Magick::Blob::data():

const void *data(void);

The ImageMagick creators definitely didn’t think in advance about JavaScript. What can we do about this nightmare?

No amount of argument massaging can produce a safe JavaScript wrapper out of this method.

The only solution is to ignore this method and to replace it with a JavaScript-friendly one:

%ignore Magick::Blob::data() const;
%extend Magick::Blob {
  void data(void **buffer_data, size_t *buffer_len) const {
    *buffer_data = const_cast<void *>(self->data());
    *buffer_len = self->length();
  }
}

We have already seen %ignore. In the case of overloaded methods, you can use it to ignore but one of the signatures — by specifying its arguments. %extend allows you to add methods to an existing C++ class. In this case we simply add a new method that uses the argout version of the nodejs_buffer.i Buffer-compatible signature that we saw earlier. This means that the JavaScript wrapper won’t take any arguments and it will instead return a Buffer. You can check nodejs_buffer.i to see how this works under the hood.

This new method calls the old one through overloading. The old one is still there — it simply won’t be exposed to JavaScript.

Asynchronous execution

One of the most peculiar aspects of the JavaScript language is its way of handling I/O and concurrency by using asynchronous execution. Although this is not by design — it is a reminder of its origin as a language dedicated to UI scripting — it is considered to be a very successful paradigm that allows for very easy and high performance access to parallel programming. This model of concurrency is usually called Green Threads or CoRoutines. It moves all the complexity of handling the parallel execution to the C++ engine.

SWIG Node-API allows the automatic generation of asynchronous wrappers that return a Promise and do the heavy lifting in invisible background threads managed by libuv — the Node.js low-level system library.

Particular care must be taken when enabling asynchronous execution as it bestows to the JavaScript end-user the capability of launching multiple operations — on the same object and by the same method — in parallel. It is up to the binary addon author to implement the exclusion rules governing parallel execution.

SWIG Node-API can implement a default locking, that works for most use cases. It implements mutexes that ensure that every underlying C++ object is used only by a single C++ method at a time. It is not without caveats — about which you should read in the documentation — but it works well enough for ImageMagick.

Enabling the generation of asynchronous wrappers for all classes is as simple as using:

%feature("async:locking", "1");
%feature("async", "Async");
%apply SWIGTYPE  LOCK {SWIGTYPE};
%apply SWIGTYPE *LOCK {SWIGTYPE *};
%apply SWIGTYPE &LOCK {SWIGTYPE &};

The first two lines enable locking and asynchronous execution globally. All asynchronous wrappers will have the same name as their synchronous counterparts with an Async suffix. Then we bring in the default locking typemaps for all types. This means that every method will try to lock all of its SWIG-exported C++ objects before proceeding with the operation.

Alas, in the case of ImageMagick this brings the generated C++ code from about 350k lines to about 700k. Having such an absolutely huge wrapper is not only impractical — its compilation also exceeds the free allotment of RAM by Github Actions. Besides, do we really need an async version of this:

const gm = new Geometry(100, 80);
assert.equal(gm.width(), 100);
assert.equal(gm.height(), 80);

Creating a Geometry and retrieving its dimensions are instantaneous operations. It is a helper class. Adding asynchronous handling and locking will only get in our way. A much more economical approach will be to limit the asynchronous execution and the locking to the heavy-weight classes — essentially Image and some global methods that apply processing and do I/O. These can take anywhere from a few milliseconds to several seconds and must be done without blocking the event loop. I won’t go through the exact selection of asynchronous classes in ImageMagick, but I have grouped them in AsyncClasses.i and then I have defined a macro that allows me to enable async support selectively:

%feature("async:locking", "1");
%define LOCKED_ASYNC(TYPE)
%apply SWIGTYPE  LOCK {TYPE};
%apply SWIGTYPE *LOCK {TYPE *};
%apply SWIGTYPE &LOCK {TYPE &};
%feature("async", "Async") TYPE;
%enddef
%include "AsyncClasses.i"

This allows me to bring them one by one by using a single statement:

LOCKED_ASYNC(Magick::adaptiveBlurImage);
LOCKED_ASYNC(Magick::adaptiveThresholdImage);
LOCKED_ASYNC(Magick::addNoiseImage);
LOCKED_ASYNC(Magick::adjoinImage);
...

This way the size of the final generated code is kept to reasonable levels.

Putting it all together

Invoke SWIG on your .i file to generate the C++ wrappers:

swig -javascript -napi -typescript -c++ \
  -Ideps/ImageMagick/Magick++/lib -Ideps/ImageMagick \
  -DMAGICKCORE_HDRI_ENABLE=1 -DMAGICKCORE_QUANTUM_DEPTH=16 \
  -o swig/Magick++.cxx -outdir swig src/Magick++.i

As you can see, it has a compiler-like command-line interface. You can even pass include paths and add macros. This will produce the actual code for your addon.

This tutorial is provided in the hope that it will pave the road for porting many existing excellent C++ libraries to Node.js.

Previously, this has been a very labour-intensive process that had greatly limited the number of available options for Node.js.

Then simply add the resulting file to your binding.gyp in the sources section:

'sources': [ 'swig/Magick++.cxx' ]

Now you are ready to launch the build through node-gyp:

node-gyp configure
node-gyp build

I am an unemployed engineer that is currently being extorted with the French IT recruitment companies and the French judiciary about a huge sexually-motivated judicial affair involving high-level corruption in the French administration.

I use my free time to create and maintain open-source software. My main areas of interest are Node.js/V8 internals, linking C++ and JavaScript, geospatial software. I am also a paragliding pilot with a keen interest in numerical weather prediction.

mmomtchev - Overview

(part of a series of a slightly philosophical stories by an AI dilettante)

Deep neural networks seem to have revolutionized AI. For now, I would avoid delving too much in ChatGPT — as it merits its own story — but rather at the general adoption of DNNs — which seem to have become an ubiquitous miracle cure in AI. So have we finally started gaining any real insights in how our brain works? Are DNNs our first real success at reverse-engineering ourselves?

Before continuing, let me tell you a personal story. 5 years ago I discovered electric monowheels. I live in downtown Paris and commuting has always been a huge problem — so I instantly fell in love with the concept of the monowheel. The only problem was that I had to learn to ride it. I was in my late 30s, had never skateboarded or rollerskated during my teens, and I haven’t been skiing since my early childhood. I knew this one was going to be difficult. I bought and old second-hand wheel and decided to simply give it a try on my own. The very first time I spent an hour without ever doing more than 50 cm. The next evening, after lots of failing at about 1 m, I was suddenly able to keep myself standing on it for 20 m. Half an hour later, I was riding it without falling too much. On the third day, I used it to get to work. I was stunned, because, initially, it seemed like an absolutely impossible task — than in a few hours it became a breeze. Just like that. Baffled by the experience, my next stop was Wikipedia where I started searching for motor-skills and muscle memory. It is an absolutely fascinating subject. You should probably try learning about it too. Maybe you remember how you learned to ride a bike or drive a car. In the beginning, it was a very tedious conscious process, where you were thinking hard about every step. Then — you simply stopped thinking about it and started doing it. It became embedded in the hardware. Often, just like for DNNs, it is a very sudden process.

So, to answer that question in the beginning, definitely yes, we do have started reverse engineering parts of our brain. It is just not the really important part — the neocortex. We have started cracking the “peripherals”: visual recognition, motor skills, language skills and even gaming strategy — which are mostly intuitive. Now, language skills and gaming strategy are particularly interesting since they have both a “hardware” first-order intuitive part — as well as a higher-order “software” part — and the truth is that this second part is still somewhat lacking in the current generation AI.

When 20 years ago, Deep Blue won its first victory against Kasparov, many noted that humans were still unequaled at extreme complexity — and the one example they frequently gave was Go — a game with a much higher order of complexity compared to chess — in which humans were still impossible to beat. Then there was StarCraft 2 and DOTA 2. Both video games were supposedly fine examples of solution-spaces that were impossible to explore using classical branch-and-bound exhaustive approaches. Only “human creativity”, and human capacity of inventing strategies could secure a win. Personally, for having played — competitively — both of these — even if I never came out of the bottom of the ranking ladders — I consider both of them to be very bad examples. True — these games are not accessible to classical algorithms that simply explore the solutions space. Predicting even 2 or 3 seconds in the future would require considering gazillions of possibilities — and one needs to think minutes in advance to have any chance of winning.

DNNs are however extremely good at precisely this kind of tasks. In fact, this is probably the type of game where a DNN is the absolutely best possible player. They simply have to learn various — not so complex — strategies and to apply them perfectly in what is a very fast-paced game where no human is ever perfect — and where one of the very characteristic differences between the entry-level amateur and the top-level professional player is his APM — actions per minute. Obviously, in these games, DNNs easily gained the upper hand without requiring the huge R&D investment that IBM made for Deep Blue.

I even think that if there was a large corporation with deep pockets and a project to create an entirely mechanic top soccer player, its most difficult problem would probably be the power source — as power storage is a technology in which we are still far behind our own bodies. And of course the gargantuan task of having to analyze thousands of hours of soccer matches that are available only as analog video. DOTA 2 has a Linux API — which meant that the AI creators could focus entirely on the AI itself.

In fact, we have started understanding — and successfully copying — all those basic skills that we are able to learn to perform without thinking. We are still decades away from understanding the higher functions of the brain. Heck, it might even be centuries away. Or maybe there are no other mechanisms in the brain besides what we already know. Maybe it is simply a matter of adding even more neurons. Which is easier said than done, because ChatGPT has been trained on a — very expensive — supercomputer. From what we know, the human brain is not similar to a CPU — but rather to an FPGA. Its most distinctive advantage over DNNs is that it is fully dynamic, capable of adding neurons to existing structures and interconnecting stages on the go. But the hard truth is that we simply do not even know what there is to know for the next step.

Because let’s be honest. We, the computer engineers, didn’t invent anything. Neural networks, reinforcement learning, genetic algorithms — we didn’t come up with those. Evolution produced them. Then they were discovered by the scientists. Only then, we started adapting them, filling the voids — and even — improving them — since nature has never been a perfect designer. So for there to be a significant AI breakthrough — there must be a significant neurology breakthrough first. This is not coming out of a computer lab for sure — it simply has to come from medical science.

About 4 years ago, while working on a typical CPU-heavy geometry optimization problem in Python, I decided to give Node.js a try. Until that moment, I was subscribing to the commonly held opinion that Node.js excelled at I/O, while serious number crunching was firmly inside Python’s territory. No matter how hard I tried, I was never able to beat the Node.js implementation in Python. Both CPython and pypy failed behind and failed hard. Alas, the simplicity and elegance of the Python’s interpretators could not compete with the JIT juggernaut that V8 has become.

Now, don’t get me wrong — Python is still the better language. In the short history of technology, JavaScript is but one of the so many examples of an inferior technology winning over a superior one — VHS, x86, MS-DOS — you don’t have to look hard to find dozens of others. Momentum and installed base are very important when it comes to core technologies — and the Allmighty Web has spoken — JavaScript will be the new general-purpose language for the masses. Like it or not.

However, despite Node.js gaining a huge amount of traction during the last few years, there is still one field where it is lagging probably a whole decade behind Python —and that is precisely number crunching. Even if you have never used Python, you have probably heard about scipy, numpy and pandas and you know at least someone who regularly uses them. They are that good and that widely used.

In the Node.js world we have scijs and now @stdlib — however scijs covers about 5% of the numpy features and @stdlib is a gargantuan task that is still a work in progress. Even if it is growing fast, the community behind it is still orders of magnitude smaller than the scipy community.

Now, if you want to do serious number crunching in the browser — there are still no alternatives. @stdlib is the only way to go. However, if you are targeting only Node.js — then Python has a solution for you — its embedded version can be included anywhere. Python can be integrated with any other language and its integration with Node.js — another somewhat similar interpreted language — can be absolutely flawless.

Enough talk, let’s get to the point

import { pymport } from 'pymport/profixied';
const np = pymport('numpy');

const a = np.arange(15).reshape(3, 5);
const b = np.ones([2, 3], { dtype: np.int16 });

Eh? What is the catch? Too good to be true? What about performance? How does it work? Is this a transpiler? What about the binary code? Does it support all Python?

Yes, it supports all Python and there is no catch. And in fact, the explanation is very mundane. Node.js runs the JS code, Python runs the Python code. Python can be loaded as a shared library and has a very good and mature embedding API. And Node.js has a very good addon API. Both languages being somewhat similar, the integration is nearly perfect. It is also remarkably simple: each Python object is proxied in JS — ie there is a corresponding JS Proxy object that holds a reference to it.

pymport simply implements Python references in Node.js. Nothing more, nothing less. JS objects are managed by the V8 GC. Python objects are managed by the Python GC — but are locked in place while JS is using them.

In this example a is a JS object of PyObject type that holds a numpy array. np is a PyObject of a Python module type. Call toJS() on a Python reference, and you will obtain a JS copy of the underlying object:

import { pymport } from './proxified/index.js';
const np = pymport('numpy');
const list = np.arange(15).reshape(3, 5).tolist();
// list is a reference to a Python list
// it can be converted to a JS array
console.log(list.toJS());
// or you can use Python's own str() built-in
// .toString() is wired to it
console.log(list.toString());

Performance is as good as the slowest part — Node.js won’t run slower because you loaded Python — and Python code won’t run slower because it is embedded in Node.js.

There is a certain memory price to pay though. You load and run both interpreters. As Python is numbers of magnitude lighter the Node.js, it is not that much of a problem. The only thing one must be careful with are the proxy objects:

// This creates a single JS proxy object
// a is a reference to a Python numpy object (overhead: 1 reference)
const a = np.arange(65536);
// list is a reference to a Python list object (overhead: 1 reference)
const list = a.tolist();
// refArray is a JavaScript array of references to Python numbers
// The memory overhead is huge - 65536 separate references
const refArray = a.map((x) => x);
// jsArray is a JavaScript array of numbers, we are now fully in JS land
const jsArray = a.toJS();

But numpy makes heavy use of operator overloading that does not exist in JavaScript?

Python has the solution for you, every overloaded function can be called explicitly:

// living simply
const sum = a.__add__(b);
// or a slightly more snobbish approach
const op = pymport('operator');
const sum = op.add(a, b);

But what about functions and exceptions?

Absolutely natural:

const fn = (x, y) => {
  return x.__add__(y);
};
try {
  const a = np.fromfunction(fn, [2, 3]);
} catch (e) {
  console.error(e);
}

And if I already have an existing scijs Node.js application and I want just one feature of numpy that does not exist in scijs?

You are welcome, numpy arrays can be converted to scijs without even copying the backing-store:

// b is a scijs ndarray
const ref = np.frombuffer(PyObject.memoryview(b.data),
  {dtype: np.int32}).reshape(b.shape);

And pip3? Where does numpy come from in Node.js?

It comes from pip3 of course. When installing pymport you have two choices: use the built-in Python interpreter that comes with it — if you simply type npm install pymport it will quietly sneak itself into node_modules/pymport/lib/binding. You will have to call it npx pympip3, but it will be otherwise indistinguishable from a normal pip3. I have tried as hard as I could to make this work on all OSes and all environments.

Or — you can opt for the advanced installation. Install Python yourself, then rebuild the pymport C++ code to use your own Python installation. npm install pymport --build-from-source will take you on this route. In this case, it will be up to you to manage this installation and add whatever modules you need to it.

For a more detailed documentation and more examples — including expressing some extreme pandas statements, your starting point should be https://github.com/mmomtchev/pymport/wiki — the pymport wiki.

GitHub - mmomtchev/pymport: Use Python libraries from Node.js

If you are interested in its internals — or should I dare to ask — want to even contribute — you can find a brief introduction in the wiki.

I am the world’s first unemployed IT engineer — as I am currently embroiled in an absolutely huge judicial/sex scandal that is being kept under wraps because of its political implications in France. I use this time to work on various open-source projects, related to Node.js/V8 internals, geospatial software as well as everything else that comes my way.

mmomtchev - Overview

Even if I have been living under a rock for quite some time now, it has been absolutely impossible to not be aware that a new version of the ChatGPT bot has been recently released.

In between all the hype, the raving reviews, there has also been a steady influx of stories by various bloggers and pundits about “coding coming to an end, sometime in the next 5 years”.

If you are currently finishing high-school and having second thoughts about choosing IT, be assured, coding is not coming to an end, at least not before the current generation of students retire. It might come an end one day, but we won’t be here to see it for sure.

I have 30 years of software development experience and I admit that I do not know anything about AI. It is one of those technologies that intrigues me — as much as everyone else in fact — but at the end, it never really captured my attention span long enough for something meaningful to come out of it.

In fact, I simply don’t like it.

First of all, progress in AI has always been a very bumpy road. Software engineering is a field that has experienced a tremendous growth and progress in the last 50 years. And every decade has built upon the achievements of the previous one. When it comes to AI, however, every decade has brought a new fashion — but not necessarily progress — I mean linear progress of the type that builds upon everything that came before it.

Once every 10 years, there will be that new spectacular AI technology that will make me rethink my choice and start reading about its inner workings. (I would like to specially thank the Stable Diffusion team for publishing their amazing work and making it accessible to the average layman). Every 10 years, there will be some new AI breakthrough — that will make me reconsider this stance — until I sink a few days into it. And invariably, every 10 years I will discover that what I am reading about is an absolute revolution in making it appear that it was AI.

The previous time I did this was during the mass hysteria surrounding Deep Blue. Since, computers have finally mostly surpassed humans when it comes to chess, but there remain many other games in which humans are simply unbeatable.

AI is a very difficult technology. While many scientific discoveries were made by chance, no engineer ever designed a product that he did not understand. Well, Evolution, Our Creator (the author subscribes to a modern, evolution-based religion) did so — but it took hundreds of millions of years. You know, if you give an infinite number of monkeys and infinite number of typewriters, given an infinite time, one of them will eventually produce the complete works of Shakespeare. We, simple mortal engineers however, we don’t have infinite time or infinite resources. We are limited to designing the systems we understand. And when it comes to human intelligence, it is remarkable how little we currently understand. Especially when compared to the rest of our bodies.

Now repeat after me: we won’t design an AI before understanding the inner workings of the human brain. Not before neurology and psychiatry, the two scientific fields tackling this problem — from the two opposing sides — have advanced to the point they can merge completely into one full and complete understanding of ourselves.

Now, many AI technologies have been based on our limited understanding of the human brain: neural networks, reinforcement learning, fuzzy logic, even the genetic algorithms come from what we have seen from nature. However our current understanding can probably be compared to the first European explorers touring the Chinese coast without disembarking from their ship, then coming back to Europe trying to recreate Chinese cuisine from a smell they picked up along a way. True, it starts smelling like an AI. But the similarities stop here. Because you don’t even know what exactly they were cooking.

If you have been following chess-playing computers, you will know how different the computer playing style is. It is largely an exercise in raw computing power and optimization techniques. Same goes for Alpha Star — if you are a StarCraft fan you should definitely watch some of its games. While very good, it is definitely not human-like. The same applies to the current generation of text to image algorithms — a field that has progressed tremendously in the last five years — go read about them and you will understand why they tend to produce humans with three arms or birds with two heads and why these problems will likely persist for some time.

So, don’t hold your breath for the end of coding. At some point, ChatGPT, or some other related technology, could probably replace Google, but do not expect much more to come out of it. And coding is not coming to an end anytime soon.

GitHub - mmomtchev/react-native-settings-screen: React Native Universal Settings Screen

I, like many other people, was under the impression that React Native applications could easily be bundled for the web. After all, react-native-web is now an official part of React Native.

Turns out, this is easier said then done. There is of course expo, which can make it seem easy, but if you need something less standard, then things can get very rough very quickly.

There is of course the documentation by the original author of react-native-web — but if you browse his issues — and you inevitably will — looking for clues about arcane webpack error messages — you will find tons of issues and you can even trace the growing annoyance of its developer, forced to provide technical support for webpack — over those issues for the last two years — by now he is simply immediately closing all issues about webpack bundling problems. His message is very clear: raw bundling of React Native apps for the Web is not for the faint hearted and if you do not feel like browsing through tons of source code and eventually writing a webpack loader of your own — then better go for expo. It is there for a reason.

Still, if you need some special features, like a web demo of a component in my case, raw webpack bundling is the only way to go.

As I feel that I have accumulated some precious experience in this matter, I decided to share it with you.

The rest of this story will assume you that you have read the original guide at https://necolas.github.io/react-native-web/docs/, then you did exactly how its author said, and nevertheless you got some weird errors.

Here be dragons: webpack error messages

webpack error message when bundling React Native come essentially in two flavors.

Errors about missing components

What is key to understand here is how react-native-web works — it replaces the react-native module with a react-native-web module through an alias — that can be resolved by webpack itself, its babel plugin or the TypeScript loader if you need it. The original configuration relies on webpack — better stick to it. Avoid ts-loader, it is far too complex and will require separate configurations for your code and for the React Native modules— babel is the way to go if you use TypeScript.

So far so good. The only thing necolas didn’t tell you is that his setup requires an ideal world and we do not live in an ideal world. Many 3rd party react-native modules do not play by the rules. Instead of including the react-native libraries through their official entry points, they deep link inside the source. This way of linking is not, and cannot, be supported by react-native-web.

So the key thing that you should notice in this error output is react-native in the call stack. This error message contains a call stack — at the bottom is your code, then it calls @react-navigation, then you enter react-native. This is exactly what should not happen. First clue: If you have react-native in your stack, this is not good — you should have react-native-web. @react-navigation is deep-linking into react-native and you must break this chain somewhere.

Usually, in this case, there will be a component somewhere in this stack that has an alternative implementation in react-native-web — you will have to find which.

A web alternative of Utilities/Platform is provided by react-native-web but webpack cannot find it because of the deep link.

An even better alternative is to simply replace SafeAreaView from react-native-safe-area-context with SafeAreaView from react-native-web, breaking the chain in the middle. As always, the problem lies in a 3rd party module.

A webpack alias can solve this problem:

Errors about invalid syntax

react-native uses some non-standard JavaScript features and one of them is Flow annotations which is the culprit here. You must make sure that all of these files are transpiled by babel. As you followed the original guide exactly how its author said, you already have module:metro-react-native-babel-preset. Now you just have to be absolutely sure that it applies to all those 3rd party modules:

Notice all the additional includes. These are 3rd party modules not covered by the configuration if simply copied and pasted it from the original guide.

The big roadblock

Ok, by now you have a perfectly working webpack.config.js, but guess what, it is still not enough. You have hit the big road block — SafeAreaCompat.

The implementation in react-native-web is not complete and does not support Navigators.

Luckily the folks who made expo for us (frankly they deserve paying them a subscription) have been kind enough to open-source their implementation and we simply borrow it:

npm install — save-dev expo-dev-menu

And then one final webpack alias:

'react-native-safe-area-context': 'expo-dev-menu/vendored/react-native-safe-area-context/src'

If you have reached so far, then you probably have it very close to working. I have tried to provide you not only the ready to use answers but also the methodology I used to get so far. Once again, manually bundling React Native for the Web is not an easy task and, depending on your app, may or may not work.

I am an unemployed engineer with a strong interest in Node.js, React and GIS who is in the middle of a huge sex scandal with political implications in France. Should you require help in setting up React Native projects for the web, I will be more than willing to help you.

mmomtchev - Overview

Create a small empty .pbf or empty .mvt file to avoid 404 client errors

Many GIS tools, including GDAL, can produce MVT tiles from vector data. As the MVT specification does not cover the distribution of the tiles, it is not clear what should be the correct behavior when a given tile at a given resolution does not contain any features.

Currently, GDAL will skip those tiles:

mmom@mmom-workstation:~/velivole/dev/www/tiles/place$ ls 0/10/525
106.pbf  107.pbf  109.pbf  111.pbf  112.pbf  125.pbf
130.pbf  131.pbf  153.pbf

When those tiles are served to an Openlayers client, it will request them and it will receive a 404. If you have an error handler, it will get triggered, otherwise it will more or less ignore it. Other clients may react in a different way.

As the concept of normal errors bothers me, I decided to find a cleaner solution.

Alas, there is no way to modify GDAL to create empty tiles without rewriting major parts of the MVT code. Besides, this behavior is not that bad since it allows to avoid having gazillions of empty files — especially when using very high zoom levels.

The solution that I have found to is to generate a single .pbf file with no features and to use it in the 404 handler of the web server — by configuring it as a custom error page. It is a simple solution that combines all advantages at once.

Alas, GDAL can not generate an empty .pbffile because of its optimization, but you are free to use mine:

https://velivole.b-cdn.net/tiles/empty.pbf

for the gzip precompressed version, or:

https://velivole.b-cdn.net/tiles/uncompressed_empty.pbf

for the raw version.

It is a completely universal file that does not depend on the projection or the tilegrid.

The file being very small, the gzipped version is actually larger than the raw one, but it won’t interfere with your custom HTTP headers governing precompressed .pbf files.

All the example code can be found in this repository:

GitHub - mmomtchev/napi-inherit: An example of shared C++/JS inheritance with N-API

During the last few years most major Node.js addons switched from the older NAN (Native Abstractions for Node.js) to the newer Node-API. It offers numerous advantages: fully compatible binary ABI across different Node.js versions, native C++ class and object semantics — including constructors and destructors — and full compatibility between C++ and JS exceptions. During those years, only one major problem has remained unsolved and that is the question of C++ class inheritance — which used to work very well in NAN — and it is still not supported in Node-API. For example, the largest addon that I maintain — the GDAL bindings for Node.js — makes extensive use of C++ class inheritance — and until recently I have been unable to come up with a satisfying solution.

I will very briefly sum up the reasons why this problem has remained stalled for the last 5 years since it was first discussed in an issue:

Substitute for Inherit · Issue #229 · nodejs/node-addon-api

I won’t go through all the details of why this can’t be done in Node-API — you can read the rest — but it all comes down to V8 being unable to retrieve the v8::FunctionTemplate used for creating a v8::Function. As Node-API aims to be an universal and future-proof API for interfacing with any JS engine — even if V8 is still the only one for which there is full support, its project team refuse to extend it to provide access to a V8-specific feature. NAN, which was tied to the V8 engine did not have this problem as it simply allowed access to v8::FunctionTemplate::Inherit . However, even with NAN, extending from EventEmitter was not possible — as there was no way to retrieve its v8::FunctionTemplate .

There are various approaches to solving the problem — none of them are perfect — and you can read about some of them in the issue. Throughout this story, I will show you mine which I think is the least bad.

The requirement

• Use only Node-API, no direct V8 calls which will result in loss of binary compatibility
• In JS, the classes must appear inherited for the end-user when using instanceof
• The C++ implementation can share method code in a base class
• Support inheriting from EventEmitter (ie inheriting from a JS class)

Case 1: Inheriting a C++ class from another C++ class and exporting the class hierarchy to JavaScript

As you know, in Node-API all C++ classes that will be exported to JS must inherit from ObjectWrap<T> which is a CRTP class.

If we want to avoid the dreaded Illegal invocation V8 error, we will have to have different template parameters in the superclass and in the subclass. There is only way to make it and this is to declare another CRTP class:

template <class T> class Base: public Napi::ObjectWrap<T> {
public:
  Base(const Napi::CallbackInfo &);
  virtual ~Base(){};
  
  static Napi::Function GetClass(Napi::Env);

  // shared methods go here
  virtual Napi::Value Do(const Napi::CallbackInfo &);
  Napi::Value Tell(const Napi::CallbackInfo &);
};

This will be our Base class. It will hold all the members that will be shared between the subclasses. Now, the problem is that this class cannot be instantiated, so will have to create a special leaf class that we will be using when instantiating Base :

class BaseInstance: public Base<BaseInstance> {
public:
  using Base::Base;
  virtual ~BaseInstance(){};
};

We can still export this class to JavaScript under the name Base if we desire so. When we want to extend Base we will be using Base , and when we want to instantiate it — we will be using BaseInstance . Exporting the class to JS is straight-forward:

template <class T> Napi::Function Base<T>::GetClass(Napi::Env env) {
  return DefineClass(env, "Base",
                     {
                         InstanceMethod("do", &Base::Do),
                         InstanceMethod("tell", &Base::Tell)
                     });
}

And then when registering the module we can simply do:

exports.Set("Base", BaseInstance::GetClass(env));

Note that we name it Base but we actually call BaseInstance .

Let’s now extend this class. Create another leaf class that will hold the extended methods, nothing too fancy here:

class Extended : public Base<Extended> {
public:
  Extended(const Napi::CallbackInfo &);
  virtual ~Extended(){};

  static Napi::Function GetClass(Napi::Env);
  
  // This method overrides the one in the base class
  virtual Napi::Value Do(const Napi::CallbackInfo &);
};

The secret of this recipe is the way we register the subclass in V8:

Napi::Function Extended::GetClass(Napi::Env env) {
  return ObjectWrap<Extended>::DefineClass(
      env, "Extended",
      {
          // Override this method
          ObjectWrap<Extended>::InstanceMethod("do", &Extended::Do),
          // Inherit this method
          ObjectWrap<Extended>::InstanceMethod("tell", &Base::Tell),
      });
}

The C++ inheritance is now set up. We need just one last step to make instanceof in JavaScript work properly and this is accomplished by using Object.setPrototypeOf :

Napi::Function ClassBase = BaseInstance::GetClass(env);
Napi::Function ClassExtended = Extended::GetClass(env);
exports.Set("Base", ClassBase);
exports.Set("Extended", ClassExtended);
Napi::Function setProto = env.Global()
                              .Get("Object")
                              .ToObject()
                              .Get("setPrototypeOf")
                              .As<Napi::Function>();
setProto.Call({ClassExtended, ClassBase});
setProto.Call({ClassExtended.Get("prototype"),
                ClassBase.Get("prototype")});

In this example, as through-out the rest of the tutorial I won’t be making any error-checking — it is highly recommended that you enable C++ exceptions if you intend to do this too.

We retrieve the V8 method Object.setPrototypeOf and then we setup the JS prototype chain to make the two classes appear inherited. Voila, we are done.

These two classes are almost indistinguishable from two JS classes inherited by using extends in JavaScript. The only — very minor — difference is that when calling extended.tell() we will invoke Extended.prototype.tell() and not Extended.prototype.__proto__.tell()which is the same as Base.prototype.tell() . In our case the subclass will appear to have its own tell() method and the redirection to the base class method will happen at the C++ level.

Case 2: Extending EventEmitter

The other frequently encountered pattern is extending Node.js’ EventEmitter so that the C++ object can be compatible with the event API.

This one is a little bit uglier since we will have to call require from C++ —as EventEmitter is not defined unless one imports its definition.

There is nothing special about the declaration of the class itself, except that it will have to manually hold a reference to its JS parent:

class MyEmitter : public Napi::ObjectWrap<MyEmitter> {
public:
  MyEmitter(const Napi::CallbackInfo &);

  void Ping(const Napi::CallbackInfo &);

  static Napi::Function GetClass(Napi::Env);

private:
  // This is the quirk
  static Napi::FunctionReference *EventEmitter;
};

When initially setting up the class, this reference must be initialized:

Napi::Function MyEmitter::GetClass(Napi::Env env) {
  Napi::Function self =
      DefineClass(env, "MyEmitter",
                  {
                      InstanceMethod("ping", &MyEmitter::Ping),
                  });

  // require from C++ needs some acrobatics
  // (the ugly part is in the JS file)
  Napi::Function require = env.Global()
                          .Get("require").As<Napi::Function>();
  Napi::Function ee = require.Call({Napi::String::New(env, "events")})
                          .ToObject()
                          .Get("EventEmitter")
                          .As<Napi::Function>();

  // This is the visible inheritance
  Napi::Function setProto = env.Global()
                                .Get("Object")
                                .ToObject()
                                .Get("setPrototypeOf")
                                .As<Napi::Function>();
  // Same approach as the C++/C+ inheritance
  // This makes instanceof work
  setProto.Call({self, ee});
  setProto.Call({self.Get("prototype"), ee.Get("prototype")});

  // Keep a static reference to the constructor
  MyEmitter::EventEmitter = new Napi::FunctionReference();
  *MyEmitter::EventEmitter = Napi::Persistent(ee);
  return self;
}

Now when creating object of this class, there will be no one to call the superclass constructor for you — remember that you are extending across the JS/C++ boundary — and neither the C++ compiler neither V8 know anything about this. You will have to do this yourself:

MyEmitter::MyEmitter(const Napi::CallbackInfo &info) : ObjectWrap(info) {
  // Call the super class constructor
  MyEmitter::EventEmitter->Call(this->Value(), {});
}

Your JS to C++ inheritance is now set up. When accessed from JS, MyEmitter will be next to indistinguishable from a JS class extended from EventEmitter . There is only one very ugly last caveat, you will have to add this line in the beginning of your JS code:

globalThis.require = require;

This will allow you to easily retrieve require from C++.

Calling your JS superclass methods from C++ will also be manual and it will need to go through V8. Here is an example of calling super.emit('data', 'pong') :

void MyEmitter::Ping(const Napi::CallbackInfo &info) {
  Napi::Env env = info.Env();
  Napi::Object self = this->Value().ToObject();
  Napi::Function emit = self.Get("emit").As<Napi::Function>();
  emit.Call(this->Value(),
            {Napi::String::New(env, "data"),
            Napi::String::New(env, "pong")});
}

And of course, you could cache the first three lines in order to do this initialization only once.

My name is Momtchil Momtchev and I am an unemployed engineer with over 20 years of experience in the IT industry — mostly networking and low-level system engineering. For the last 6 years I have focused mostly on Node.js internals. I develop and maintain a number of binary Node.js addons.

I am at the center of a huge judicial scandal after an employer tried intervening in my sex life with the help of the French police, then tried extorting me to back off from suing him because it would expose his own problem. The affair has continued for many years now and has affected more than one open-source project.

mmomtchev - Overview

This article is the sequel of:

In 2021, is there still a huge performance difference between JavaScript and C++ for CPU-bound…

If you have never read it, you should probably start with it.

Recently, while working on ExprTk.js I found that in some cases, especially when using floating point numbers, scijs/cwise made V8 produced a remarkably fast code from one particular function:

const fn = (x) => x*x + 2*x + 1

I couldn’t resist, so I disassembled its output and I was, once again, amazed by its remarkable efficiency. Since I already had a previous story where I had clearly underestimated its performance, I decided to right that wrong and publish a sequel.

While I was at it, I also decided to examine one very common dilemma every JavaScript developer has faced, namely the eternal question of is using aforEach loop slower than a normal one and if so — why.

Momtchil Momtchev on Twitter: "forEach was the JS way for quite some time, then they told us that the extra function call was expensive, then they told us that the new V8 was very good at inlining, then they started making us vote... 😀I guess it comes down to the language you were using the most before JS / Twitter"

forEach was the JS way for quite some time, then they told us that the extra function call was expensive, then they told us that the new V8 was very good at inlining, then they started making us vote...

So, first things first, the code.

Let’s examine the various functions:

Let’s examine the various functions.

Old developers with lots of experience with compiled languages will immediately tell you that #1, the direct approach is surely the best one. The #2 help isn’t really needed — the compiler will optimize away the multiple memory accesses for sure. And calling a function, #3, is a good test if your compiler has an excellent inline optimizer. If you are not aware of the subtle differences in #4/#5, you should probably think that these are equivalent to #3. What about #6 and #7? Every time we ask the V8 gurus, we get a different answer, so probably it is time to finally check this for ourselves.

Ok, lets see the results now.

….ta-da…

…and the winner is…

#1 direct: 6.396ms
#2 direct with help: 4.409ms
#3 with function: 5.076ms
#4 with function and variable creation: 235.577ms
#5 with function and variable creation: 15.278ms
#6 with map: 12.399ms
#7 with forEach: 10.519ms
#8 two slices: 6.998ms
#9 two slices with cheese: 7.856ms

Well, turns out V8 is remarkably good at some tasks, but still needs some help for other tasks. This one should definitely end on a post-it on one of the V8 developers’ screen. #2 vs #1 should be automatic. It will be even faster as it will avoid the creation of a dynamic variable on the stack.

#3 is where we discover the (almost) free lunch in JS — functions in JS are a dime a dozen. You can safely use and abuse them.

If no one ever told you that you should never use for..inwith an Array — after looking at #4, now you will remember it. It was made for Objects and it has many problems, including not guaranteeing order, and also creating temporary Arrays.

And of course, #5, #6 and #7. Now it is official — forEach should stop blaming the function call for what is clearly its own fault. All these methods of Array traversal are suboptimal and should be avoided when possible. In V8, a simple for loop will be directly compiled, while these rely on more complex builtin implementations written in Torque. for..offor example supports using the Iterator protocol of the underlying object and can be used with every Object that implements it. These methods do not have any added value when used with an Array.

#8 and #9 show the dynamic compilation cost — which is less than I previously thought. The role of the cheese in #9 is to break the compiler optimization — because it initially compiled the function to accept only floating point numbers. Calling it with a different argument forces a recompilation. That one millionth and one call costs as much as hundred thousand compiled iterations. Still, this is clearly not as expensive as you might have believed — V8 recompilation is very fast.

Now to go back to my initial observation.

In fact, unlike scijs/ndarray-ops, which uses the slightly slower #1 form, scijs/cwise uses the most efficient form possible — #2.

In fact, when using #2 on x86–64 — as is the case of scijs/cwise, V8 produces this absolutely amazing machine translation which has only 2 memory accesses per iteration and keeps everything in a register:

movapd  %xmm1,%xmm2        # x has been previously loaded in xmm1
addsd   %xmm1,%xmm2        # x+x = 2*x in xmm1
movapd  %xmm1,%xmm3        # the previous add is still running
mulsd   %xmm1,%xmm3        # x*x in xmm3
addsd   %xmm2,%xmm3        # x*x+2*x in xmm3
lea     (%r11,%rax,1),%rdx # calculate output offset
addsd   %xmm0,%xmm3        # constant xmm0=1, x*x+2*x+1 in xmm3
movsd   %xmm3,(%rdx,%r15,8) # store the result

+2*x has been transformed to +x+x which is slightly faster and avoids using a constant that must be loaded into an FPU register. Instructions are correctly interleaved to take advantage of the super-scalar architecture. And — something I previously believed was absent from V8 — instead of being loaded at each iteration, the constant 1 is being held throughout the loop in a static register — xmm0. This is clearly indicative of a very good register optimization — unlike the example from my previous story.

In fact, this piece of machine code is equivalent to what gcc or clang would produce with -O3 maximum optimization. Yes, on this particular example, when using floating point numbers, V8 runs with the same speed as highly optimized C++ code. Integer would have added a few more JOinstructions for exception handling.

Remember to tell this to everyone who still intends to rewrite scijs in C++.

Or to whoever told you that JavaScript was ill-suited for data-mining.

mmomtchev - Overview

I am a hungry engineer who is currently unemployed and turned open source developer because my ex-employers are extorting me to cover up a remarkably ugly sex scandal. I do mostly Node.js and V8 stuff.