internal/task: add cooperative implementation of Futex

See the code comments for details. But in short, this implements a futex
for the cooperative scheduler (that is single threaded and
non-reentrant). Similar implementations can be made for basically every
other operating system, and even WebAssembly with the threading
(actually: atomics) proposal.
Using this basic futex implementation means we can use the same
implementation for synchronisation primitives on cooperative and
multicore systems.

For more information on futex across operating systems:
https://outerproduct.net/futex-dictionary.html

Author: aykevl

src/internal/task/atomic-cooperative.go

@@ -5,7 +5,7 @@ package task
 // different goroutine or interrupt happening at the same time.
 
 type atomicIntegerType interface {
-	uintptr | uint64
+	uintptr | uint32 | uint64
 }
 
 type pseudoAtomic[T atomicIntegerType] struct {
@@ -32,6 +32,10 @@ func (x *pseudoAtomic[T]) Swap(new T) (old T) {
 // uintptr otherwise.
 type Uintptr = pseudoAtomic[uintptr]
 
+// Uint32 is an atomic uint32 when multithreading is enabled, and a plain old
+// uint32 otherwise.
+type Uint32 = pseudoAtomic[uint32]
+
 // Uint64 is an atomic uint64 when multithreading is enabled, and a plain old
 // uint64 otherwise.
 type Uint64 = pseudoAtomic[uint64]

src/internal/task/futex-cooperative.go

@@ -0,0 +1,44 @@
+package task
+
+// A futex is a way for userspace to wait with the pointer as the key, and for
+// another thread to wake one or all waiting threads keyed on the same pointer.
+//
+// A futex does not change the underlying value, it only reads it before to prevent
+// lost wake-ups.
+type Futex struct {
+	Uint32
+	waiters Stack
+}
+
+// Atomically check for cmp to still be equal to the futex value and if so, go
+// to sleep. Return true if we were definitely awoken by a call to Wake or
+// WakeAll, and false if we can't be sure of that.
+func (f *Futex) Wait(cmp uint32) (awoken bool) {
+	if f.Uint32.v != cmp {
+		return false
+	}
+
+	// Push the current goroutine onto the waiter stack.
+	f.waiters.Push(Current())
+
+	// Pause until the waiters are awoken by Wake/WakeAll.
+	Pause()
+
+	// We were awoken by a call to Wake or WakeAll. There is no chance for
+	// spurious wakeups.
+	return true
+}
+
+// Wake a single waiter.
+func (f *Futex) Wake() {
+	if t := f.waiters.Pop(); t != nil {
+		scheduleTask(t)
+	}
+}
+
+// Wake all waiters.
+func (f *Futex) WakeAll() {
+	for t := f.waiters.Pop(); t != nil; t = f.waiters.Pop() {
+		scheduleTask(t)
+	}
+}