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

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

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

Вывод данных в callback-функциях AsyncHook

Поскольку вывод в консоль является асинхронной операцией, console.log() приведет к вызову callback-функций AsyncHook. Использование console.log() или аналогичных асинхронных операций внутри callback-функции 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. В этом случае журналирование следует пропускать, когда именно оно привело к вызову callback-функции AsyncHook. Это позволит разорвать бесконечную рекурсию.

asyncHook.enable()

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

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

По умолчанию экземпляр 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.

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

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

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

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

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> Идентификатор ресурса, ответственного за вызов выполняемой в данный момент callback-функции.

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

Отключение отслеживания выполнения промисов

Отслеживание выполнения промисов может значительно снизить производительность. Чтобы отказаться от отслеживания промисов, установите для trackPromises значение false:

const { createHook } = require('node:async_hooks');
const { writeSync } = require('node:fs');
createHook({
  init(asyncId, type, triggerAsyncId, resource) {
    // This init hook does not get called when trackPromises is set to false.
    writeSync(1, `init hook triggered for ${type}\n`);
  },
  trackPromises: false,  // Do not track promises.
}).enable();
Promise.resolve(1729);

import { createHook } from 'node:async_hooks';
import { writeSync } from 'node:fs';

createHook({
  init(asyncId, type, triggerAsyncId, resource) {
    // This init hook does not get called when trackPromises is set to false.
    writeSync(1, `init hook triggered for ${type}\n`);
  },
  trackPromises: false,  // Do not track promises.
}).enable();
Promise.resolve(1729);

Класс: AsyncResource

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