Initial project import

tools/v/vlib/goroutines/goroutines.v

@@ -0,0 +1,228 @@
+// Copyright (c) 2026 Alexander Medvednikov. All rights reserved.
+// Use of this source code is governed by an MIT license
+// that can be found in the LICENSE file.
+//
+// Go-style goroutine runtime for V.
+// Implements the GMP (Goroutine-Machine-Processor) scheduling model
+// translated from the Go runtime (src/runtime/proc.go, runtime2.go).
+//
+// Goroutine - goroutine: lightweight unit of execution with its own stack
+// Machine - machine: OS thread that executes goroutines
+// Processor - processor: logical processor that manages a local run queue
+//
+// Design doc: https://golang.org/s/go11sched
+@[has_globals]
+module goroutines
+
+import sync
+import runtime as _
+
+// GoFn is the type for a goroutine function: takes a voidptr argument.
+pub type GoFn = fn (voidptr)
+
+// Default goroutine stack size.
+// Go uses 8KB with growable stacks; V/C needs more since stacks are fixed.
+const default_stack_size = 256 * 1024
+
+// Maximum number of goroutines in a Processor's local run queue (matches Go's 256)
+const local_queue_size = 256
+
+// How often to check the global queue for fairness (matches Go's 61)
+const global_queue_check_interval = 61
+
+// GStatus represents goroutine states (matches Go's runtime2.go)
+pub enum GStatus {
+	idle      // just allocated, not yet initialized
+	runnable  // on a run queue, not currently executing
+	running   // executing user code on an Machine
+	waiting   // blocked (channel, mutex, etc.)
+	dead      // finished execution, available for reuse
+	copystack // stack is being moved (not used yet)
+}
+
+// PStatus represents processor states
+pub enum PStatus {
+	idle    // not being used, available on idle list
+	running // owned by an Machine and executing code
+	stopped // halted
+	dead    // no longer used
+}
+
+// Goroutine represents a goroutine - the fundamental unit of concurrent execution.
+// Translated from Go's `type g struct` in runtime2.go.
+pub struct Goroutine {
+pub mut:
+	id          u64 // unique goroutine id
+	status      GStatus = .idle // current state
+	stack       voidptr // stack memory (allocated)
+	stack_size  int = default_stack_size // stack allocation size
+	context     Context // saved CPU context for switching (ucontext_t or similar)
+	fn_ptr      voidptr // function to execute
+	fn_arg      voidptr // argument to the function
+	sched_link  &Goroutine = unsafe { nil } // linked list link for run queues
+	m           &Machine   = unsafe { nil } // current Machine executing this Goroutine (nil if not running)
+	parent_id   u64    // goroutine id of creator
+	wait_reason string // if status==waiting, why
+	preempt     bool   // preemption signal
+}
+
+// Machine represents a machine (OS thread) that executes goroutines.
+// Translated from Go's `type m struct` in runtime2.go.
+pub struct Machine {
+pub mut:
+	id         i64
+	g0         &Goroutine = unsafe { nil } // goroutine with scheduling stack
+	curg       &Goroutine = unsafe { nil } // current running goroutine
+	p          &Processor = unsafe { nil } // attached processor (nil if not executing Go code)
+	spinning   bool           // looking for work
+	blocked    bool           // blocked on a note
+	park       sync.Semaphore // for parking/unparking
+	sched_link &Machine = unsafe { nil } // linked list for idle Machine list
+	thread     thread // underlying OS thread handle
+}
+
+// Processor represents a processor - a resource required to execute goroutines.
+// Each Processor has a local run queue. Translated from Go's `type p struct` in runtime2.go.
+pub struct Processor {
+pub mut:
+	id         i32
+	status     PStatus  = .idle
+	m          &Machine = unsafe { nil } // back-link to associated Machine
+	sched_tick u32 // incremented on every scheduler call
+
+	// Local run queue - lock-free SPMC ring buffer (matches Go's design)
+	runq_head u32 // consumer index (atomic)
+	runq_tail u32 // producer index (atomic)
+	runq      [local_queue_size]&Goroutine // circular buffer
+	runnext   &Goroutine = unsafe { nil } // next Goroutine to run (fast path, like Go's runnext)
+
+	// Free Goroutine list for reuse
+	g_free GoroutineList
+
+	// ID cache to avoid contention on the global counter
+	goid_cache     u64
+	goid_cache_end u64
+
+	link &Processor = unsafe { nil } // linked list for idle Processor list
+}
+
+// Sched is the global scheduler state.
+// Translated from Go's `type schedt struct` in runtime2.go.
+pub struct Sched {
+pub mut:
+	goid_gen u64 // global goroutine ID generator (atomic)
+
+	mu SpinLock // protects idle lists, global queue (spinlock is ucontext-safe)
+
+	// Idle Machine's waiting for work
+	midle  &Machine = unsafe { nil }
+	nmidle i32
+
+	// Idle Processor's
+	pidle  &Processor = unsafe { nil }
+	npidle i32
+
+	// Global run queue
+	runq       GoroutineQueue
+	nmspinning i32 // number of spinning Machine's (atomic)
+
+	// All Processor's (indexed by id)
+	allp []&Processor
+
+	// Total Machine count
+	mnext     i64
+	maxmcount i32 = 10000
+
+	// Global Goroutine free list
+	g_free_mu    SpinLock
+	g_free       GoroutineList
+	g_free_count i32
+
+	// Shutdown
+	stopped bool
+}
+
+// GoroutineQueue is a simple linked-list queue of Goroutine's (matches Go's gQueue).
+pub struct GoroutineQueue {
+pub mut:
+	head &Goroutine = unsafe { nil }
+	tail &Goroutine = unsafe { nil }
+	size i32
+}
+
+// GoroutineList is a list of Goroutine's.
+pub struct GoroutineList {
+pub mut:
+	head  &Goroutine = unsafe { nil }
+	count i32
+}
+
+fn (mut q GoroutineQueue) push_back(gp &Goroutine) {
+	mut g := unsafe { gp }
+	g.sched_link = unsafe { nil }
+	if q.tail != unsafe { nil } {
+		q.tail.sched_link = g
+	} else {
+		q.head = g
+	}
+	q.tail = g
+	q.size++
+}
+
+fn (mut q GoroutineQueue) push(gp &Goroutine) {
+	mut g := unsafe { gp }
+	g.sched_link = q.head
+	q.head = g
+	if q.tail == unsafe { nil } {
+		q.tail = g
+	}
+	q.size++
+}
+
+fn (mut q GoroutineQueue) pop() &Goroutine {
+	if q.head == unsafe { nil } {
+		return unsafe { nil }
+	}
+	gp := q.head
+	q.head = gp.sched_link
+	if q.head == unsafe { nil } {
+		q.tail = unsafe { nil }
+	}
+	q.size--
+	return gp
+}
+
+fn (q &GoroutineQueue) empty() bool {
+	return q.head == unsafe { nil }
+}
+
+fn (mut l GoroutineList) push(gp &Goroutine) {
+	mut g := unsafe { gp }
+	g.sched_link = l.head
+	l.head = g
+	l.count++
+}
+
+fn (mut l GoroutineList) pop() &Goroutine {
+	if l.head == unsafe { nil } {
+		return unsafe { nil }
+	}
+	gp := l.head
+	l.head = gp.sched_link
+	l.count--
+	return gp
+}
+
+fn (l &GoroutineList) empty() bool {
+	return l.head == unsafe { nil }
+}
+
+// Global scheduler instance
+__global gsched = Sched{}
+
+// Number of processors (defaults to number of CPU cores)
+__global gomaxprocs = i32(0)
+
+// All goroutines ever created (for debugging)
+__global allgs_mu = SpinLock{}
+__global allgs = []&Goroutine{}