Skip to content

Fix wasm-bindgen-test compatibility with doctests in Node.js #4535

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

drewcrawford
Copy link

This commit addresses crashes when running wasm-bindgen-test in doctests, which execute in Node.js environments with specific limitations.

Problem:
When running doctests with wasm-bindgen-test, async code using spawn_local() would crash with "not a shared typed array" error. This occurred because:

  1. Doctests run in Node.js, not browsers
  2. Node.js may not have SharedArrayBuffer enabled by default
  3. Even with atomics compiled in, the runtime memory might not be shared

Solution:

  1. SharedArrayBuffer detection: Before using Atomics.waitAsync(), we now check if the memory buffer is actually a SharedArrayBuffer. If not, we gracefully fall back to the polyfill implementation.

  2. Worker availability handling: In Node.js doctests, Worker may not be available or may behave differently. The polyfill now:

    • Checks for Worker constructor availability before attempting to use it
    • Falls back to setTimeout-based polling when Worker is unavailable
    • Implements exponential backoff (1ms → 2ms → 4ms... up to 100ms)
    • Polls up to 10 times before timing out

Design decisions:

  • The SharedArrayBuffer check uses inline JS to properly detect the type, as this can't be reliably done from Rust alone
  • The polling fallback provides basic async behavior without Worker deps, making doctests functional even in restricted environments
  • The implementation prioritizes compatibility over performance in fallback scenarios, as doctests are primarily for documentation/testing

This enables wasm-bindgen-test to work reliably in doctest environments while maintaining full functionality in production browser contexts.

This commit addresses crashes when running wasm-bindgen-test in doctests,
which execute in Node.js environments with specific limitations.

Problem:
When running doctests with wasm-bindgen-test, async code using spawn_local()
would crash with "not a shared typed array" error. This occurred because:
1. Doctests run in Node.js, not browsers
2. Node.js may not have SharedArrayBuffer enabled by default
3. Even with atomics compiled in, the runtime memory might not be shared

Solution:
1. SharedArrayBuffer detection: Before using Atomics.waitAsync(), we now
   check if the memory buffer is actually a SharedArrayBuffer. If not,
   we gracefully fall back to the polyfill implementation.

2. Worker availability handling: In Node.js doctests, Worker may not be
   available or may behave differently. The polyfill now:
   - Checks for Worker constructor availability before attempting to use it
   - Falls back to setTimeout-based polling when Worker is unavailable
   - Implements exponential backoff (1ms → 2ms → 4ms... up to 100ms)
   - Polls up to 10 times before timing out

Design decisions:
- The SharedArrayBuffer check uses inline JS to properly detect the type,
  as this can't be reliably done from Rust alone
- The polling fallback provides basic async behavior without Worker deps,
  making doctests functional even in restricted environments
- The implementation prioritizes compatibility over performance in fallback
  scenarios, as doctests are primarily for documentation/testing

This enables wasm-bindgen-test to work reliably in doctest environments
while maintaining full functionality in production browser contexts.
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.

1 participant