105 lines
2.6 KiB
Markdown
105 lines
2.6 KiB
Markdown
# Script -- Async Promises (`scriptpromisepend_t`)
|
|
|
|
Source: `src/dusk/script/scriptpromisepend.h`
|
|
|
|
See also: `.claude/script.md`
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
When a C module needs to resolve a JS `Promise` from an asynchronous
|
|
C event (e.g. an asset finishing loading, a network response arriving),
|
|
use `scriptpromisepend_t`. The pattern avoids heap allocation by using
|
|
a fixed-size pending slot array declared in the module.
|
|
|
|
---
|
|
|
|
## Declaring the pending array
|
|
|
|
```c
|
|
#define MY_MODULE_PENDING_MAX 8
|
|
static scriptpromisepend_t MY_PENDING[MY_MODULE_PENDING_MAX];
|
|
static uint32_t MY_PENDING_COUNT = 0;
|
|
```
|
|
|
|
---
|
|
|
|
## Add a pending promise
|
|
|
|
Called from the JS-facing function that returns the Promise:
|
|
|
|
```c
|
|
jerry_value_t promise = jerry_create_promise();
|
|
scriptPromisePendAdd(
|
|
MY_PENDING, &MY_PENDING_COUNT, MY_MODULE_PENDING_MAX,
|
|
key, // opaque void * used to match the resolve/reject later
|
|
promise
|
|
);
|
|
return jerry_acquire_value(promise); // return a copy to the caller
|
|
```
|
|
|
|
The `key` should be a stable pointer that uniquely identifies the
|
|
async operation -- e.g. an `assetentry_t *`, a network request handle,
|
|
or a pointer to a fixed-size slot in the module.
|
|
|
|
---
|
|
|
|
## Resolve or reject
|
|
|
|
Called when the C event fires, typically from `moduleUpdate` or an
|
|
event callback:
|
|
|
|
```c
|
|
// On success:
|
|
scriptPromisePendResolve(
|
|
MY_PENDING, &MY_PENDING_COUNT,
|
|
key, jerry_undefined() // or a result value
|
|
);
|
|
|
|
// On failure:
|
|
jerry_value_t err = jerry_create_error(
|
|
JERRY_ERROR_COMMON, (const jerry_char_t *)"reason"
|
|
);
|
|
scriptPromisePendReject(MY_PENDING, &MY_PENDING_COUNT, key, err);
|
|
jerry_release_value(err);
|
|
```
|
|
|
|
Both macros remove the slot from the pending array after settling.
|
|
|
|
---
|
|
|
|
## Guard against double-submit
|
|
|
|
```c
|
|
if(scriptPromisePendHas(MY_PENDING, MY_PENDING_COUNT, key)) {
|
|
// already waiting -- return the existing promise or an error
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Module teardown
|
|
|
|
Free all pending promises before cleaning up events or other state:
|
|
|
|
```c
|
|
scriptPromisePendFreeAll(MY_PENDING, &MY_PENDING_COUNT);
|
|
```
|
|
|
|
This rejects all still-pending promises and resets the count to 0.
|
|
Call it from the module's `Dispose` function, **before** any backing
|
|
data (asset entries, event subscriptions) is torn down.
|
|
|
|
---
|
|
|
|
## Design notes
|
|
|
|
- `MY_MODULE_PENDING_MAX` sets a hard cap on concurrent async ops.
|
|
Exceeding it is a runtime assertion -- size the array to the maximum
|
|
realistic concurrency for the module.
|
|
- The key is opaque (`void *`); the system does not dereference it.
|
|
A raw integer cast to `void *` is fine if no pointer is available.
|
|
- `scriptUpdate()` runs the JerryScript microjob queue each frame,
|
|
which is what processes `.then()` chains after a resolve/reject.
|