Implement precise pthread wakeups by sbc100 · Pull Request #26659 · emscripten-core/emscripten

sbc100 · 2026-04-09T07:11:58Z

This change implements the design in docs/design/01-precise-futex-wakeups.md

As part of this change emscripten_futex_wait API now explicitly allows spurious wakeups, much like the corresponding linux syscall. There were a couple of tests that were using emscripten_futex_wait without a loop, so I added loops to them in an abundance of caution.

Fixes: #26633

tlively · 2026-04-09T17:06:43Z

"implemenat" => "implements" in description.

system/include/emscripten/threading_primitives.h

system/lib/libc/musl/src/internal/pthread_impl.h

system/lib/pthread/em_task_queue.c

system/lib/pthread/emscripten_futex_wait.c

system/lib/pthread/emscripten_futex_wake.c

This change implements the design in docs/design/01-precise-futex-wakeups.md Note: As part of this change the definition of emscripten_futex_wait was changes to explicitly allow spurious wakeups. Fixes: emscripten-core#26633

tlively · 2026-04-11T02:00:01Z

system/include/emscripten/threading_primitives.h


 // 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.


Suggested change

// Note: Like the Linux futex syscall, this APi *does* allow spurious wakeups.

// Note: Like the Linux futex syscall, this API *does* allow spurious wakeups.

tlively · 2026-04-11T02:00:22Z

system/include/emscripten/threading_primitives.h

+// 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 wraps this some kind loop.


Suggested change

// to wraps this some kind loop.

// to wrap this in some kind loop.

tlively · 2026-04-11T02:01:04Z

system/lib/libc/musl/src/thread/pthread_cancel.c

 		return 0;
 	}
+#ifdef __EMSCRIPTEN__
+	// Wake the target thread in case it in emscripten_futex_wait.  Normally


Suggested change

// Wake the target thread in case it in emscripten_futex_wait. Normally

// Wake the target thread in case it is in emscripten_futex_wait. Normally

tlively · 2026-04-11T02:03:36Z

system/lib/pthread/emscripten_futex_wait.c

+  } else {
+    DBG("emscripten_futex_wait skipping atomic.wait due to NOTIFY_BIT");
+    // CAS failed, NOTIFY_BIT must have been set.  In this case we don't
+    // actually wait at all.  Instead we behaviour as if we spuriously woke up


Suggested change

// actually wait at all. Instead we behaviour as if we spuriously woke up

// actually wait at all. Instead we behave as if we spuriously woke up

tlively · 2026-04-11T02:07:10Z

system/lib/pthread/emscripten_futex_wait.c

+    return -ECANCELED;
+  }
+#else
+  ret = __builtin_wasm_memory_atomic_wait32((int*)addr, val, max_wait_ns);


It would be good to add an // __EMSCRIPTEN_PTHREADS__ comment to the above #else. Otherwise the presence of a second wait here is very confusing. Actually, why do we wait when pthreads are not enabled? Is it just in case user code will handle the notify, e.g. from JS? Or is this a Wasm Workers thing?

tlively · 2026-04-11T02:16:11Z

system/lib/pthread/proxying.c

+  // Then proxying work to the main thread using the system queue we have
+  // a very special case in that we need the target thread to wake up from
+  // `emscripten_futex_wait` to process the queue.
+  if (rtn && is_system_queue && pthread_equal(target_thread, emscripten_main_runtime_thread_id())) {


It would be good to clang-format this to wrap to 80 columns. At least that's what the rest of the proxying code uses.

tlively · 2026-04-11T02:16:33Z

system/lib/pthread/proxying.c


-  return em_task_queue_send(tasks, t);
+  bool rtn =  em_task_queue_send(tasks, t);
+  // Then proxying work to the main thread using the system queue we have


Suggested change

// Then proxying work to the main thread using the system queue we have

// When proxying work to the main thread using the system queue we have

tlively · 2026-04-11T02:17:29Z

system/lib/pthread/proxying.c

  }

-  return em_task_queue_send(tasks, t);
+  bool rtn =  em_task_queue_send(tasks, t);


I would have expected ret rather than rtn. Unless there is common precedent for rtn in the code base?

Suggested change

bool rtn = em_task_queue_send(tasks, t);

bool ret = em_task_queue_send(tasks, t);

tlively · 2026-04-11T02:19:39Z

system/lib/pthread/threading_internal.h

 // since blocking is not allowed there).
 int _emscripten_thread_supports_atomics_wait(void);
+
+// Notify a thread that it has new work to do (cancellation or mailbox).


Suggested change

// Notify a thread that it has new work to do (cancellation or mailbox).

All the method does is inject the wakeup, so I would avoid suggesting that it also directly causes the target thread to do anything like check a mailbox.

tlively · 2026-04-11T02:20:18Z

ChangeLog.md


 5.0.6 (in development)
 ----------------------
+- The emscripten_futux_wait API is not document to explicitly allow spurious


Suggested change

- The emscripten_futux_wait API is not document to explicitly allow spurious

- The emscripten_futux_wait API is now documented to explicitly allow spurious

sbc100 force-pushed the precise_wakeups branch 3 times, most recently from 61f016e to 20d6937 Compare April 9, 2026 16:56

sbc100 requested a review from tlively April 9, 2026 16:56

tlively reviewed Apr 9, 2026

View reviewed changes

sbc100 force-pushed the precise_wakeups branch from 20d6937 to 96b8d1e Compare April 9, 2026 20:15

Implement precise pthread wakeups

1f8caee

This change implements the design in docs/design/01-precise-futex-wakeups.md Note: As part of this change the definition of emscripten_futex_wait was changes to explicitly allow spurious wakeups. Fixes: emscripten-core#26633

sbc100 force-pushed the precise_wakeups branch 2 times, most recently from cb1c872 to 8dc3c30 Compare April 11, 2026 00:49

sbc100 requested a review from tlively April 11, 2026 00:50

Feedback

5a0cd24

sbc100 force-pushed the precise_wakeups branch from 8dc3c30 to 5a0cd24 Compare April 11, 2026 01:14

tlively reviewed Apr 11, 2026

View reviewed changes

	// Note: Like the Linux futex syscall, this APi does allow spurious wakeups.
	// Note: Like the Linux futex syscall, this API does allow spurious wakeups.

	// to wraps this some kind loop.
	// to wrap this in some kind loop.

	// Wake the target thread in case it in emscripten_futex_wait. Normally
	// Wake the target thread in case it is in emscripten_futex_wait. Normally

	// actually wait at all. Instead we behaviour as if we spuriously woke up
	// actually wait at all. Instead we behave as if we spuriously woke up

	// Then proxying work to the main thread using the system queue we have
	// When proxying work to the main thread using the system queue we have

	bool rtn = em_task_queue_send(tasks, t);
	bool ret = em_task_queue_send(tasks, t);

	- The emscripten_futux_wait API is not document to explicitly allow spurious
	- The emscripten_futux_wait API is now documented to explicitly allow spurious

Conversation

sbc100 commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tlively commented Apr 9, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sbc100 commented Apr 9, 2026 •

edited

Loading