Skip to content

Add JS_GetContinuationData and JS_SetContinuationData - #1920

Open
tom96da wants to merge 1 commit into
quickjs-ng:masterfrom
tom96da:continuation-data
Open

tom96da wants to merge 1 commit into
quickjs-ng:masterfrom
tom96da:continuation-data

Conversation

@tom96da

@tom96da tom96da commented Nov 13, 2026

Copy link
Copy Markdown

Adds JS_GetContinuationData and JS_SetContinuationData, which let an embedder attach a value to the running code and have it follow the code through jobs, promise reactions and await, like V8's ContinuationPreservedEmbedderData. The value is only reachable from C, so an embedder that wants AsyncLocalStorage exposes a getter and a setter to JS and keeps a frame object in the value (the tests do this with getCD and setCD). The motivation is in #1919.

Behaviour

The engine keeps one value per runtime and carries it from where work is queued to where it runs.

  • A job runs with the value that was current when JS_EnqueueJob queued it.
  • A promise reaction (then, catch, finally, await, async generators) runs with the value that was current when it was registered, not when the promise settles.
  • A thenable job gets the value of the code that called resolve.
  • The previous value is restored when the job ends.
  • FinalizationRegistry callbacks run with undefined.
  • Callbacks that come from the embedder (timers, I/O, the module body that a deferred JS_LoadModule evaluates) are not tracked. quickjs.h says so.

JS_GetContinuationData returns a new reference. JS_SetContinuationData does not take ownership of val. The slot is per runtime and has the same threading rules as the rest of the runtime API. No public struct changes.

Implementation

  • Each job entry and promise reaction stores the value (enqueue_job and perform_promise_then copy it in).
  • JS_ExecutePendingJob sets the value of the job while it runs. It restores the previous value before it releases the job's value, because releasing it can run a finalizer that queues a job.
  • js_promise_mark marks the value of a reaction, so a cycle through a promise is collected. JS_FreeRuntime releases the slot.

Tests

api-test.c has five new tests:

Test What it checks
continuation_data then, await, queueMicrotask, a reaction registered before the promise settles from another value, an awaited thenable, and the host-side API
continuation_data_registry a FinalizationRegistry callback runs without a value, also when the object dies while another value is current
continuation_data_cycle a value that refers to its pending promise is collected
continuation_data_finalizer a finalizer queues a job while the value of the finished job is released (a heap-use-after-free under ASan if the previous value is not restored first)
continuation_data_free_runtime a finalizer that reads the value while JS_FreeRuntime releases it sees undefined

tests.conf gives 0/123 errors, test262-check gives the known 64, and api-test and tests.conf are clean under ASan/LSan. Each of these changes makes a test fail, checked under ASan: the job ignoring its value, the reaction job taking the value of the code that settles the promise, the mark removed, the order in JS_ExecutePendingJob reversed, and the registry job queued with the current value.

Cost

One JSValue more per job entry and per reaction, with a few js_dup and JS_FreeValue calls and stores. On 1M await plus 1M then(), pinned to one CPU, over 40 alternating pairs, the median was 1001 ms for stock and 993 ms for patched. The difference is within the noise. A run with a value set was not measured.

This change adds no AsyncContext and no JavaScript-visible API.

Fixes: #1919

Let an embedder carry a value through the asynchronous flow of the code,
like V8's ContinuationPreservedEmbedderData. A job runs with the value that
was current when it was queued, and a promise reaction (then, await,
async generators) runs with the value that was current when it was
registered. The previous value is restored when the job ends.

An embedder can build AsyncLocalStorage on it. Callbacks that come from the
embedder (timers, I/O) are not tracked. FinalizationRegistry callbacks run
without a value.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Let embedders carry a context value through promise jobs (AsyncLocalStorage)

1 participant