ThreadX (Beta)

**Warning: This is beta software and all of the exposed APIs are subject to
breaking changes**

ThreadX is a web browser-based JavaScript library that helps manage the
communcation of data between one or more web worker threads.

ThreadX handles data communcation in two ways:

One is via the standard
postMessage()
API. This facilitates passing of complex nested object data.

The other is via SharedArrayBuffer between two workers. ThreadX
provides two base classes which can be implemented side-by-side in order to
facilitate fast exchange of object properties: BufferStruct and SharedObject.
The BufferStruct defines the basic structure of data as it will exist in the
SharedArrayBuffer, while the SharedObject provides an API for either worker
to access and set properties in a syncronous manner.

Examples on how BufferStructs and SharedObjects are used are available in our
browser-tests directory and in the Lightning 3 Renderer repo.

Setup

- npm install

Build

- npm run build
- npm run watch (Watch Mode)

This builds the library using the TypeScript compiler and places the output to
a directory named dist.

When run in Watch Mode, the TypeScript compiler will listen for changes to files
and automatically recompile

Docs

- npm run typedoc

This builds the TypeDoc API documentation files which you can browse using your
web browser from the docs folder.

Tests

- npm run test:browser (Browser Integration Tests)
- npm run test (Unit Tests)

There are two categories of tests run by the commands above: Unit Tests and Browser
Integration Tests. When running either category, the test runner will remain open
and re-run when any changes are detected to the code.

$3

Browser Integration Tests focus on the user-end capabilities / features of
ThreadX, such as creating/closing workers, sending messages to workers,
receiving responses from workers, and using SharedObjects / BufferStructs
to share data between workers. These tests use Mocha + Chai and are launched
(by default) in the Chrome browser.

NOTE: The Integration Tests rely on the built assets in the dist folder. For
the best live testing experience, run a build in Watch Mode at the same time
as running the Integration Tests.

$3

Unit Tests focus on whatever we can test that does not rely on browser APIs
such as Workers. Self-contained utility methods are great candidates for unit
tests. These tests are written with Vitest which uses virtually similar
testing constructs as Mocha + Chai.

Security

As a requirement, your app needs to be in a secture context. For top level documents, two headers need to be set to cross-origin isolate yout app.

- Cross-Origin-Embedder-Policy : require-corp ( protects your origin from attackers )
- Cross-Origin-Opener-Policy : same-origin ( protects victims from your origin )

to test if isolation is succesfull you can check the crossOriginIsolated property available in Worker and Window contexts:

``js
if (globalThis.crossOriginIsolated) {
// app logic
}
`

Atomics

Since we share memory and multiple threads can read and write to the same piece of memory, we need the Atomics object to perform atomic operations on the SharedArrayBuffer objects. Atomics` make sure that operations run uninterrupted and are finished before the next will.