Improved LockCore and UnlockCore documentation for clarity on usage, behavior, and limitations with the "cores" scheduler. Updated LockOSThread and UnlockOSThread comments to reflect core pinning behavior on RP2040/RP2350.

Author: amken3d

src/machine/machine_rp2_cores.go

@@ -4,15 +4,46 @@ package machine
 
 const numCPU = 2 // RP2040 and RP2350 both have 2 cores
 
-// LockCore implementation for the cores scheduler.
+// LockCore sets the affinity for the current goroutine to the specified core.
+// This does not immediately migrate the goroutine; migration occurs at the next
+// scheduling point. See machine_rp2.go for full documentation.
+// Important: LockCore sets the affinity but does not immediately migrate the
+// goroutine to the target core. The actual migration happens at the next
+// scheduling point (e.g., channel operation, time.Sleep, or Gosched). After
+// that point, the goroutine will wait in the target core's queue if that core
+// is busy running another goroutine.
+//
+// To avoid potential blocking on a busy core, consider calling LockCore in an
+// init function before any other goroutines have started. This guarantees the
+// target core is available.
+//
+// This is useful for:
+//   - Isolating time-critical operations to a dedicated core
+//   - Improving cache locality for performance-sensitive code
+//   - Exclusive access to core-local resources
+//
+// Warning: Pinning goroutines can lead to load imbalance. The goroutine will
+// wait in the specified core's queue even if other cores are idle. If a
+// long-running goroutine occupies the target core, LockCore may appear to
+// block indefinitely (until the next scheduling point on the target core).
+//
+// Valid core values are 0 and 1. Panics if core is out of range.
+//
+// Only available on RP2040 and RP2350 with the "cores" scheduler.
 func LockCore(core int) {
 	if core < 0 || core >= numCPU {
 		panic("machine: core out of range")
 	}
 	machineLockCore(core)
 }
 
-// UnlockCore implementation for the cores scheduler.
+// UnlockCore unpins the calling goroutine, allowing it to run on any available core.
+// This undoes a previous call to LockCore.
+//
+// After calling UnlockCore, the scheduler is free to schedule the goroutine on
+// any core for automatic load balancing.
+//
+// Only available on RP2040 and RP2350 with the "cores" scheduler.
 func UnlockCore() {
 	machineUnlockCore()
 }

src/runtime/runtime.go

@@ -100,6 +100,9 @@ func os_sigpipe() {
 // LockOSThread wires the calling goroutine to its current operating system thread.
 // On microcontrollers with multiple cores (e.g., RP2040/RP2350), this pins the
 // goroutine to the core it's currently running on.
+// With the "cores" scheduler on RP2040/RP2350, this pins the goroutine to the
+// core it's currently running on. The pinning takes effect at the next
+// scheduling point (e.g., channel operation, time.Sleep, or Gosched).
 // Called by go1.18 standard library on windows, see https://github.com/golang/go/issues/49320
 func LockOSThread() {
 	lockOSThreadImpl()
@@ -108,6 +111,8 @@ func LockOSThread() {
 // UnlockOSThread undoes an earlier call to LockOSThread.
 // On microcontrollers with multiple cores, this unpins the goroutine, allowing
 // it to run on any available core.
+// With the "cores" scheduler, this unpins the goroutine, allowing it to run on
+// any available core.
 func UnlockOSThread() {
 	unlockOSThreadImpl()
 }