How Go's `os/signal` Package Works: A Deep Dive from First Principles

var handlers struct {
    sync.Mutex
    // Maps each channel to the set of signals it wants
    m map[chan<- os.Signal]*handler
    // Reference count: how many channels want each signal number
    ref [numSig]int64
    // Channels in the process of being stopped
    stopping []stopping
}

type handler struct {
    mask [(numSig + 31) / 32]uint32
}

func (h *handler) want(sig int) bool {
    return (h.mask[sig/32]>>uint(sig&31))&1 != 0
}

func (h *handler) set(sig int) {
    h.mask[sig/32] |= 1 << uint(sig&31)
}

func (h *handler) clear(sig int) {
    h.mask[sig/32] &^= 1 << uint(sig&31)
}

func Notify(c chan<- os.Signal, sig ...os.Signal) {
    if c == nil {
        panic("os/signal: Notify using nil channel")
    }

    handlers.Lock()
    defer handlers.Unlock()

    add := func(n int) {
        if n < 0 {
            return
        }
        h := getHandler()       // get or create handler for this channel
        if !h.want(n) {
            h.set(n)            // mark channel as interested in signal n
            if handlers.ref[n] == 0 {
                enableSignal(n) // tell the runtime to capture this signal

                // Start the background watcher goroutine — only once, ever
                watchSignalLoopOnce.Do(func() {
                    if watchSignalLoop != nil {
                        go watchSignalLoop()
                    }
                })
            }
            handlers.ref[n]++   // increment reference count
        }
    }
    // ...
}

func process(sig os.Signal) {
    n := signum(sig)
    if n < 0 {
        return
    }

    handlers.Lock()
    defer handlers.Unlock()

    for c, h := range handlers.m {
        if h.want(n) {
            select {
            case c <- sig:
            default: // drop if buffer is full — never block the dispatcher
            }
        }
    }
}

func Stop(c chan<- os.Signal) {
    handlers.Lock()

    h := handlers.m[c]
    if h == nil {
        handlers.Unlock()
        return
    }
    delete(handlers.m, c)
    // ... decrement ref counts, disable signals if ref hits 0 ...

    // Keep c in the stopping list so any in-flight signal can still be delivered
    handlers.stopping = append(handlers.stopping, stopping{c, h})
    handlers.Unlock()

    // Block until the runtime confirms no signals are mid-delivery
    signalWaitUntilIdle()

    handlers.Lock()
    // Now safe to fully remove c
    for i, s := range handlers.stopping {
        if s.c == c {
            handlers.stopping = slices.Delete(handlers.stopping, i, i+1)
            break
        }
    }
    handlers.Unlock()
}

// Defined by the runtime package — these cross the Go/runtime boundary
func signal_disable(uint32)
func signal_enable(uint32)
func signal_ignore(uint32)
func signal_ignored(uint32) bool
func signal_recv() uint32   // blocks until a signal arrives

func loop() {
    for {
        process(syscall.Signal(signal_recv()))
    }
}

func init() {
    watchSignalLoop = loop
}

func NotifyContext(parent context.Context, signals ...os.Signal) (ctx context.Context, stop context.CancelFunc) {
    ctx, cancel := context.WithCancelCause(parent)
    c := &signalCtx{
        Context: ctx,
        cancel:  cancel,
        signals: signals,
    }
    c.ch = make(chan os.Signal, 1)
    Notify(c.ch, c.signals...)

    if ctx.Err() == nil {
        go func() {
            select {
            case s := <-c.ch:
                // Cancel context with a descriptive error message
                c.cancel(signalError(s.String() + " signal received"))
            case <-c.Done():
            }
        }()
    }
    return c, c.stop
}

package main

import (
    "fmt"
    "os"
    "os/signal"
    "syscall"
    "time"
)

func main() {
    fmt.Printf("Server started (PID: %d). Press Ctrl+C to stop.\n", os.Getpid())

    // Always use a buffered channel — a buffer of 1 is enough for a single
    // signal type. It queues one signal even if your goroutine isn't ready yet.
    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
    defer signal.Stop(sigChan)

    go doWork()

    sig := <-sigChan
    fmt.Printf("\nReceived: %s — running cleanup...\n", sig)
    cleanup()
}

func doWork() {
    for i := 1; ; i++ {
        fmt.Printf("Working... tick %d\n", i)
        time.Sleep(1 * time.Second)
    }
}

func cleanup() {
    fmt.Println("Flushing buffers and closing connections.")
    time.Sleep(200 * time.Millisecond)
    fmt.Println("Done.")
}

signal.Notify(sigChan,
    syscall.SIGINT,   // Ctrl+C       → shutdown
    syscall.SIGTERM,  // kill         → shutdown
    syscall.SIGHUP,   // hangup       → reload config
    syscall.SIGUSR1,  // user-defined → dump state
)

for {
    switch sig := <-sigChan; sig {
    case syscall.SIGHUP:
        fmt.Println("Reloading configuration...")
        reloadConfig()
    case syscall.SIGUSR1:
        fmt.Println("Dumping internal state...")
        dumpState()
    case syscall.SIGINT, syscall.SIGTERM:
        fmt.Printf("Shutdown signal (%s) received.\n", sig)
        return
    }
}

ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()

// Pass ctx to your HTTP server, workers, database clients, etc.
// When Ctrl+C is pressed, ctx.Done() closes and everything shuts down cleanly.
if err := server.Shutdown(ctx); err != nil {
    log.Printf("shutdown error: %v", err)
}