Design doc feedback from #26621. NFC

Author: sbc100

docs/design/01-precise-futex-wakeups.md

@@ -24,7 +24,7 @@ CPU wakeups and increased latency for events.
 ## Non-Goals
 - **Main Browser Thread**: Changes to the busy-wait loop in `futex_wait_main_browser_thread` are out of scope.
 - **Direct Atomics Usage**: Threads that call `atomic.wait` directly (bypassing `emscripten_futex_wait`) will remain un-interruptible.
-- **Wasm Workers**: Wasm Worker do not have a `pthread` structure, they are not covered by this design.
+- **Wasm Workers**: Wasm Workers do not have a `pthread` structure, so they are not covered by this design.
 
 ## Proposed Design
 
@@ -85,7 +85,7 @@ When a thread needs to wake another thread for a side-channel event (e.g., in `p
 3.  If `target_addr` is not NULL:
     -   Read `start_c = target->wait_counter` (`SEQ_CST`).
     -   Enter a loop:
-        -   Call `emscripten_futex_wake(target_addr, 1)`.
+        -   Call `emscripten_futex_wake(target_addr, INT_MAX)`.
         -   Exit loop if `target->wait_counter != start_c` OR `target->waiting_on_address != target_addr`.
         -   **Yield**: Call `sched_yield()` (or a small sleep) to allow the target thread to proceed if it is currently being scheduled.
 
@@ -106,7 +106,7 @@ counter.
 ### 5. Overlapping and Spurious Wakeups
 The design must handle cases where "real" wakeups (triggered by the application) and "side-channel" wakeups (cancellation/mailbox) occur simultaneously.
 
-1.  **Spurious Wakeups for Other Threads**: If multiple threads are waiting on the same address (e.g., a shared mutex), a side-channel `atomic_wake(addr, 1)` targeted at Thread A might be delivered by the kernel to Thread B.
+1.  **Spurious Wakeups for Other Threads**: If multiple threads are waiting on the same address (e.g., a shared mutex), a side-channel `atomic_wake(addr, 1)` targeting Thread A could also wake Thread B.
     -   **Thread B's response**: It will wake up, increment its `wait_counter`, see that its `wait_reasons` are empty, and return `0` to its caller.
     -   **Thread C (the waker)**: It will see that Thread A's `wait_counter` has *not* changed and `waiting_on_address` is still `addr`. It will therefore continue its loop and call `atomic_wake` again until Thread A is finally woken.
     -   **Result**: Thread B experiences a "spurious" wakeup. This is acceptable and expected behavior for futex-based synchronization.
@@ -118,7 +118,8 @@ The `wait_counter` is a `uint32_t` and will wrap around to zero after $2^{32}$ w
 1.  **Impossibility of Racing**: For the waker to "miss" a wake-up due to wrap-around, the waiter would have to wake up and re-enter a sleep state exactly $2^{32}$ times in the very brief window between the waker's `atomic_wake` and its subsequent check of `wait_counter`. Even at extreme wakeup frequencies (e.g., 1 million per second), this would take over an hour.
 2.  **Address Change Check**: The waker loop also checks `target->waiting_on_address != target_addr`. If the waiter wakes up and either stops waiting or starts waiting on a *different* address, the waker will exit the loop regardless of the counter value.
 
-### 6. Benefits
+## Benefits
+
 -   **Lower Power Consumption**: Threads can sleep indefinitely (or for the full duration of a user-requested timeout) without periodic wakeups.
 -   **Lower Latency**: Mailbox events and cancellation requests are processed immediately rather than waiting for the next 1ms or 100ms tick.
 -   **Simpler Loop**: The complex logic for calculating remaining timeout slices in `emscripten_futex_wait` is removed.

docs/design/README.md

@@ -3,8 +3,19 @@
 This directory contains design documents for emscripten features and major
 changes/refactors.
 
-We are experimenting with keeping these document here under source control with
+We are experimenting with keeping these documents here under source control with
 the hope that this will increase understandability of the codebase.  This has
-some advantages over doing all planning in Google Docs or GitHub issues.  For
-example, it allows us to track the history of designs and it allows them to be
-searchable using standard tools like `git grep`.
+some advantages over doing all our planning in Google Docs or GitHub issues.
+For example, it allows us to track the history of designs and it allows them to
+be searchable using standard tools like `git grep`.
+
+## Document Format
+
+Each document in this directory should be a markdown file.  At the top of each
+document should be a `Status` which can be either `Draft`, `Accepted`,
+`Completed`.
+
+When a document is marked as `Completed` it should also be updated such that
+it is clear the work has been done, and is now in the past.  For example,
+phrases such as "The current behavior" should be replaced with "The previous
+behavior".