144 lines
4.8 KiB
Haxe
144 lines
4.8 KiB
Haxe
package node;
|
|
|
|
@:jsRequire("node:async_hooks") @valueModuleOnly extern class NodeAsync_hooks {
|
|
/**
|
|
```js
|
|
import { executionAsyncId } from 'node:async_hooks';
|
|
import fs from 'node:fs';
|
|
|
|
console.log(executionAsyncId()); // 1 - bootstrap
|
|
fs.open(path, 'r', (err, fd) => {
|
|
console.log(executionAsyncId()); // 6 - open()
|
|
});
|
|
```
|
|
|
|
The ID returned from `executionAsyncId()` is related to execution timing, not
|
|
causality (which is covered by `triggerAsyncId()`):
|
|
|
|
```js
|
|
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();
|
|
});
|
|
```
|
|
|
|
Promise contexts may not get precise `executionAsyncIds` by default.
|
|
See the section on `promise execution tracking`.
|
|
**/
|
|
static function executionAsyncId():Float;
|
|
/**
|
|
Resource objects returned by `executionAsyncResource()` are most often internal
|
|
Node.js handle objects with undocumented APIs. Using any functions or properties
|
|
on the object is likely to crash your application and should be avoided.
|
|
|
|
Using `executionAsyncResource()` in the top-level execution context will
|
|
return an empty object as there is no handle or request object to use,
|
|
but having an object representing the top-level can be helpful.
|
|
|
|
```js
|
|
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
|
|
});
|
|
```
|
|
|
|
This can be used to implement continuation local storage without the
|
|
use of a tracking `Map` to store the metadata:
|
|
|
|
```js
|
|
import { createServer } from 'node:http';
|
|
import {
|
|
executionAsyncId,
|
|
executionAsyncResource,
|
|
createHook,
|
|
} from '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);
|
|
```
|
|
**/
|
|
static function executionAsyncResource():Dynamic;
|
|
/**
|
|
```js
|
|
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();
|
|
});
|
|
```
|
|
|
|
Promise contexts may not get valid `triggerAsyncId`s by default. See
|
|
the section on `promise execution tracking`.
|
|
**/
|
|
static function triggerAsyncId():Float;
|
|
/**
|
|
Registers functions to be called for different lifetime events of each async
|
|
operation.
|
|
|
|
The callbacks `init()`/`before()`/`after()`/`destroy()` are called for the
|
|
respective asynchronous event during a resource's lifetime.
|
|
|
|
All callbacks are optional. For example, if only resource cleanup needs to
|
|
be tracked, then only the `destroy` callback needs to be passed. The
|
|
specifics of all functions that can be passed to `callbacks` is in the `Hook Callbacks` section.
|
|
|
|
```js
|
|
import { createHook } from 'node:async_hooks';
|
|
|
|
const asyncHook = createHook({
|
|
init(asyncId, type, triggerAsyncId, resource) { },
|
|
destroy(asyncId) { },
|
|
});
|
|
```
|
|
|
|
The callbacks will be inherited via the prototype chain:
|
|
|
|
```js
|
|
class MyAsyncCallbacks {
|
|
init(asyncId, type, triggerAsyncId, resource) { }
|
|
destroy(asyncId) {}
|
|
}
|
|
|
|
class MyAddedCallbacks extends MyAsyncCallbacks {
|
|
before(asyncId) { }
|
|
after(asyncId) { }
|
|
}
|
|
|
|
const asyncHook = async_hooks.createHook(new MyAddedCallbacks());
|
|
```
|
|
|
|
Because promises are asynchronous resources whose lifecycle is tracked
|
|
via the async hooks mechanism, the `init()`, `before()`, `after()`, and`destroy()` callbacks _must not_ be async functions that return promises.
|
|
**/
|
|
static function createHook(callbacks:node.async_hooks.HookCallbacks):node.async_hooks.AsyncHook;
|
|
} |