// 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{}