Signals

Signals as channel receives

A signal is an asynchronous notification from the kernel. Handling async events safely is hard in most languages (you’re in a restricted handler context). Go’s trick: turn signals into channel sends with os/signal, so you handle them in ordinary code.

graph LR
OS["OS: SIGTERM"] -->|"signal.Notify"| CH["chan os.Signal (buffered)"]
CH --> CODE["your code: <-ch → clean up → exit"]

This runs here and delivers a real signal — the goroutine sends our own process SIGTERM via syscall.Kill (the kill(2) syscall), exactly as kill <pid> or an orchestrator would. (A select timeout guards against any sandbox that blocks self-signalling.)

package main

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

func main() {
// Relay SIGINT/SIGTERM onto a buffered channel.
sigs := make(chan os.Signal, 1)
signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)

// Deliver a REAL signal to ourselves — the same kill(2) syscall that
// Ctrl-C, 'kill <pid>', or Kubernetes uses.
go func() {
	time.Sleep(50 * time.Millisecond)
	syscall.Kill(syscall.Getpid(), syscall.SIGTERM)
}()

fmt.Println("server running; waiting for shutdown signal…")
select {
case sig := <-sigs: // block until the signal arrives
	fmt.Printf("received %v — shutting down gracefully\n", sig)
	// Real cleanup goes here: stop accepting work, drain, flush, close.
	fmt.Println("drained connections, flushed logs — bye")
case <-time.After(2 * time.Second):
	fmt.Println("(no signal delivered — sandbox restriction)")
}
}

The handler logic — receive on the channel, then clean up — is identical whether the signal comes from syscall.Kill, a terminal Ctrl-C, or an orchestrator’s SIGTERM.

Graceful shutdown, the modern way

In real services you rarely manage the channel yourself — signal.NotifyContext gives you a context that cancels on the first signal, which you hand straight to your server’s Shutdown:

func main() {
	// ctx is cancelled when SIGINT or SIGTERM arrives.
	ctx, stop := signal.NotifyContext(context.Background(),
		syscall.SIGINT, syscall.SIGTERM)
	defer stop()

	srv := &http.Server{Addr: ":8080", Handler: mux}
	go srv.ListenAndServe()

	<-ctx.Done() // wait for the signal
	log.Println("shutting down…")

	// Give in-flight requests up to 10s to finish, then force.
	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()
	srv.Shutdown(shutdownCtx) // stops accepting, drains existing conns
}

That’s the canonical pattern: catch the signal → stop accepting new work → drain in-flight work with a deadline → exit. It pairs directly with context cancellation.

Common signals

You can also ignore a signal (signal.Ignore) or stop catching one (signal.Reset/signal.Stop), e.g. to restore default Ctrl-C behavior after a critical section.

See also

• processes & exec — sending signals to child processes.
• scheduling & watching — the other “react to events” mechanism.
• context & cancellation (patterns) — what NotifyContext plugs into.
• graceful shutdown (web) — applying this to an HTTP server.

Next: programs that wake on a timer or a file change — scheduling & watching.

Related topics