Update emscripten_futex_wait to return -EINTR on spurious wakeups. NFC (#26735)

sbc100 · web-flow · commit 47e7d6795e6a · 2026-04-21T22:37:14.000-07:00
The internal musl code assumes that futex wait returns -EINTR if the wait is interrupted. We return -EINTR here in case we wakeup to run a timer or if were notified to wake up by another thread using `emscripten_thread_notify`. Followup to #26659
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -31,6 +31,11 @@ See docs/process.md for more on how version tagging works.
   emscripten so folks can sill use it manually if needed.  If you are a user of
   this feature please let us know otherwise this may be deleted in a future
   release. (#26648)
+- The emscripten_futux_wait internals were improved to avoid unnecessary thread
+  wakeups.  As part of this change emscripten_futux_wait is now documented to
+  explicitly allow for returning EINTR when the wait is interrupted by an async
+  operation.  All callers of emscripten_futux_wait are advised to use a loop
+  to handle these types of spurious wakeups / interruptions. (#26659, #26735)
 
 5.0.6 - 04/14/26
 ----------------
diff --git a/system/include/emscripten/threading_primitives.h b/system/include/emscripten/threading_primitives.h
@@ -187,12 +187,13 @@ ATOMICS_WAIT_TOKEN_T emscripten_condvar_wait_async(emscripten_condvar_t * _Nonnu
 void emscripten_condvar_signal(emscripten_condvar_t * _Nonnull condvar, uint32_t numWaitersToSignal);
 
 // If the given memory address contains value val, puts the calling thread to
-// sleep waiting for that address to be notified.
-// Note: Like the Linux futex syscall, this API *does* allow spurious wakeups.
-// This differs from the WebAssembly `atomic.wait` instruction itself which
-// does *not* allow supurious wakeups and it means that most callers will want
-// to wrap this some kind of loop.
+// sleep waiting for that address to be notified. Like the linux futex syscall
+// this function returns negative errno values on failure.
 // Returns -EINVAL if addr is null.
+// Returns -ETIMEOUT if the maxWaitMilliseconds timeout was exceeded.
+// Returns -EINTR if the operation was interrupted (e.g. a timer fired, or an
+// async signal was received).
+// Returns 0 on success (i.e. another thread signaled this address)
 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 ==
diff --git a/system/lib/libc/emscripten_yield_stub.c b/system/lib/libc/emscripten_yield_stub.c
@@ -7,11 +7,14 @@
 
 #include <features.h>
 
-static void dummy(double now) {
+#include "threading_internal.h"
+
+static bool dummy(double now) {
+  return false;
 }
 
 weak_alias(dummy, _emscripten_check_timers);
 
-void _emscripten_yield(double now) {
-  _emscripten_check_timers(now);
+bool _emscripten_yield(double now) {
+  return _emscripten_check_timers(now);
 }
diff --git a/system/lib/libc/musl/src/signal/setitimer.c b/system/lib/libc/musl/src/signal/setitimer.c
@@ -64,21 +64,25 @@ void _emscripten_timeout(int which, double now)
 	raise(signum);
 }
 
-void _emscripten_check_timers(double now)
+bool _emscripten_check_timers(double now)
 {
 	// Timers always run on the main runtime thread. They are registered with
 	// _setitimer_js which is proxied to the main runtime thread.
 	assert(emscripten_is_main_runtime_thread());
+	bool rtn = false;
 	for (int which = 0; which < 3; which++) {
 		if (current_timeout_ms[which]) {
 			// Only call out to JS to get the current time if it was not passed in
 			// *and* we have one or more timers set.
 			if (!now)
 			 	now = emscripten_get_now();
-			if (now >= current_timeout_ms[which])
+			if (now >= current_timeout_ms[which]) {
+				rtn = true;
 				_emscripten_timeout(which, now);
+			}
 		}
 	}
+	return rtn;
 }
 
 double _emscripten_next_timer()
diff --git a/system/lib/pthread/emscripten_futex_wait.c b/system/lib/pthread/emscripten_futex_wait.c
@@ -21,6 +21,12 @@
 #include <stdlib.h>
 #include <sys/param.h>
 
+#ifdef __EMSCRIPTEN_PTHREADS__
+// Note: We use a weak reference here.  If it's null we know that threads are
+// not cancelable.
+weak long __cancel(void);
+#endif
+
 extern void* _emscripten_main_thread_futex;
 
 static int futex_wait_main_browser_thread(volatile void* addr,
@@ -53,8 +59,7 @@ static int futex_wait_main_browser_thread(volatile void* addr,
   while (1) {
 #ifdef __EMSCRIPTEN_PTHREADS__
     if (cancelable && __pthread_self()->cancel) {
-      __pthread_testcancel();
-      return -ETIMEDOUT;
+      return __cancel();
     }
 #endif
     // Check for a timeout.
@@ -79,7 +84,10 @@ static int futex_wait_main_browser_thread(volatile void* addr,
       // We were told to stop waiting, so stop.
       break;
     }
-    _emscripten_yield(now);
+    bool timer_fired = _emscripten_yield(now);
+    if (timer_fired) {
+      return -EINTR;
+    }
 
     // Check the value, as if we were starting the futex all over again.
     // This handles the following case:
@@ -132,27 +140,24 @@ static double dummy() {
 
 weak_alias(dummy, _emscripten_next_timer);
 
-int emscripten_futex_wait(volatile void *addr, uint32_t val, double max_wait_ms) {
+static int _do_futex_wait(volatile void *addr, uint32_t val, double max_wait_ms) {
   if ((((intptr_t)addr)&3) != 0) {
     return -EINVAL;
   }
 
   int ret;
-  emscripten_conditional_set_current_thread_status(EM_THREAD_STATUS_RUNNING, EM_THREAD_STATUS_WAITFUTEX);
 
 #ifdef __EMSCRIPTEN_PTHREADS__
   pthread_t self = __pthread_self();
-  bool cancelable = self->canceldisable != PTHREAD_CANCEL_DISABLE;
+  bool cancelable = __cancel && self->canceldisable != PTHREAD_CANCEL_DISABLE;
 #else
   bool cancelable = false;
 #endif
 
   // For the main browser thread and audio worklets we can't use
   // __builtin_wasm_memory_atomic_wait32 so we have busy wait instead.
   if (!_emscripten_thread_supports_atomics_wait()) {
-    ret = futex_wait_main_browser_thread(addr, val, max_wait_ms, cancelable);
-    emscripten_conditional_set_current_thread_status(EM_THREAD_STATUS_WAITFUTEX, EM_THREAD_STATUS_RUNNING);
-    return ret;
+    return futex_wait_main_browser_thread(addr, val, max_wait_ms, cancelable);
   }
 
   DBG("emscripten_futex_wait ms=%f", max_wait_ms);
@@ -182,28 +187,31 @@ int emscripten_futex_wait(volatile void *addr, uint32_t val, double max_wait_ms)
   }
 
   // Clear the wait_addr
-  DBG("emscripten_futex_wait done notify=%d cancelable=%d cancel=%d", !!(self->wait_addr & NOTIFY_BIT), cancelable, self->cancel);
-  self->wait_addr = 0;
+  bool notified = atomic_exchange(&self->wait_addr, 0) & NOTIFY_BIT;
+
+  // Here we are mimicking the behaviour of musl's __syscall_cp_c which wraps
+  // the linux futex syscall.
+  if (self->cancel && cancelable) {
+    return __cancel();
+  }
+
+  DBG("emscripten_futex_wait done notified=%d cancelable=%d cancel=%d", notified, cancelable, self->cancel);
 
   // Pass 0 here, which means we don't have access to the current time in this
   // function.  This tells _emscripten_yield to call emscripten_get_now if (and
   // only if) it needs to know the time.
-  _emscripten_yield(0);
-
-  if (cancelable && self->cancel) {
-    __pthread_testcancel();
-    // If __pthread_testcancel does return here it means that canceldisable
-    // must be set to PTHREAD_CANCEL_MASKED.  In this case we emulate the
-    // behaviour of the futex syscall and return ECANCELLED here.
-    // See pthread_cond_timedwait.c for the only use of this flag.
-    emscripten_conditional_set_current_thread_status(EM_THREAD_STATUS_WAITFUTEX, EM_THREAD_STATUS_RUNNING);
-    return -ECANCELED;
+  bool timer_fired = _emscripten_yield(0);
+  if (notified || timer_fired) {
+    return -EINTR;
   }
 #else // __EMSCRIPTEN_PTHREADS__
   ret = __builtin_wasm_memory_atomic_wait32((int*)addr, val, max_wait_ns);
+  bool timer_fired = _emscripten_yield(0);
+  if (timer_fired) {
+    return -EINTR;
+  }
 #endif // __EMSCRIPTEN_PTHREADS__
 
-  emscripten_conditional_set_current_thread_status(EM_THREAD_STATUS_WAITFUTEX, EM_THREAD_STATUS_RUNNING);
 
   if (ret == ATOMICS_WAIT_NOT_EQUAL) {
     return -EWOULDBLOCK;
@@ -214,3 +222,11 @@ int emscripten_futex_wait(volatile void *addr, uint32_t val, double max_wait_ms)
   assert(ret == ATOMICS_WAIT_OK);
   return 0;
 }
+
+
+int emscripten_futex_wait(volatile void *addr, uint32_t val, double max_wait_ms) {
+  emscripten_conditional_set_current_thread_status(EM_THREAD_STATUS_RUNNING, EM_THREAD_STATUS_WAITFUTEX);
+  int ret = _do_futex_wait(addr, val, max_wait_ms);
+  emscripten_conditional_set_current_thread_status(EM_THREAD_STATUS_WAITFUTEX, EM_THREAD_STATUS_RUNNING);
+  return ret;
+}
diff --git a/system/lib/pthread/emscripten_yield.c b/system/lib/pthread/emscripten_yield.c
@@ -18,13 +18,14 @@ void _emscripten_thread_crashed() {
   _emscripten_thread_notify(emscripten_main_runtime_thread_id());
 }
 
-static void dummy(double now)
-{
+static bool dummy(double now) {
+  return false;
 }
 
 weak_alias(dummy, _emscripten_check_timers);
 
-void _emscripten_yield(double now) {
+bool _emscripten_yield(double now) {
+  bool rtn = false;
   // When a secondary thread crashes, we need to be able to interrupt the main
   // thread even if it's in a blocking/looping on a mutex.  We want to avoid
   // using the normal proxying mechanism to send this message since it can
@@ -42,7 +43,7 @@ void _emscripten_yield(double now) {
     }
 
     // This is no-op in programs that don't include use of itimer/alarm.
-    _emscripten_check_timers(now);
+    rtn = _emscripten_check_timers(now);
 
     // Assist other threads by executing proxied operations that are effectively
     // singlethreaded.
@@ -53,4 +54,5 @@ void _emscripten_yield(double now) {
     _emscripten_process_dlopen_queue();
   }
 #endif
+  return rtn;
 }
diff --git a/system/lib/pthread/threading_internal.h b/system/lib/pthread/threading_internal.h
@@ -8,6 +8,7 @@
 #pragma once
 
 #include <pthread.h>
+#include <stdbool.h>
 
 // Defined THREADING_DEBUG here (or in the build system) to enabled verbose
 // logging using emscripten_dbgf.
@@ -51,7 +52,9 @@ typedef struct thread_profiler_block {
 // argument.  This can save _emscripten_check_timers from needing to call out to
 // JS to get the current time.  Passing 0 means that caller doesn't know the
 // current time.
-void _emscripten_yield(double now);
+//
+// Returns true is a timer was fired, false otherwise.
+bool _emscripten_yield(double now);
 
 void _emscripten_init_main_thread_js(void* tb);
 void _emscripten_thread_profiler_enable();
diff --git a/test/codesize/test_codesize_hello_dylink_all.json b/test/codesize/test_codesize_hello_dylink_all.json
@@ -1,7 +1,7 @@
 {
   "a.out.js": 244416,
-  "a.out.nodebug.wasm": 577664,
-  "total": 822080,
+  "a.out.nodebug.wasm": 577672,
+  "total": 822088,
   "sent": [
     "IMG_Init",
     "IMG_Load",
diff --git a/test/codesize/test_codesize_minimal_pthreads.json b/test/codesize/test_codesize_minimal_pthreads.json
@@ -1,10 +1,10 @@
 {
   "a.out.js": 7323,
   "a.out.js.gz": 3573,
-  "a.out.nodebug.wasm": 19095,
-  "a.out.nodebug.wasm.gz": 8830,
-  "total": 26418,
-  "total_gz": 12403,
+  "a.out.nodebug.wasm": 19065,
+  "a.out.nodebug.wasm.gz": 8807,
+  "total": 26388,
+  "total_gz": 12380,
   "sent": [
     "a (memory)",
     "b (exit)",
diff --git a/test/codesize/test_codesize_minimal_pthreads_memgrowth.json b/test/codesize/test_codesize_minimal_pthreads_memgrowth.json
@@ -1,10 +1,10 @@
 {
   "a.out.js": 7726,
   "a.out.js.gz": 3779,
-  "a.out.nodebug.wasm": 19096,
-  "a.out.nodebug.wasm.gz": 8831,
-  "total": 26822,
-  "total_gz": 12610,
+  "a.out.nodebug.wasm": 19066,
+  "a.out.nodebug.wasm.gz": 8808,
+  "total": 26792,
+  "total_gz": 12587,
   "sent": [
     "a (memory)",
     "b (exit)",
diff --git a/test/pthread/test_pthread_join_interrupted.c b/test/pthread/test_pthread_join_interrupted.c
@@ -0,0 +1,57 @@
+#define _GNU_SOURCE // for pthread_timedjoin_np
+#include <pthread.h>
+#include <assert.h>
+#include <stdio.h>
+#include <unistd.h>
+#include <stdbool.h>
+#include <signal.h>
+
+_Atomic bool got_alarm = false;
+
+void* thread_main(void* arg) {
+  printf("thread_main\n");
+  while (!got_alarm) {
+    // Sleep in 1ms chunks until the main thread recieves the alarm.
+    usleep(1 * 1000);
+  }
+  usleep(100 * 1000);
+  return (void*)42;
+}
+
+void my_handler(int signum) {
+  assert(signum == SIGALRM);
+  got_alarm = true;
+}
+
+int main() {
+  int rtn;
+  printf("main\n");
+  pthread_t t;
+  // Set an alarm to fire while we are waiting for the thread to exit.
+  signal(SIGALRM, my_handler);
+  alarm(1);
+  rtn = pthread_create(&t, NULL, thread_main, NULL);
+  assert(rtn == 0);
+  void* result;
+  // Test that the alarm does not interrupt the join operation.  i.e.
+  // join should not return fail or return early here.
+  rtn = pthread_join(t, &result);
+  assert(rtn == 0);
+  assert((int)result == 42);
+
+  // Same again but this time with a pthread_timedjoin_np
+  got_alarm = false;
+  result = 0;
+  alarm(1);
+  rtn = pthread_create(&t, NULL, thread_main, NULL);
+  assert(rtn == 0);
+  struct timespec timeout;
+  clock_gettime(CLOCK_REALTIME, &timeout);
+  timeout.tv_sec += 3;
+  rtn = pthread_timedjoin_np(t, &result, &timeout);
+  assert(rtn == 0);
+  assert((int)result == 42);
+
+  printf("done\n");
+  return 0;
+}
diff --git a/test/test_other.py b/test/test_other.py
@@ -13082,6 +13082,10 @@ def test_pthread_growth_mainthread(self, cflags, pthread_pool_size):
     self.set_setting('PTHREAD_POOL_SIZE', pthread_pool_size)
     self.do_runf('pthread/test_pthread_memory_growth_mainthread.c', cflags=['-pthread', '-sALLOW_MEMORY_GROWTH', '-sINITIAL_MEMORY=32MB', '-sMAXIMUM_MEMORY=256MB'] + cflags)
 
+  @requires_pthreads
+  def test_phtread_join_interrupted(self):
+    self.do_runf('pthread/test_pthread_join_interrupted.c', cflags=['-pthread', '-sPTHREAD_POOL_SIZE=1'])
+
   @requires_node_25
   def test_growable_arraybuffers(self):
     self.node_args.append('--experimental-wasm-rab-integration')
diff --git a/test/test_posixtest.py b/test/test_posixtest.py
@@ -61,15 +61,15 @@ def get_tests():
 # TODO: Investigate failing semaphores tests.
 unsupported_noreturn = {
   'test_pthread_mutex_lock_5_1': 'signals are not supported',
-  'test_pthread_spin_lock_3_1': 'signals are not supported',
+  'test_pthread_spin_lock_1_1': 'signals are not supported during spin lock',
+  'test_pthread_spin_lock_3_1': 'signals are not supported during spin lock',
   'test_pthread_join_6_3': 'creates too many threads',
   'test_pthread_barrier_wait_3_2': 'signals are not supported',
   'test_pthread_cond_broadcast_1_2': 'tries to create 10,0000 threads, then depends on fork()',
   'test_pthread_setcanceltype_1_1': 'async cancelation does not work withing pthread_mutex_lock',
 }
 
 unsupported = {
-  'test_pthread_spin_lock_1_1': 'alarm causes spurious wakeup during pthread_join',
   'test_pthread_exit_6_1': 'fork() and multiple processes are not supported',
   'test_pthread_atfork_1_1': 'fork() and multiple processes are not supported',
   'test_pthread_atfork_1_2': 'fork() and multiple processes are not supported',

Original file line number	Diff line number	Diff line change
`@@ -7,11 +7,14 @@`
`7`	`7`
`8`	`8`	`#include <features.h>`
`9`	`9`
`10`		`-static void dummy(double now) {`
	`10`	`+#include "threading_internal.h"`
	`11`	`+`
	`12`	`+static bool dummy(double now) {`
	`13`	`+ return false;`
`11`	`14`	`}`
`12`	`15`
`13`	`16`	`weak_alias(dummy, _emscripten_check_timers);`
`14`	`17`
`15`		`-void _emscripten_yield(double now) {`
`16`		`- _emscripten_check_timers(now);`
	`18`	`+bool _emscripten_yield(double now) {`
	`19`	`+ return _emscripten_check_timers(now);`
`17`	`20`	`}`
Original file line number	Diff line number	Diff line change
`@@ -64,21 +64,25 @@ void _emscripten_timeout(int which, double now)`
`64`	`64`	`raise(signum);`
`65`	`65`	`}`
`66`	`66`
`67`		`-void _emscripten_check_timers(double now)`
	`67`	`+bool _emscripten_check_timers(double now)`
`68`	`68`	`{`
`69`	`69`	`// Timers always run on the main runtime thread. They are registered with`
`70`	`70`	`// _setitimer_js which is proxied to the main runtime thread.`
`71`	`71`	`assert(emscripten_is_main_runtime_thread());`
	`72`	`+ bool rtn = false;`
`72`	`73`	`for (int which = 0; which < 3; which++) {`
`73`	`74`	`if (current_timeout_ms[which]) {`
`74`	`75`	`// Only call out to JS to get the current time if it was not passed in`
`75`	`76`	`// and we have one or more timers set.`
`76`	`77`	`if (!now)`
`77`	`78`	`now = emscripten_get_now();`
`78`		`- if (now >= current_timeout_ms[which])`
	`79`	`+ if (now >= current_timeout_ms[which]) {`
	`80`	`+ rtn = true;`
`79`	`81`	`_emscripten_timeout(which, now);`
	`82`	`+ }`
`80`	`83`	`}`
`81`	`84`	`}`
	`85`	`+ return rtn;`
`82`	`86`	`}`
`83`	`87`
`84`	`88`	`double _emscripten_next_timer()`
Original file line number	Diff line number	Diff line change
`@@ -18,13 +18,14 @@ void _emscripten_thread_crashed() {`
`18`	`18`	`_emscripten_thread_notify(emscripten_main_runtime_thread_id());`
`19`	`19`	`}`
`20`	`20`
`21`		`-static void dummy(double now)`
`22`		`-{`
	`21`	`+static bool dummy(double now) {`
	`22`	`+ return false;`
`23`	`23`	`}`
`24`	`24`
`25`	`25`	`weak_alias(dummy, _emscripten_check_timers);`
`26`	`26`
`27`		`-void _emscripten_yield(double now) {`
	`27`	`+bool _emscripten_yield(double now) {`
	`28`	`+ bool rtn = false;`
`28`	`29`	`// When a secondary thread crashes, we need to be able to interrupt the main`
`29`	`30`	`// thread even if it's in a blocking/looping on a mutex. We want to avoid`
`30`	`31`	`// using the normal proxying mechanism to send this message since it can`
`@@ -42,7 +43,7 @@ void _emscripten_yield(double now) {`
`42`	`43`	`}`
`43`	`44`
`44`	`45`	`// This is no-op in programs that don't include use of itimer/alarm.`
`45`		`- _emscripten_check_timers(now);`
	`46`	`+ rtn = _emscripten_check_timers(now);`
`46`	`47`
`47`	`48`	`// Assist other threads by executing proxied operations that are effectively`
`48`	`49`	`// singlethreaded.`
`@@ -53,4 +54,5 @@ void _emscripten_yield(double now) {`
`53`	`54`	`_emscripten_process_dlopen_queue();`
`54`	`55`	`}`
`55`	`56`	`#endif`
	`57`	`+ return rtn;`
`56`	`58`	`}`