Add multithreaded version of Jolt to the package

[jrouwe]

See #110

We can build Jolt in multithreaded mode now, we should create an example (a plain one and one implementing callbacks) and make the build available in the package.

[PhoenixIllusion]

Regarding an example with callbacks, that is now very challenging again. The latest Emscripten now no longer puts code in the .worker.js file, so all multi-threading code is self-contained in the NPM compiled JS module and out-of-the-box we are without a 'hook' into the threads again.

This is back in the situation where multi-threading is essentially non-functional for all but trivial cases.

The minimal requirements I can think of before it is viable for anything using a JS callback:

1. Required - A way a worker thread can run a configurable script import PostJoltInit, PreThreadStart
2. Ideally - a way for the main thread to pass data to all workers PostJoltInit, PreThreadStart

It may be possible to hijack the PThread singleton in the module and use the --post-js feature to swizzle/grab the thread-spawning and thread-initializing routines and add one extra step that can support a promise or script imports.

An alternative would be subclassing the ThreadPool and somehow accessing the thread-workers and giving them EM_ASM hooks to call a JS world 'on-thread-create' callback, which then calls 'thread.start' after it has setup, but that is even more non-trivial.

new NPM package jolt-physics/multi-threaded

I tried to approach this as either building them "All At Once (4 to 5x variants)", or build it in two phases.
This may be due to my limited knowledge of best CMake practices and techniques, but one challenge of trying to build 'all at once' is that both the core Jolt C++ static library and Glue code will need to be compiled without shared memory flags for [ wasm, wasm-opt, JS ] and compiled with flags for [ multi-threaded ].

The easiest setup I can think of is make a NPM-packaging SH build-script that compiles just the multi-threading/shared-mem/atomics versions, reconfigure CMake, then build the default [wasm, wasm-opt, JS] variants.

set -e # putting this at the very top, this avoids the need for so many on-fail, exit 1 checks

cmake -B Build/$BUILD_TYPE -DENABLE_MULTI_THREADING=ON -DCMAKE_BUILD_TYPE=$BUILD_TYPE "${@}"
cmake --build Build/$BUILD_TYPE -j`nproc` --target jolt-wasm-compat jolt-wasm

for file in ./dist/jolt-physics.*; do
	mv "${file}" "${file/physics/physics.multithread}"
done

cmake -B Build/$BUILD_TYPE -DENABLE_MULTI_THREADING=OFF -DCMAKE_BUILD_TYPE=$BUILD_TYPE "${@}"
cmake --build Build/$BUILD_TYPE -j`nproc`

[PhoenixIllusion]

I really wish there was an official method to do this, since anything unofficial is risky and could break at some point in the future, which is one of my main concerns about multithreading in an official package.

With current emscripten, this is an example --post-js swizzle to pass a custom JS module URL and extra args supporting shared arrays buffers.
It tacks on a script URL and extra params if available during worker-thread spawning, and on individual workers it strips them off on and conditionally executes a passed in JS module.

// START: MULTI THREADED
if(ENVIRONMENT_IS_PTHREAD) {
  const _invokeEntryPoint = invokeEntryPoint;
  invokeEntryPoint = (ptr, arg) => {
    if(arg.script) {
      import(arg.script).then(module => {
        module.default(Module, arg.params).then(() => _invokeEntryPoint(ptr, arg.value));
      })
    } else {
      _invokeEntryPoint(ptr, arg.value);
    }
  }
} else {
  const _spawnThread  = spawnThread;
  spawnThread = (threadParams) => {
    threadParams.arg = { value: threadParams.arg, script: Module['workerScript'], params: Module['workerScriptParams']};
    _spawnThread(threadParams);
  }
}
// END: MULTI THREADED

usage:

const contactListener = new Jolt.ContactListenerJS();
Jolt['workerScript'] =  './on-worker-conveyor-belt.js';
const workerParams = Jolt['workerScriptParams'] = {
	contactListenerPtr: Jolt.getPointer(contactListener),
	angularBelt: new Uint32Array(new SharedArrayBuffer(4)),
	linearBelts: new Uint32Array(new SharedArrayBuffer(20))
}
// workerParams are sent to all workers at this point, and then never again until Thread restarted
// so no more modifying the workerParam entries outside of internal SharedArrayBuffer values
initExample(Jolt, null); 
// conveyor demo
workerParams.angularBelt[0] = angularBelt.GetID().GetIndexAndSequenceNumber();
workerParams.linearBelts.set(linearBelts.map(belt => belt.GetID().GetIndexAndSequenceNumber()));
// ensure all SharedArrayBuffer are set prior to the next execution of a PhysicsEngine Step

Sample module:

const onWorker =  async (Jolt, args) => {
   // values passed during JoltInterface initialization, when the ThreadPool is started
  const { contactListenerPtr, linearBelts, angularBelt } = args;
  
  // linearBelts and angularBelt are ui32 arrays of a fixed size, but who's values may be changed on any thread
  const contactListener = Jolt.wrapPointer(contactListenerPtr, Jolt.ContactListenerJS);
  contactListener.OnContactAdded = (body1, body2, manifold, settings) => { ... }
}
export default onWorker;

[jrouwe]

Hello, I'm currently on holiday so can't try anything out until I'm back.

Wrt cmake: you usually build different settings to different locations so something like:

cmake -B Build/$BUILD_TYPE$MT

Where $MT indicates if it a multi threading build or not.

[PhoenixIllusion]

Wrt cmake: you usually build different settings to different locations so something like:
cmake -B Build/$BUILD_TYPE$MT
Where $MT indicates if it a multi threading build or not.

This does trigger two downloads since it is making two build folders, and I don't think by default CMake will support caching the git repo anywhere, but there is probably not much overhead in cloning down the original library twice.

This is a PoC of the above workerScript + workerParam idea: PhoenixIllusion@ce18a68

[jrouwe]

This does trigger two downloads since it is making two build folders, and I don't think by default CMake will support caching the git repo anywhere, but there is probably not much overhead in cloning down the original library twice.

Yes, that should not be a problem, if you switch between debug/release using build.sh it also downloads the repo 2x.

[jrouwe]

I've finally looked at the change, to me the solution looks quite reasonable. The main issue is that you're building 2x to Build/$BUILD_TYPE and cmake afaik doesn't pick up changes to -DENABLE_MULTI_THREADING= in that case. So we'd need to build to 2 different folders (this also helps incremental builds). If you're also happy with this solution then send me a PR and I'll make that fix and merge it.

[jrouwe]

@PhoenixIllusion I've edited your solution a bit and merged it into main.

The main issue I'm now running into is that github.io doesn't turn on COOP/COEP so the multithreaded demo won't run there (they do run fine with npm run examples). I've tried fixing this by including https://github.com/gzuidhof/coi-serviceworker, but for some reason that does not want to work. Do you know if this can work at all?

I also tried to configure the npm package so that it includes the multi threaded version. Can you check if it makes sense this way? I'm not sure if I'm breaking common naming conventions by using wasm-compat-multithread and wasm-multithread.

[PhoenixIllusion]

https://github.com/gzuidhof/coi-serviceworker will register the base-URL of the script itself as the watched and controlled COOP/COEP domain. You are currently hosting it out of the /js folder, so it will only override that domain. It would need to be hosted off the HTML directory at least. A JS Service Worker can only control resourced loaded starting at it's hosted path and lower.

ex:

https://jrouwe.github.io/s-worker.js -- can control all files under your domain
https://jrouwe.github.io/JoltPhysics.js/s-worker.js -- can control all HTML and children like the js folder
https://jrouwe.github.io/JoltPhysics.js/js/s-worker.js -- can only control the JS folders and lower

A secondary issue is the actual isolation. This prevents using my example's externally hosted CDN three.module.js since cloudflare JS CDN does not have the headers. I found that JSDeliver does provide the CORP header, so that is one solution to the issue.

I make a fork branch that will confirm these cases. #211

[jrouwe]

Thanks a lot, it works! I would have never figured that one out.

B.t.w. is it needed to import THREE from https://cdn.jsdelivr.net/npm/three@0.161.0/build/three.module.min.js, can't it use the version in ./js/three/three.min.js? I've tried, but it seems to overwrite THREE so it no longer contains THREE.OrbitControls: TypeError: THREE.OrbitControls is not a constructor.

[PhoenixIllusion]

You can make that work, but will need to conditionally use the importScript in the worker script.

It will need to import and execute only in worker threads, not main, to prevent that overwrite.

A secondary issue is that the conveyor belt example is using Blob URL scripts. Blob URLs are not designated as being on the site path hierarchy, so you can't use relative script URLs when importing external resources, like 'js/three/three.min.js'. You would need to runtime resolve the absolute path of the script for use in the Blob script, probably even runtime modifying the text of the JS Blob script to use that new URL. I've done it before, using await import.meta.resolve(...)

This secondary issue and possibly even primary issue are non existent if you use an external JS file instead of the Blob JS file. In that case you can safely import relative URLs.

[jrouwe]

Ok, then perhaps it is better to go the other way around and use the https://cdn.jsdelivr.net/npm/three@0.161.0/build/three.module.min.js version everywhere.

Thanks for your help!

[jrouwe]

I ran into quite a fundamental issue with the multi threaded conveyor belt example:

While converting the example to using Jolt's math function (see https://github.com/jrouwe/JoltPhysics.js/tree/mt_conveyor), I realized that the WebIDL bindings are completely unsafe to use in a threaded environment. It wasn't so noticable before, but when using more math functions it becomes very apparent. The WebIDL bindings generate code constructs like:

RVec3* EMSCRIPTEN_KEEPALIVE emscripten_bind_Body_GetCenterOfMassPosition_0(Body* self) {
  static RVec3 temp;
  return (temp = self->GetCenterOfMassPosition(), &temp);
}

Which means that when OnContactAdded handler does:

const COM1 = body1.GetCenterOfMassPosition();

Any other thread could overwrite temp and thus COM1 at any moment.

I guess there's no way to easily prevent multiple threads from calling a JS callback at the same time?

Otherwise I'm going to have to change webidl_binder.py so that it constructs a new value for every call...

[PhoenixIllusion]

You can use the SharedArrayBuffer to create atomically accessible values and use signal/mutex.

You would need to isolate a code section of the callback routine using an atomic lock/unlock, where anything using those C/C++ static values would be used only inside those blocks.

In the demo, it should only require locking the Read calls since it calculates the math result in JS.

If you are going to use the Jolt math routines, then you would need to atomic lock the Read and any math functions that have the static variable pattern to also be inside the lock.

[jrouwe]

I found a nice solution by adding 'thread_local' to the code generated by webidl_binder.py. This still allows multiple JS threads to call the contact listener at the same time.

See: emscripten-core/emscripten#22772

And this commit: fa0df81

[jrouwe]

I just released 0.28.0 which includes these changes.