Initial project import

tools/v/vlib/goroutines/README.md

@@ -0,0 +1,57 @@
+# goroutines
+
+> `goroutines` is experimental.
+> It landed after `0.5.1`, so `import goroutines` is not available in that release.
+
+Go-style goroutine runtime for V, implementing the GMP
+(Goroutine-Machine-Processor) scheduling model translated
+from the Go runtime (`src/runtime/proc.go`, `runtime2.go`,
+`chan.go`).
+
+## Overview
+
+This module provides lightweight goroutines for V's `go`
+keyword, as opposed to `spawn` which creates OS threads.
+
+### GMP Model
+
+- **G (Goroutine)**: Lightweight unit of execution with its own stack (~8KB default)
+- **M (Machine)**: OS thread that executes goroutines
+- **P (Processor)**: Logical processor with a local run queue (one per CPU core)
+
+### Key Features
+
+- **Work stealing**: Idle processors steal work from busy ones
+- **Local run queues**: Lock-free per-P queues minimize contention
+- **Global run queue**: Overflow and fairness mechanism
+- **Goroutine parking**: Efficient blocking/unblocking for channels
+- **G reuse**: Dead goroutines are recycled to reduce allocation
+
+## Usage
+
+```v ignore
+// `go` launches a goroutine (lightweight, scheduled by GMP)
+go expensive_computation()
+
+// `spawn` launches an OS thread (traditional V behavior)
+spawn blocking_io_task()
+```
+
+## Architecture
+
+Translated from Go's runtime source:
+
+| Go Source | V Module File | Purpose |
+|-----------|---------------|---------|
+| `runtime2.go` | `goroutines.v` | Core data structures (G, M, P, Sched) |
+| `proc.go` | `scheduler.v` | Scheduler loop, work stealing, run queues |
+| `proc.go` | `park.v` | gopark/goready, Sudog, WaitQ |
+| `proc.go` | `init.v` | Initialization (schedinit, procresize) |
+| `chan.go` | `chan.v` | Channel implementation |
+| asm (gogo/gosave) | `context_nix.c.v` | Context switching (ucontext) |
+| asm (gogo/gosave) | `context_windows.c.v` | Context switching (Windows fibers) |
+
+## References
+
+- [Go Scheduler Design Doc](https://golang.org/s/go11sched)
+- [Go Runtime Source](https://github.com/golang/go/tree/master/src/runtime)