Обработка ошибок

Если какой-либо обратный вызов AsyncHook выбрасывает исключение, приложение выведет трассировку стека и завершится. Завершение выполняется так же, как при необработанном исключении, но все обработчики 'uncaughtException' удаляются, что приводит к завершению процесса. Обратные вызовы 'exit' всё равно будут вызваны, если только приложение не запущено с --abort-on-uncaught-exception; в этом случае будет выведена трассировка стека, приложение завершится, а файл core останется.

Причина такого поведения при обработке ошибок заключается в том, что эти обратные вызовы выполняются в потенциально нестабильные моменты жизненного цикла объекта, например во время создания и уничтожения класса. Поэтому считается необходимым быстро завершить процесс, чтобы предотвратить непреднамеренный сбой в будущем. Это поведение может измениться, если в будущем будет проведён всесторонний анализ, подтверждающий, что исключение может следовать обычному потоку управления без непреднамеренных побочных эффектов.

Вывод данных в обратных вызовах AsyncHook

Поскольку вывод в консоль является асинхронной операцией, console.log() приводит к вызову обратных вызовов AsyncHook. Использование console.log() или подобных асинхронных операций внутри функции обратного вызова AsyncHook приводит к бесконечной рекурсии. Для отладки можно использовать простую синхронную операцию журналирования, например fs.writeFileSync(file, msg, flag). Она выводит данные в файл и не вызывает AsyncHook рекурсивно, поскольку является синхронной.

import { writeFileSync } from 'node:fs';
import { format } from 'node:util';

function debug(...args) {
  // Use a function like this one when debugging inside an AsyncHook callback
  writeFileSync('log.out', `${format(...args)}\n`, { flag: 'a' });
}

const fs = require('node:fs');
const util = require('node:util');

function debug(...args) {
  // Use a function like this one when debugging inside an AsyncHook callback
  fs.writeFileSync('log.out', `${util.format(...args)}\n`, { flag: 'a' });
}

Если для журналирования нужна асинхронная операция, можно отслеживать причину её вызова, используя сведения, предоставляемые самим AsyncHook. В этом случае журналирование следует пропускать, если именно оно вызвало обратный вызов AsyncHook. Это позволяет прервать бесконечную рекурсию.

asyncHook.enable()

• Возвращает: <AsyncHook> Ссылка на asyncHook.

Включает обратные вызовы для заданного экземпляра AsyncHook. Если обратные вызовы не заданы, включение ничего не делает.

По умолчанию экземпляр AsyncHook отключён. Если экземпляр AsyncHook нужно включить сразу после создания, можно использовать следующий шаблон.

import { createHook } from 'node:async_hooks';

const hook = createHook(callbacks).enable();

const async_hooks = require('node:async_hooks');

const hook = async_hooks.createHook(callbacks).enable();

asyncHook.disable()

• Возвращает: <AsyncHook> Ссылка на asyncHook.

Отключает обратные вызовы для заданного экземпляра AsyncHook в глобальном пуле обратных вызовов AsyncHook, предназначенных для выполнения. После отключения хук не будет вызываться до тех пор, пока его снова не включат.

Для согласованности API disable() также возвращает экземпляр AsyncHook.

Обратные вызовы хуков

Ключевые события жизненного цикла асинхронных событий разделены на четыре категории: создание экземпляра, выполнение обратного вызова и события до и после него, а также уничтожение экземпляра.

import { createServer } from 'node:net';

createServer().listen(function() { this.close(); });
// OR
clearTimeout(setTimeout(() => {}, 10));

require('node:net').createServer().listen(function() { this.close(); });
// OR
clearTimeout(setTimeout(() => {}, 10));

import { createHook, executionAsyncId } from 'node:async_hooks';
import { stdout } from 'node:process';
import net from 'node:net';
import fs from 'node:fs';

createHook({
  init(asyncId, type, triggerAsyncId) {
    const eid = executionAsyncId();
    fs.writeSync(
      stdout.fd,
      `${type}(${asyncId}): trigger: ${triggerAsyncId} execution: ${eid}\n`);
  },
}).enable();

net.createServer((conn) => {}).listen(8080);

const { createHook, executionAsyncId } = require('node:async_hooks');
const { stdout } = require('node:process');
const net = require('node:net');
const fs = require('node:fs');

createHook({
  init(asyncId, type, triggerAsyncId) {
    const eid = executionAsyncId();
    fs.writeSync(
      stdout.fd,
      `${type}(${asyncId}): trigger: ${triggerAsyncId} execution: ${eid}\n`);
  },
}).enable();

net.createServer((conn) => {}).listen(8080);

TCPSERVERWRAP(5): trigger: 1 execution: 1
TCPWRAP(7): trigger: 5 execution: 0 copy

import async_hooks from 'node:async_hooks';
import fs from 'node:fs';
import net from 'node:net';
import { stdout } from 'node:process';
const { fd } = stdout;

let indent = 0;
async_hooks.createHook({
  init(asyncId, type, triggerAsyncId) {
    const eid = async_hooks.executionAsyncId();
    const indentStr = ' '.repeat(indent);
    fs.writeSync(
      fd,
      `${indentStr}${type}(${asyncId}):` +
      ` trigger: ${triggerAsyncId} execution: ${eid}\n`);
  },
  before(asyncId) {
    const indentStr = ' '.repeat(indent);
    fs.writeSync(fd, `${indentStr}before:  ${asyncId}\n`);
    indent += 2;
  },
  after(asyncId) {
    indent -= 2;
    const indentStr = ' '.repeat(indent);
    fs.writeSync(fd, `${indentStr}after:  ${asyncId}\n`);
  },
  destroy(asyncId) {
    const indentStr = ' '.repeat(indent);
    fs.writeSync(fd, `${indentStr}destroy:  ${asyncId}\n`);
  },
}).enable();

net.createServer(() => {}).listen(8080, () => {
  // Let's wait 10ms before logging the server started.
  setTimeout(() => {
    console.log('>>>', async_hooks.executionAsyncId());
  }, 10);
});

const async_hooks = require('node:async_hooks');
const fs = require('node:fs');
const net = require('node:net');
const { fd } = process.stdout;

let indent = 0;
async_hooks.createHook({
  init(asyncId, type, triggerAsyncId) {
    const eid = async_hooks.executionAsyncId();
    const indentStr = ' '.repeat(indent);
    fs.writeSync(
      fd,
      `${indentStr}${type}(${asyncId}):` +
      ` trigger: ${triggerAsyncId} execution: ${eid}\n`);
  },
  before(asyncId) {
    const indentStr = ' '.repeat(indent);
    fs.writeSync(fd, `${indentStr}before:  ${asyncId}\n`);
    indent += 2;
  },
  after(asyncId) {
    indent -= 2;
    const indentStr = ' '.repeat(indent);
    fs.writeSync(fd, `${indentStr}after:  ${asyncId}\n`);
  },
  destroy(asyncId) {
    const indentStr = ' '.repeat(indent);
    fs.writeSync(fd, `${indentStr}destroy:  ${asyncId}\n`);
  },
}).enable();

net.createServer(() => {}).listen(8080, () => {
  // Let's wait 10ms before logging the server started.
  setTimeout(() => {
    console.log('>>>', async_hooks.executionAsyncId());
  }, 10);
});

TCPSERVERWRAP(5): trigger: 1 execution: 1
TickObject(6): trigger: 5 execution: 1
before:  6
  Timeout(7): trigger: 6 execution: 6
after:   6
destroy: 6
before:  7
>>> 7
  TickObject(8): trigger: 7 execution: 7
after:   7
before:  8
after:   8 copy

  root(1)
     ^
     |
TickObject(6)
     ^
     |
 Timeout(7) copy

 bootstrap(1)
     |
     ˅
TCPSERVERWRAP(5)
     |
     ˅
 TickObject(6)
     |
     ˅
  Timeout(7) copy

new Promise((resolve) => resolve(true)).then((a) => {}); copy

init for PROMISE with id 5, trigger id: 1
  promise resolve 5      # corresponds to resolve(true)
init for PROMISE with id 6, trigger id: 5  # the Promise returned by then()
  before 6               # the then() callback is entered
  promise resolve 6      # the then() callback resolves the promise by returning
  after 6 copy

async_hooks.executionAsyncResource()

• Возвращает: <Object> Ресурс, представляющий текущее выполнение. Удобен для хранения данных в ресурсе.

Объекты ресурсов, возвращаемые executionAsyncResource(), чаще всего являются внутренними объектами-обработчиками Node.js с недокументированными API. Использование любых функций или свойств этого объекта может привести к сбою приложения и не рекомендуется.

В контексте выполнения верхнего уровня вызов executionAsyncResource() возвращает пустой объект, поскольку нет объекта-обработчика или объекта запроса. Однако объект, представляющий верхний уровень, может быть полезен.

import { open } from 'node:fs';
import { executionAsyncId, executionAsyncResource } from 'node:async_hooks';

console.log(executionAsyncId(), executionAsyncResource());  // 1 {}
open(new URL(import.meta.url), 'r', (err, fd) => {
  console.log(executionAsyncId(), executionAsyncResource());  // 7 FSReqWrap
});

const { open } = require('node:fs');
const { executionAsyncId, executionAsyncResource } = require('node:async_hooks');

console.log(executionAsyncId(), executionAsyncResource());  // 1 {}
open(__filename, 'r', (err, fd) => {
  console.log(executionAsyncId(), executionAsyncResource());  // 7 FSReqWrap
});

Это можно использовать для реализации локального хранилища продолжения без применения отслеживающего Map для хранения метаданных:

import { createServer } from 'node:http';
import {
  executionAsyncId,
  executionAsyncResource,
  createHook,
} from 'node:async_hooks';
const sym = Symbol('state'); // Private symbol to avoid pollution

createHook({
  init(asyncId, type, triggerAsyncId, resource) {
    const cr = executionAsyncResource();
    if (cr) {
      resource[sym] = cr[sym];
    }
  },
}).enable();

const server = createServer((req, res) => {
  executionAsyncResource()[sym] = { state: req.url };
  setTimeout(function() {
    res.end(JSON.stringify(executionAsyncResource()[sym]));
  }, 100);
}).listen(3000);

const { createServer } = require('node:http');
const {
  executionAsyncId,
  executionAsyncResource,
  createHook,
} = require('node:async_hooks');
const sym = Symbol('state'); // Private symbol to avoid pollution

createHook({
  init(asyncId, type, triggerAsyncId, resource) {
    const cr = executionAsyncResource();
    if (cr) {
      resource[sym] = cr[sym];
    }
  },
}).enable();

const server = createServer((req, res) => {
  executionAsyncResource()[sym] = { state: req.url };
  setTimeout(function() {
    res.end(JSON.stringify(executionAsyncResource()[sym]));
  }, 100);
}).listen(3000);

async_hooks.executionAsyncId()

• Возвращает: <number> asyncId текущего контекста выполнения. Полезен для отслеживания момента вызова.

import { executionAsyncId } from 'node:async_hooks';
import fs from 'node:fs';

console.log(executionAsyncId());  // 1 - bootstrap
const path = '.';
fs.open(path, 'r', (err, fd) => {
  console.log(executionAsyncId());  // 6 - open()
});

const async_hooks = require('node:async_hooks');
const fs = require('node:fs');

console.log(async_hooks.executionAsyncId());  // 1 - bootstrap
const path = '.';
fs.open(path, 'r', (err, fd) => {
  console.log(async_hooks.executionAsyncId());  // 6 - open()
});

Идентификатор, возвращаемый executionAsyncId(), связан со временем выполнения, а не с причинно-следственной связью (её охватывает triggerAsyncId()):

const server = net.createServer((conn) => {
  // Returns the ID of the server, not of the new connection, because the
  // callback runs in the execution scope of the server's MakeCallback().
  async_hooks.executionAsyncId();

}).listen(port, () => {
  // Returns the ID of a TickObject (process.nextTick()) because all
  // callbacks passed to .listen() are wrapped in a nextTick().
  async_hooks.executionAsyncId();
}); copy

По умолчанию контексты промисов могут не получать точные значения executionAsyncIds. См. раздел Отслеживание выполнения промисов.

async_hooks.triggerAsyncId()

• Возвращает: <number> Идентификатор ресурса, ответственного за вызов выполняемого в данный момент обратного вызова.

const server = net.createServer((conn) => {
  // The resource that caused (or triggered) this callback to be called
  // was that of the new connection. Thus the return value of triggerAsyncId()
  // is the asyncId of "conn".
  async_hooks.triggerAsyncId();

}).listen(port, () => {
  // Even though all callbacks passed to .listen() are wrapped in a nextTick()
  // the callback itself exists because the call to the server's .listen()
  // was made. So the return value would be the ID of the server.
  async_hooks.triggerAsyncId();
}); copy

По умолчанию контексты промисов могут не получать корректные значения triggerAsyncId. См. раздел Отслеживание выполнения промисов.

async_hooks.asyncWrapProviders

• Возвращает: сопоставление типов поставщиков с соответствующими числовыми идентификаторами. Это сопоставление содержит все типы событий, которые могут быть сгенерированы событием async_hooks.init().

Эта возможность позволяет отказаться от устаревшего использования process.binding('async_wrap').Providers. См.: DEP0111

Класс: AsyncResource

Документация по этому классу перенесена AsyncResource.