Navigating Node.js C++ code

class: center, middle

# Navigating Node.js C++ code

The quick version <br />
<small>(Terms and conditions apply)</small>

Anna Henningsen <br />
she/her <br />
@addaleax

<br />

---

# Layers (almost accurate)

<table>
  <tr>
    <th>Is called …</th>
    <th>Is a …</th>
    <th>Owns e.g. …</th>
    <th>Relates to …</th>
  </tr>
  <tr>
    <td><code>v8::Context</code></td>
    <td>Set of JS builtins</td>
    <td><code>Array.prototype</code></td>
    <td>n <code>Context</code>s per 1 <code>Environment</code></td>
  </tr>
  <tr>
    <td><code>node::Environment</code></td>
    <td>Set of Node.js API instances</td>
    <td><code>net</code> module</td>
    <td>n (≈ 1) <code>Environment</code>s per 1 <code>Isolate</code></td>
  </tr>
  <tr>
    <td><code>v8::Isolate</code></td>
    <td>JS engine runtime</td>
    <td>JS heap, GC</td>
    <td>n (≈ 1) <code>Isolate</code>s per 1 thread</td>
  </tr>
  <tr>
    <td>Thread</td>
    <td>Execution context</td>
    <td>Event loop</td>
    <td>n threads per process</td>
  </tr>
</table>

---

# V8 API concepts

```c++
/* ... */
v8::Isolate* isolate = ...;
v8::HandleScope handle_scope(isolate);

v8::Local<v8::Context> context = isolate->GetCurrentContext();
v8::Local<v8::String> str = OneByteString(isolate, "foobar");
{
  v8::HandleScope inner_handle_scope(isolate);
  v8::Local<v8::Object> obj = v8::Object::New(isolate);
  // Empty (“Nothing”) Maybe/MaybeLocal = pending exception → Return to JS!
  if (obj->Set(context, str, v8::Integer::New(isolate, 42)).IsNothing())
    return;
}
// `obj` can be GC'ed now, `str` is still there
```

---

# Node.js binding function

```c++
void ErrName(const FunctionCallbackInfo<Value>& args) {  // Implicit HandleScope
  // args = { env | return-value-placeholder | args.This() | args[0], args[1], ... }
  Environment* env = Environment::GetCurrent(args);
  int err;
  // Int32Value() returns Maybe<int32_t>
  if (!args[0]->Int32Value(env->context()).To(&err)) return;
  CHECK_LT(err, 0);  // Super-easy way to crash Node
  const char* name = uv_err_name(err);
  args.GetReturnValue().Set(OneByteString(env->isolate(), name));
}
```

---

# Binding to JS

```c++
void Initialize(Local<Object> target,  // exports
                Local<Value> unused,   // module
                Local<Context> context) {
  Environment* env = Environment::GetCurrent(context);
  Isolate* isolate = env->isolate();
  target->Set(FIXED_ONE_BYTE_STRING(isolate, "errname"),
              env->NewFunctionTemplate(ErrName)
                  ->GetFunction(env->context())
                  .ToLocalChecked());
  // Same thing, but nicer:
  env->SetMethod(target, "errname", ErrName);
}

NODE_MODULE_CONTEXT_AWARE_INTERNAL(uv, node::Initialize)
```

---

# A new `setImmediate()`

```js
const { Immediate } = internalBinding('fakeSetImmediate');
function setImmediate(cb, ...args) {
  const immediate = new Immediate();
  immediate.ondone = () => cb(...args);
  immediate.start();
}
```

```c++
void Initialize(Local<Object> target, Local<Value> unused, Local<Context> context) {
  Environment* env = Environment::GetCurrent(context);
  Local<FunctionTemplate> tmpl = env->NewFunctionTemplate(ImmediateWrap::New);
  tmpl->InstanceTemplate()->SetInternalFieldCount(1);
  env->SetProtoMethod(tmpl, "start", ImmediateWrap::Start);

target->Set(FIXED_ONE_BYTE_STRING(env->isolate(), "Immediate"),
              tmpl->GetFunction(env->context()).ToLocalChecked());
}

NODE_MODULE_CONTEXT_AWARE_INTERNAL(fakeSetImmediate, Initialize)
```

---

```c++
class ImmediateWrap : public AsyncWrap {  // AsyncWrap = BaseObject + async context
  ImmediateWrap(Environment* env, Local<Object> object) : AsyncWrap(env, object) { MakeWeak(); }
  static void New(const FunctionCallbackInfo<Value>& args) {  // 'public' JS constructor
    CHECK(args.IsConstructCall());
    Environment* env = Environment::GetCurrent(args);
    new ImmediateWrap(env, args.This());  // Store instance internally on `this`
  }
  static void Start(const FunctionCallbackInfo<Value>& args) {  // prototype method
    ImmediateWrap* immediate = Unwrap<ImmediateWrap>(args.This());  // similar to ASSIGN_OR_RETURN_UNWRAP
    immediate->env()->SetImmediate([](Environment* env, void* data) {
      static_cast<ImmediateWrap*>(data)->RunCallback();
    }, static_cast<void*>(immediate));
    ClearWeak();
  }
  void RunCallback() {
    MakeWeak();
    Local<Value> args[1] = { env()->GetNow() };
    MakeCallback(env()->ondone_string(), arraysize(args), args);  // terrible function name :(
  }
};

```

---

# Thank you!

Slides @ https://addaleax.net/node-cpp-vancouver