Move emscripten_futex declaration into threading_primitives.h. NFC (#26436)

Also, document that the low level wait function don't work everywhere.

This is step towards #26375.

Author: sbc100

system/include/emscripten/atomic.h

@@ -197,6 +197,10 @@ _EM_INLINE void emscripten_atomic_fence(void) {
 // NOTE: This function takes in the wait value in int64_t nanosecond units. Pass
 // in maxWaitNanoseconds = -1 (or ATOMICS_WAIT_DURATION_INFINITE) to wait
 // infinitely long.
+// NOTE: This function is thin wrapper around the Wasm atomic.wait instruction
+// and therefore cannot be used on the main browser thread, or in Audio Worklets.
+// If you need a wait primitive that works everywhere you can use
+// `emscripten_futex_wait`.
 _EM_INLINE ATOMICS_WAIT_RESULT_T emscripten_atomic_wait_u32(void /*uint32_t*/* _Nonnull addr, uint32_t expectedValue, int64_t maxWaitNanoseconds) {
   return __builtin_wasm_memory_atomic_wait32((int32_t*)addr, expectedValue, maxWaitNanoseconds);
 }
@@ -208,6 +212,10 @@ _EM_INLINE ATOMICS_WAIT_RESULT_T emscripten_atomic_wait_u32(void /*uint32_t*/* _
 // NOTE: This function takes in the wait value in int64_t nanosecond units. Pass
 // in maxWaitNanoseconds = -1 (or ATOMICS_WAIT_DURATION_INFINITE) to wait
 // infinitely long.
+// NOTE: This function is thin wrapper around the Wasm atomic.wait instruction
+// and therefore cannot be used on the main browser thread, or in Audio Worklets.
+// If you need a wait primitive that works everywhere you can use
+// `emscripten_futex_wait`.
 _EM_INLINE ATOMICS_WAIT_RESULT_T emscripten_atomic_wait_u64(void /*uint64_t*/* _Nonnull addr, uint64_t expectedValue, int64_t maxWaitNanoseconds) {
   return __builtin_wasm_memory_atomic_wait64((int64_t*)addr, expectedValue, maxWaitNanoseconds);
 }

system/include/emscripten/threading.h

@@ -29,16 +29,6 @@ bool emscripten_has_threading_support(void);
 // Returns the number of logical cores on the system.
 int emscripten_num_logical_cores(void);
 
-// If the given memory address contains value val, puts the calling thread to
-// sleep waiting for that address to be notified.
-// Returns -EINVAL if addr is null.
-int emscripten_futex_wait(volatile void/*uint32_t*/ * _Nonnull addr, uint32_t val, double maxWaitMilliseconds);
-
-// Wakes the given number of threads waiting on a location. Pass count ==
-// INT_MAX to wake all waiters on that location.
-// Returns -EINVAL if addr is null.
-int emscripten_futex_wake(volatile void/*uint32_t*/ * _Nonnull addr, int count);
-
 // Returns true if the current thread is the thread that hosts the Emscripten
 // runtime.
 // Returns false on pthreads and Wasm Workers.

system/include/emscripten/threading_primitives.h

@@ -13,10 +13,6 @@
 extern "C" {
 #endif
 
-// Similar to emscripten_async_wait_callback_t but with a volatile first
-// argument.
-typedef void (*emscripten_async_wait_volatile_callback_t)(volatile void* address, uint32_t value, ATOMICS_WAIT_RESULT_T waitResult, void* userData);
-
 #define emscripten_lock_t volatile uint32_t
 
 // Use with syntax "emscripten_lock_t l = EMSCRIPTEN_LOCK_T_STATIC_INITIALIZER;"
@@ -34,7 +30,6 @@ void emscripten_lock_init(emscripten_lock_t * _Nonnull lock);
 // NOTE: This function can be only called in a Worker, and not on the main
 //       browser thread, because the main browser thread cannot synchronously
 //       sleep to wait for locks.
-
 bool emscripten_lock_wait_acquire(emscripten_lock_t * _Nonnull lock, int64_t maxWaitNanoseconds);
 
 // Similar to emscripten_lock_wait_acquire(), but instead of waiting for at most
@@ -74,6 +69,10 @@ bool emscripten_lock_busyspin_wait_acquire(emscripten_lock_t * _Nonnull lock, do
 //       acquire without contention from other threads.
 void emscripten_lock_busyspin_waitinf_acquire(emscripten_lock_t * _Nonnull lock);
 
+// Similar to emscripten_async_wait_callback_t but with a volatile first
+// argument.
+typedef void (*emscripten_async_wait_volatile_callback_t)(volatile void* address, uint32_t value, ATOMICS_WAIT_RESULT_T waitResult, void* userData);
+
 // Registers an *asynchronous* lock acquire operation. The calling thread will
 // asynchronously try to obtain the given lock after the calling thread yields
 // back to the event loop. If the attempt is successful within
@@ -187,6 +186,16 @@ ATOMICS_WAIT_TOKEN_T emscripten_condvar_wait_async(emscripten_condvar_t * _Nonnu
 // ("broadcast" operation).
 void emscripten_condvar_signal(emscripten_condvar_t * _Nonnull condvar, int64_t numWaitersToSignal);
 
+// If the given memory address contains value val, puts the calling thread to
+// sleep waiting for that address to be notified.
+// Returns -EINVAL if addr is null.
+int emscripten_futex_wait(volatile void/*uint32_t*/ * _Nonnull addr, uint32_t val, double maxWaitMilliseconds);
+
+// Wakes the given number of threads waiting on a location. Pass count ==
+// INT_MAX to wake all waiters on that location.
+// Returns -EINVAL if addr is null.
+int emscripten_futex_wake(volatile void/*uint32_t*/ * _Nonnull addr, int count);
+
 #ifdef __cplusplus
 }
 #endif