Go Scheduler: The Engine Behind Your Goroutines

A Million Goroutines, Eight Cores

Why Not Just Use OS Threads

• 1MB+ of stack memory
• Kernel involvement for creation
• Expensive context switches (save all registers, switch page tables)
• Kernel scheduling overhead

Go blog diagram 1

The Traffic Controller Analogy

Think of it like this: Imagine an airport with thousands of planes (goroutines) but only a few runways (OS threads). The air traffic controller (scheduler) decides which planes take off when. Planes wait in queues. When one plane is waiting for fuel (I/O), another takes its slot. The controller balances load across runways and handles emergencies. Go's scheduler does exactly this for your goroutines.

The GMP Model Explained

Go blog diagram 2

The Number of Ps

go
// Filename: gomaxprocs.go
package main

import (
    "fmt"
    "runtime"
)

func main() {
    // Default: number of CPU cores
    fmt.Println("GOMAXPROCS:", runtime.GOMAXPROCS(0))

    // You can change it (rarely needed)
    runtime.GOMAXPROCS(4)
    fmt.Println("After change:", runtime.GOMAXPROCS(0))
}

How Scheduling Works

Step 1: Goroutine Creation

go
go func() {
    // New G created
    // Added to current P's local queue
}()

Step 2: Running a Goroutine

Step 3: Goroutine Yields

• Channel operations (send/receive)
• System calls
• Function calls (checking stack growth)
• Explicit runtime.Gosched()
• Blocking operations

Step 4: Work Stealing

1. Check global run queue
2. Check network poller
3. Steal from another P's queue

Go blog diagram 3

Work Stealing in Action

go
// Filename: work_stealing_demo.go
package main

import (
    "fmt"
    "runtime"
    "sync"
    "time"
)

func main() {
    runtime.GOMAXPROCS(2) // 2 Ps

    var wg sync.WaitGroup

    // Create unbalanced load
    // 100 goroutines started from one P
    for i := 0; i < 100; i++ {
        wg.Add(1)
        go func(id int) {
            defer wg.Done()
            // Simulate work
            time.Sleep(10 * time.Millisecond)
        }(i)
    }

    // Work stealing ensures both Ps stay busy
    // Even though all Gs started on one P

    wg.Wait()
    fmt.Println("All done - work stealing balanced the load")
}

Preemption: No More Infinite Loops

go
// Before Go 1.14: This would block other goroutines
go func() {
    for {
        // No function calls = no yield points
    }
}()

Go blog diagram 4

Scheduling During System Calls

Go blog diagram 5

Network Poller Integration

go
// When you write:
conn.Read(buffer)

// Go's runtime:
// 1. Tries non-blocking read
// 2. If would block, registers with network poller
// 3. Goroutine is parked (not running, not in queue)
// 4. Network poller wakes goroutine when data arrives

Visualizing the Scheduler

GoBash
// Filename: trace_example.go
package main

import (
    "os"
    "runtime/trace"
    "sync"
)

func main() {
    f, _ := os.Create("trace.out")
    trace.Start(f)
    defer trace.Stop()

    var wg sync.WaitGroup
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func(id int) {
            defer wg.Done()
            // Work here
        }(i)
    }
    wg.Wait()
}

• When each G runs
• Which P/M it runs on
• When it blocks and why
• Work stealing events

Scheduler-Friendly Code

Use Buffered Channels Wisely

go
// Can cause excessive scheduling
unbuffered := make(chan int)

// Reduces scheduling overhead
buffered := make(chan int, 100)

Batch Work

go
// WRONG: One goroutine per tiny task
for i := 0; i < 1000000; i++ {
    go process(item[i]) // Million goroutines!
}

// RIGHT: Batch into worker pools
workers := runtime.GOMAXPROCS(0)
batch := len(items) / workers
for w := 0; w < workers; w++ {
    go func(start, end int) {
        for i := start; i < end; i++ {
            process(items[i])
        }
    }(w*batch, (w+1)*batch)
}

Avoid Lock Contention

go
// WRONG: All goroutines fight for one lock
var globalMu sync.Mutex
var globalCounter int

// RIGHT: Reduce contention with sharding
type ShardedCounter struct {
    shards [16]struct {
        mu    sync.Mutex
        count int
    }
}

func (c *ShardedCounter) Inc(id int) {
    shard := &c.shards[id%16]
    shard.mu.Lock()
    shard.count++
    shard.mu.Unlock()
}

Key Scheduler Metrics

go
// Filename: scheduler_metrics.go
package main

import (
    "fmt"
    "runtime"
)

func main() {
    fmt.Println("NumCPU:", runtime.NumCPU())
    fmt.Println("GOMAXPROCS:", runtime.GOMAXPROCS(0))
    fmt.Println("NumGoroutine:", runtime.NumGoroutine())

    // More detailed stats
    var memStats runtime.MemStats
    runtime.ReadMemStats(&memStats)
    fmt.Println("Num GC:", memStats.NumGC)
}

GODEBUG Scheduler Tracing

bash
GODEBUG=schedtrace=1000 ./myprogram

SCHED 1000ms: gomaxprocs=8 idleprocs=6 threads=9 spinningthreads=1 idlethreads=2 runqueue=0 [1 0 0 0 0 0 0 0]

• gomaxprocs: Number of Ps
• idleprocs: Ps without work
• threads: Total Ms
• runqueue: Global queue size
• [1 0 0...]: Each P's local queue size

Scheduler Internals Summary

Go blog diagram 6

Common Misconceptions

What You Learned

• GMP model: Goroutines, Machines (threads), Processors
• Work stealing balances load: Idle Ps steal from busy ones
• Preemption prevents starvation: No goroutine can hog CPU
• System calls hand off P: Blocking doesn't block scheduling
• Network poller is efficient: Async I/O under the hood
• GOMAXPROCS controls parallelism: Usually defaults are fine

Your Next Steps

• Profile: Use go tool trace on your application
• Read Next: Learn about goroutine leaks and how to detect them
• Experiment: Try GODEBUG=schedtrace to see your scheduler in action