| author |  Lucas Santos <lucascarvalhosantos91@gmail.com> 2025-12-25 22:08:34-03:00 |
| committer |  Andrew Kelley <andrew@ziglang.org> 2025-12-27 20:40:19+01:00 |
| log | ef77cc0de1f4453d89d8841116eaa65a42a9c89f |
| tree | 02246336362aa127cf6c4ec806c6f38f0dc11fd4 |
| parent | 9db3e23e8081e7598e35a2da53a2b29c064d8404 |
Fixes doc comment of Futex.wait
On Windows, changing the value at the target address is not sufficient, there needs to be a wake call.
From [MSDN](https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitonaddress):
> If the value at Address differs from the value at CompareAddress, the function returns immediately. If the values are the same, the function does not return until another thread in the same process signals that the value at Address has changed by calling WakeByAddressSingle or WakeByAddressAll or the timeout elapses, whichever comes first.
We could note that this behavior is only observed on Windows. However, if we want the function to have consistent behavior across all platforms, we should require users to call wake. On platforms where changing the value is sufficient to wake the waiting thread, an unblocking of the thread without a matching wake would just be considered a spurious wake.1 files changed, 1 insertions(+), 2 deletions(-)
lib- std
- Thread
lib/std/Thread/Futex.zig+1-2
| ... | ... | @@ -20,8 +20,7 @@ const testing = std.testing; |
| 20 | 20 | const atomic = std.atomic; |
| 21 | 21 | |
| 22 | 22 | /// Checks if `ptr` still contains the value `expect` and, if so, blocks the caller until either: |
| 23 | /// - The value at `ptr` is no longer equal to `expect`. | |
| 24 | /// - The caller is unblocked by a matching `wake()`. | |
| 23 | /// - The value at `ptr` is no longer equal to `expect` and `wake()` is called on the same address. | |
| 25 | 24 | /// - The caller is unblocked spuriously ("at random"). |
| 26 | 25 | /// |
| 27 | 26 | /// The checking of `ptr` and `expect`, along with blocking the caller, is done atomically |