@@ -5420,6 +5420,42 @@ invocation. If it is deleted before then, then the finalize callback may never |
5420 | 5420 | be invoked. Therefore, when obtaining a reference a finalize callback is also |
5421 | 5421 | required in order to enable correct disposal of the reference. |
5422 | 5422 |
|
| 5423 | +#### `node_api_post_finalizer` |
| 5424 | + |
| 5425 | +<!-- YAML |
| 5426 | +added: REPLACEME |
| 5427 | +--> |
| 5428 | + |
| 5429 | +> Stability: 1 - Experimental |
| 5430 | + |
| 5431 | +```c |
| 5432 | +napi_status node_api_post_finalizer(napi_env env, |
| 5433 | + napi_finalize finalize_cb, |
| 5434 | + void* finalize_data, |
| 5435 | + void* finalize_hint); |
| 5436 | +``` |
| 5437 | + |
| 5438 | +* `[in] env`: The environment that the API is invoked under. |
| 5439 | +* `[in] finalize_cb`: Native callback that will be used to free the |
| 5440 | + native data when the JavaScript object has been garbage-collected. |
| 5441 | + [`napi_finalize`][] provides more details. |
| 5442 | +* `[in] finalize_data`: Optional data to be passed to `finalize_cb`. |
| 5443 | +* `[in] finalize_hint`: Optional contextual hint that is passed to the |
| 5444 | + finalize callback. |
| 5445 | + |
| 5446 | +Returns `napi_ok` if the API succeeded. |
| 5447 | + |
| 5448 | +Schedules a `napi_finalize` callback to be called asynchronously in the |
| 5449 | +event loop. |
| 5450 | + |
| 5451 | +Normally, finalizers are called while the GC (garbage collector) collects |
| 5452 | +objects. At that point calling any Node-API that may cause changes in the GC |
| 5453 | +state will be disabled and will crash Node.js. |
| 5454 | + |
| 5455 | +`node_api_post_finalizer` helps to work around this limitation by allowing the |
| 5456 | +add-on to defer calls to such Node-APIs to a point in time outside of the GC |
| 5457 | +finalization. |
| 5458 | + |
5423 | 5459 | ## Simple asynchronous operations |
5424 | 5460 |
|
5425 | 5461 | Addon modules often need to leverage async helpers from libuv as part of their |
|