Signals on Opensource internals

How Go's CPU Profiler Works: SIGPROF, the Signal Stack and 100 Hz Sampling

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: Go’s CPU profiler is an interval timer plus a signal handler. runtime/pprof.StartCPUProfile hardcodes 100 Hz, the runtime arms setitimer(ITIMER_PROF) with that period, and every time the timer fires the kernel raises SIGPROF on some thread. The handler runs on a dedicated 32 KB signal stack, unwinds the interrupted goroutine’s stack in place, and appends the PCs to a lock-free ring buffer. A separate goroutine drains that buffer and writes a protobuf profile.

Profiling a Go program is easy: call pprof.StartCPUProfile(f) and walk away. What that call actually sets up is a POSIX interval timer, a kernel signal, a signal handler running on a stack the runtime reserves for exactly this purpose, a stack unwinder that has to work while the world is half-frozen, and a lock-free ring buffer shared between a signal handler and an ordinary goroutine.

Every one of those pieces is in the Go tree, and every one of them is a little unusual. Let’s walk through them, based on the Go 1.28 development tree.

The 100 Hz decision

The frequency is not configurable through the public API, and the reason is written down in runtime/pprof:

 go
 
 
// src/runtime/pprof/pprof.go:885
func StartCPUProfile(w io.Writer) error {
	// The runtime routines allow a variable profiling rate,
	// but in practice operating systems cannot trigger signals
	// at more than about 500 Hz, and our processing of the
	// signal is not cheap (mostly getting the stack trace).
	// 100 Hz is a reasonable choice: it is frequent enough to
	// produce useful data, rare enough not to bog down the
	// system, and a nice round number to make it easy to
	// convert sample counts to seconds. Instead of requiring
	// each client to specify the frequency, we hard code it.
	const hz = 100

	cpu.Lock()
	defer cpu.Unlock()
	if cpu.done == nil {
		cpu.done = make(chan bool)
	}
	// Double-check.
	if cpu.profiling {
		return fmt.Errorf("cpu profiling already in use")
	}
	cpu.profiling = true
	pprof_setCPUProfileRate(hz)
	go profileWriter(w)
	return nil
}

Two things to notice. First, 100 is hardcoded — runtime.SetCPUProfileRate exists and does let you pick a rate, but runtime/pprof refuses to use it. Second, the comment tells you the real cost model: the expensive part is not the signal, it is the stack unwinding that follows it. That single sentence explains most of the design decisions below.

profileWriter is the other half of the public API, and it is the goroutine that drains the samples and turns them into a profile:

 go
 
 
// src/runtime/pprof/pprof.go:919
func profileWriter(w io.Writer) {
	b := newProfileBuilder(w)
	var err error
	for {
		if runtime.GOOS == "darwin" || runtime.GOOS == "ios" {
			// see runtime_pprof_readProfile
			time.Sleep(100 * time.Millisecond)
		}
		data, tags, eof := readProfile()
		if e := b.addCPUData(data, tags); e != nil && err == nil {
			err = e
		}
		if eof {
			break
		}
	}
	if err != nil {
		// The runtime should never produce an invalid or truncated profile.
		// It drops records that can't fit into its log buffers.
		panic("runtime/pprof: converting profile: " + err.Error())
	}
	b.build()
	cpu.done <- true
}

The signal handler and this goroutine never touch the same data structure directly. They meet in profBuf, a ring buffer designed for exactly one reader and one writer.

Arming the timer

pprof_setCPUProfileRate is a go:linknamed entry point into the runtime, which lands in setCPUProfileRate in src/runtime/cpuprof.go. That function creates the ring buffer, writes one special record into it (the sampling rate), and then calls setcpuprofilerate, which eventually reaches the OS-specific timer setup:

 go
 
 
// src/runtime/signal_unix.go:276
// setProcessCPUProfilerTimer is called when the profiling timer changes.
// It is called with prof.signalLock held. hz is the new timer, and is 0 if
// profiling is being disabled. Enable or disable the signal as
// required for -buildmode=c-archive.
func setProcessCPUProfilerTimer(hz int32) {
	if hz != 0 {
		// Enable the Go signal handler if not enabled.
		if atomic.Cas(&handlingSig[_SIGPROF], 0, 1) {
			h := getsig(_SIGPROF)
			// If no signal handler was installed before, then we record
			// _SIG_IGN here. When we turn off profiling (below) we'll start
			// ignoring SIGPROF signals. We do this, rather than change
			// to SIG_DFL, because there may be a pending SIGPROF
			// signal that has not yet been delivered to some other thread.
			// If we change to SIG_DFL when turning off profiling, the
			// program will crash when that SIGPROF is delivered. We assume
			// that programs that use profiling don't want to crash on a
			// stray SIGPROF. See issue 19320.
			// We do the change here instead of when turning off profiling,
			// because there we may race with a signal handler running
			// concurrently, in particular, sigfwdgo may observe _SIG_DFL and
			// die. See issue 43828.
			if h == _SIG_DFL {
				h = _SIG_IGN
			}
			atomic.Storeuintptr(&fwdSig[_SIGPROF], h)
			setsig(_SIGPROF, abi.FuncPCABIInternal(sighandler))
		}

		var it itimerval
		it.it_interval.tv_sec = 0
		it.it_interval.set_usec(1000000 / hz)
		it.it_value = it.it_interval
		setitimer(_ITIMER_PROF, &it, nil)
	} else {
		setitimer(_ITIMER_PROF, &itimerval{}, nil)

setitimer(ITIMER_PROF) is the crux. ITIMER_PROF counts CPU time consumed by the process (user time plus system time), not wall-clock time. So a program that spends its life blocked on a socket does not accumulate profiling ticks; a program burning CPU in a tight loop does. The timer is process-wide, and when it expires the kernel picks a thread that does not have the signal blocked and raises SIGPROF there.

That “picks a thread” is why the profiler is biased the way it is. The sample is attributed to whatever goroutine happened to be running on the thread that won the race to receive the signal.

The _SIG_IGN dance above is a lovely piece of defensive engineering: turning the timer off does not cancel an already-pending signal, so switching the handler back to SIG_DFL would let that pending signal kill the program.

The signal stack

Signals are delivered on the thread’s normal stack by default, which is a disaster for a profiler: the interrupted goroutine’s stack is already in use, and the handler needs room to walk it. Go gives every M a dedicated signal stack.

 go
 
 
// src/runtime/os_linux.go:385
// Called to initialize a new m (including the bootstrap m).
// Called on the parent thread (main thread in case of bootstrap), can allocate memory.
func mpreinit(mp *m) {
	mp.gsignal = malg(32 * 1024) // Linux wants >= 2K
	mp.gsignal.m = mp
}

And it installs it as the thread’s alternate signal stack, with SA_ONSTACK:

 go
 
 
// src/runtime/os_linux.go:478
func setsig(i uint32, fn uintptr) {
	var sa sigactiont
	sa.sa_flags = _SA_SIGINFO | _SA_ONSTACK | _SA_RESTORER | _SA_RESTART
	sigfillset(&sa.sa_mask)
	// Although Linux manpage says "sa_restorer element is obsolete and
	// should not be used". x86_64 kernel requires it. Only use it on
	// x86. Note that on 386 this is cleared when using the C sigaction
	// function via cgo; see fixSigactionForCgo.
	if GOARCH == "386" || GOARCH == "amd64" {
		sa.sa_restorer = abi.FuncPCABI0(sigreturn__sigaction)
	}
	if fn == abi.FuncPCABIInternal(sighandler) { // abi.FuncPCABIInternal(sighandler) matches the callers in signal_unix.go
		if iscgo {
			fn = abi.FuncPCABI0(cgoSigtramp)
		} else {
			fn = abi.FuncPCABI0(sigtramp)
		}
	}
	sa.sa_handler = fn
	sigaction(i, &sa, nil)
}

Note sigfillset(&sa.sa_mask): while the handler runs, every signal is blocked. That is why the runtime can rely on a single signal at a time — no reentrancy into the profiler from another signal — and it is also why the profiler’s own locking is a simple compare-and-swap rather than a mutex.

Each thread gets its own 32 KB gsignal goroutine stack, set up when the M is initialised:

 go
 
 
// src/runtime/signal_unix.go:1329
func minitSignals() {
	minitSignalStack()
	minitSignalMask()
}

// minitSignalStack is called when initializing a new m to set the
// alternate signal stack. If the alternate signal stack is not set
// for the thread (the normal case) then set the alternate signal
// stack to the gsignal stack. If the alternate signal stack is set
// for the thread (the case when a non-Go thread sets the alternate
// signal stack and then calls a Go function) then set the gsignal
// stack to the alternate signal stack. We also set the alternate
// signal stack to the gsignal stack if cgo is not used (regardless
// of whether it is already set). Record which choice was made in
// newSigstack, so that it can be undone in unminit.
func minitSignalStack() {
	mp := getg().m
	var st stackt
	sigaltstack(nil, &st)
	if st.ss_flags&_SS_DISABLE != 0 || !iscgo {
		signalstack(&mp.gsignal.stack)
		mp.newSigstack = true
	} else {
		setGsignalStack(&st, &mp.goSigStack)
		mp.newSigstack = false
	}
}

The handler: identify the goroutine, unwind the stack

The handler itself is sighandler, which handles every signal Go cares about. SIGPROF gets an early return:

 go
 
 
// src/runtime/signal_unix.go:674
	if sig == _SIGPROF {
		// Some platforms (Linux) have per-thread timers, which we use in
		// combination with the process-wide timer. Avoid double-counting.
		if !delayedSignal && validSIGPROF(mp, c) {
			sigprof(c.sigpc(), c.sigsp(), c.siglr(), gp, mp)
		}
		return
	}

gp is the G that was running when the signal arrived; mp is the M it was running on. That is the “per-thread goroutine identification”: the sample is attributed to mp.curg, and the goroutine’s pprof labels are attached to the sample as a tag pointer.

sigprof is where the stack is unwound:

 go
 
 
// src/runtime/proc.go:5801
// Called if we receive a SIGPROF signal.
// Called by the signal handler, may run during STW.
//
//go:nowritebarrierrec
func sigprof(pc, sp, lr uintptr, gp *g, mp *m) {
	if prof.hz.Load() == 0 {
		return
	}

	// If mp.profilehz is 0, then profiling is not enabled for this thread.
	// We must check this to avoid a deadlock between setcpuprofilerate
	// and the call to cpuprof.add, below.
	if mp != nil && mp.profilehz == 0 {
		return
	}
	...
	// Profiling runs concurrently with GC, so it must not allocate.
	// Set a trap in case the code does allocate.
	// Note that on windows, one thread takes profiles of all the
	// other threads, so mp is usually not getg().m.
	// In fact mp may not even be stopped.
	// See golang.org/issue/17165.
	getg().m.mallocing++

	var u unwinder
	var stk [maxCPUProfStack]uintptr
	n := 0
	...
	} else {
		u.initAt(pc, sp, lr, gp, unwindSilentErrors|unwindTrap|unwindJumpStack)
	}
	n += tracebackPCs(&u, 0, stk[n:])

Here is a genuinely surprising fact about modern Go: gentraceback is gone. It used to be the workhorse, and every blog post about Go stack unwinding still describes it. In the Go 1.28 tree there is no gentraceback function at all. It has been replaced by the unwinder type, an explicit iterator:

 go
 
 
// src/runtime/traceback.go:84
// An unwinder iterates the physical stack frames of a Go sack.
//
// Typical use of an unwinder looks like:
//
//	var u unwinder
//	for u.init(gp, 0); u.valid(); u.next() {
//		// ... use frame info in u ...
//	}
//
// Implementation note: This is carefully structured to be pointer-free because
// tracebacks happen in places that disallow write barriers (e.g., signals).
// Even if this is stack-allocated, its pointer-receiver methods don't know that
// their receiver is on the stack, so they still emit write barriers. Here we
// address that by carefully avoiding any pointers in this type. Another
// approach would be to split this into a mutable part that's passed by pointer
// but contains no pointers itself and an immutable part that's passed and
// returned by value and can contain pointers. We could potentially hide that
// we're doing that in trivial methods that are inlined into the caller that has
// the stack allocation, but that's fragile.
type unwinder struct {
	// frame is the current physical stack frame, or all 0s if
	// there is no frame.
	frame stkframe

The pointer-free design is not cosmetic. The signal handler runs with write barriers disabled (the GC may be in the middle of a stop-the-world), and the unwinder is deliberately built so it cannot allocate or trigger a barrier.

The result of the unwind is a flat array of return PCs, up to 64 frames:

 go
 
 
// src/runtime/traceback.go:645
func tracebackPCs(u *unwinder, skip int, pcBuf []uintptr) int {
	var cgoBuf [32]uintptr
	n := 0
	for ; n < len(pcBuf) && u.valid(); u.next() {
		f := u.frame.fn
		cgoN := u.cgoCallers(cgoBuf[:])

		// TODO: Why does &u.cache cause u to escape? (Same in traceback2)
		for iu, uf := newInlineUnwinder(f, u.symPC()); n < len(pcBuf) && uf.valid(); uf = iu.next(uf) {
			sf := iu.srcFunc(uf)
			if sf.funcID == abi.FuncIDWrapper && elideWrapperCalling(u.calleeFuncID) {
				// ignore wrappers
			} else if skip > 0 {
				skip--
			} else {
				// Callers expect the pc buffer to contain return addresses
				// and do the -1 themselves, so we add 1 to the call pc to
				// create a "return pc". Since there is no actual call, here
				// "return pc" just means a pc you subtract 1 from to get
				// the pc of the "call". The actual no-op we insert may or
				// may not be 1 byte.
				pcBuf[n] = uf.pc + 1
				n++
			}
			u.calleeFuncID = sf.funcID
		}

If the unwind fails — the sample landed in a JIT blob, or in C code with no Go frames — the profiler falls back to a synthetic two-frame stack of System or GC plus _ExternalCode. Those fake frames show up in go tool pprof output as runtime._System and runtime._ExternalCode, and they are a reliable signal that the time was spent outside Go.

Writing to the ring buffer

The sample is handed to cpuprof.add, which does the least it can get away with:

 go
 
 
// src/runtime/cpuprof.go:108
// add adds the stack trace to the profile.
// It is called from signal handlers and other limited environments
// and cannot allocate memory or acquire locks that might be
// held at the time of the signal, nor can it use substantial amounts
// of stack.
//
//go:nowritebarrierrec
func (p *cpuProfile) add(tagPtr *unsafe.Pointer, stk []uintptr) {
	// Simple cas-lock to coordinate with setcpuprofilerate.
	for !prof.signalLock.CompareAndSwap(0, 1) {
		// TODO: Is it safe to osyield here? https://go.dev/issue/52672
		osyield()
	}

	if prof.hz.Load() != 0 { // implies cpuprof.log != nil
		if p.numExtra > 0 || p.lostExtra > 0 || p.lostAtomic > 0 {
			p.addExtra()
		}
		hdr := [1]uint64{1}
		// Note: write "knows" that the argument is &gp.labels,
		// because otherwise its write barrier behavior may not
		// be correct. See the long comment there before
		// changing the argument here.
		cpuprof.log.write(tagPtr, nanotime(), hdr[:], stk)
	}

	prof.signalLock.Store(0)
}

No allocation, no mutex — a compare-and-swap on prof.signalLock and a copy into a preallocated ring. The ring is profBuf, and its record layout is deliberately trivial:

 go
 
 
// src/runtime/profbuf.go:358
	// Main record.
	// It has to fit in a contiguous section of the slice, so if it doesn't fit at the end,
	// leave a rewind marker (0) and start over at the beginning of the slice.
	wd := int(bw.dataCount() % uint32(len(b.data)))
	nd := countSub(br.dataCount(), bw.dataCount()) + len(b.data)
	skip := 0
	if wd+2+int(b.hdrsize)+len(stk) > len(b.data) {
		b.data[wd] = 0
		skip = len(b.data) - wd
		nd -= skip
		wd = 0
	}
	data := b.data[wd:]
	data[0] = uint64(2 + b.hdrsize + uintptr(len(stk))) // length
	data[1] = uint64(now) // time stamp
	// header, zero-padded
	i := copy(data[2:2+b.hdrsize], hdr)
	clear(data[2+i : 2+b.hdrsize])
	for i, pc := range stk {
		data[2+b.hdrsize+uintptr(i)] = uint64(pc)
	}

Each record is: a length word, a timestamp, a one-word header (the sample count), and the PCs. The buffer is sized in the source with a very human comment:

 go
 
 
// src/runtime/cpuprof.go:21
const (
	maxCPUProfStack = 64

	// profBufWordCount is the size of the CPU profile buffer's storage for the
	// header and stack of each sample, measured in 64-bit words. Every sample
	// has a required header of two words. With a small additional header (a
	// word or two) and stacks at the profiler's maximum length of 64 frames,
	// that capacity can support 1900 samples or 19 thread-seconds at a 100 Hz
	// sample rate, at a cost of 1 MiB.
	profBufWordCount = 1 << 17

19 thread-seconds of samples in a megabyte. If the reader goroutine falls behind and the ring fills up, samples are dropped and the drop count is recorded as a special “overflow” record rather than silently lost.

The three-word header

The very first record the runtime writes is not a sample — it is the sampling rate, and the reader uses it to turn sample counts into nanoseconds:

 go
 
 
// src/runtime/cpuprof.go:94
		cpuprof.on = true
		cpuprof.log = newProfBuf(1, profBufWordCount, profBufTagCount)
		hdr := [1]uint64{uint64(hz)}
		cpuprof.log.write(nil, nanotime(), hdr[:], nil)
		setcpuprofilerate(int32(hz))

That record has a zero-length stack, so it occupies three words: length (3), timestamp, and the frequency. The reader checks for exactly that shape:

 go
 
 
// src/runtime/pprof/proto.go:278
func (b *profileBuilder) addCPUData(data []uint64, tags []unsafe.Pointer) error {
	if !b.havePeriod {
		// first record is period
		if len(data) < 3 {
			return fmt.Errorf("truncated profile")
		}
		if data[0] != 3 || data[2] == 0 {
			return fmt.Errorf("malformed profile")
		}
		// data[2] is sampling rate in Hz. Convert to sampling
		// period in nanoseconds.
		b.period = 1e9 / int64(data[2])
		b.havePeriod = true
		data = data[3:]
		// Consume tag slot. Note that there isn't a meaningful tag
		// value for this record.
		tags = tags[1:]
	}

The same routine also decodes the overflow records, which is how a dropped sample shows up in the profile rather than vanishing:

 go
 
 
// src/runtime/pprof/proto.go:322
		count := data[2]
		stk := data[3:data[0]]
		data = data[data[0]:]
		tag := tags[0]
		tags = tags[1:]

		if count == 0 && len(stk) == 1 {
			// overflow record
			count = uint64(stk[0])
			stk = []uint64{
				// gentraceback guarantees that PCs in the
				// stack can be unconditionally decremented and
				// still be valid, so we must do the same.
				uint64(abi.FuncPCABIInternal(lostProfileEvent) + 1),
			}
		}
		b.m.lookup(stk, tag).count += int64(count)

(The comment mentioning gentraceback is a leftover from before the unwinder rewrite — the property it describes still holds.)

The builder then deduplicates identical stacks on the fly and finally emits the protobuf with two sample types, samples/count and cpu/nanoseconds.

The memory profile is a different animal

The memory profile does not use signals at all. It samples allocations, at a rate set by a global:

 go
 
 
// src/runtime/mprof.go:856
// MemProfileRate controls the fraction of memory allocations
// that are recorded and reported in the memory profile.
// The profiler aims to sample an average of
// one allocation per MemProfileRate bytes allocated.
//
// To include every allocated block in the profile, set MemProfileRate to 1.
// To turn off profiling entirely, set MemProfileRate to 0.
//
// The tools that process the memory profiles assume that the
// profile rate is constant across the lifetime of the program
// and equal to the current value. Programs that change the
// memory profiling rate should do so just once, as early as
// possible in the execution of the program (for example,
// at the beginning of main).
var MemProfileRate int = 512 * 1024

512 KB, by default. The decision of which allocation to sample is made with a counter kept in the mcache — the per-P allocation cache — and the next sample point is drawn from an exponential distribution so that the sampling is Poissonian rather than periodic:

 go
 
 
// src/runtime/malloc.go:2236
// nextSample returns the next sampling point for heap profiling. The goal is
// to sample allocations on average every MemProfileRate bytes, but with a
// completely random distribution over the allocation timeline; this
// corresponds to a Poisson process with parameter MemProfileRate. In Poisson
// processes, the distance between two samples follows the exponential
// distribution (exp(MemProfileRate)), so the best return value is a random
// number taken from an exponential distribution whose mean is MemProfileRate.
func nextSample() int64 {
	if MemProfileRate == 0 {
		// Basically never sample.
		return math.MaxInt64
	}
	if MemProfileRate == 1 {
		// Sample immediately.
		return 0
	}
	return int64(fastexprand(MemProfileRate))
}

The counter lives on the mcache, and the check happens on every allocation:

 go
 
 
// src/runtime/malloc.go:1449
	c.nextSample -= int64(size)
	if c.nextSample < 0 || MemProfileRate != c.memProfRate {
		profilealloc(mp, x, size)
	}

So: the CPU profile samples time using a signal; the memory profile samples bytes using a counter in the allocator cache. Different mechanisms, different biases. The memory profile counts the sampled allocation as if it represented MemProfileRate bytes, which is why pprof scales it up — a 4 KB allocation sampled at 512 KB per sample is reported as 512 KB.

Why CPU-bound goroutines dominate

Because ITIMER_PROF counts CPU time, a goroutine only gets sampled when it is actually on the CPU. A goroutine blocked on a channel, sleeping on a timer, or waiting on a mutex is invisible to the CPU profiler no matter how important it is. The profile answers “where did the CPU time go”, not “where did the program spend its time”.

That is the correct answer for a CPU profiler, but it means a program dominated by I/O will produce a profile full of runtime._System and runtime._ExternalCode frames and nothing else. For “where is my time going”, you want the execution tracer or the block profile instead.

Two more biases worth knowing:

Short goroutines are undersampled. At 100 Hz, a goroutine needs to burn roughly 10 ms of CPU to have a decent chance of appearing at all.
The signal lands on an arbitrary thread. The kernel picks a thread that does not block SIGPROF, so the sample is a snapshot of that thread’s current goroutine. This is unbiased in aggregate, but it means individual samples are attributed to a goroutine that was merely running, not necessarily the one that consumed the CPU time.

Trade-offs

What sampling buys you: near-zero steady-state overhead. The timer fires 100 times a second, each firing costs one signal delivery plus one stack unwind, and nothing else in the program changes.

What it costs:

Statistical error. A short profile is a small sample. 100 samples is 1 second of CPU time; the standard error on a 1% line is roughly 10% relative.
The unwinder is the expensive part. The runtime comment says so outright: “our processing of the signal is not cheap (mostly getting the stack trace)”.
Signal-handler constraints. The handler cannot allocate, cannot take a mutex, and cannot grow the stack. The whole unwinder design is shaped by that.
Dropped samples. If the reader goroutine cannot keep up, samples are dropped and reported as an overflow record rather than blocking the signal handler.
Frames are lost at 64. maxCPUProfStack is 64; deeper stacks are truncated, and the truncated frame is a plain function name.

Caveats

SIGPROF is a normal signal. If your program calls os/signal.Notify(c, syscall.SIGPROF), it will fight the profiler for the signal. On Unix, sigenable explicitly refuses to touch SIGPROF:

 go
 
 
// src/runtime/signal_unix.go:195
	// SIGPROF is handled specially for profiling.
	if sig == _SIGPROF {
		return
	}

c-archive and c-shared builds are different. StartCPUProfile documents that it does not work by default there, because SIGPROF goes to the host program’s handler rather than Go’s.

Linux has per-thread timers. The kernel’s timer_create timers show up as _SI_TIMER signal codes while setitimer produces _SI_KERNEL, and validSIGPROF uses that to avoid counting the same CPU time twice.

Darwin cannot block in the reader. runtime_pprof_readProfile uses a non-blocking read on Darwin and iOS, and profileWriter sleeps 100 ms between reads, because notetsleepg is not safe in a signal handler there.

Profiles are not comparable across runs unless the rate is the same — which it is, since 100 Hz is hardcoded — but they are not comparable if the program was interrupted differently or if samples were dropped.

Wrapping up

The one thing to remember: the CPU profiler is a 100 Hz setitimer(ITIMER_PROF) plus a SIGPROF handler that runs on a per-M 32 KB signal stack, unwinds the interrupted goroutine with a pointer-free unwinder, and copies the PCs into a lock-free ring buffer that a separate goroutine turns into a profile.

The part people get wrong: ITIMER_PROF counts CPU time, so the profile shows you where the CPU went, not where the wall-clock went. A program that is mostly blocked will show almost nothing, and the samples it does show will be attributed to runtime._System.

What to go do about it: turn on a CPU profile and an execution trace at the same time. The profile tells you which function is hot; the trace tells you why the goroutine that called it was asleep. And if the profile is suspiciously empty, check for a SIGPROF handler installed by a library before you go looking for a performance bug.

How Go Handles Signals and Context Cancellation Without Losing Signals

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: Go installs its own handler for every signal it cares about, and because a signal handler cannot block, allocate or take a lock, it does almost nothing: it sets a bit in a global bitmask and wakes one dedicated goroutine. That goroutine turns bits back into signals and pushes them onto your channels. Context cancellation is a different mechanism entirely — a tree of cancelCtx nodes where cancelling a parent cancels its children.

Two mechanisms in the Go runtime look related and are not. Signal handling is about getting a signal from the kernel into a Go channel without losing it. Context cancellation is about propagating a “stop” through a tree of operations. They meet in exactly one place: signal.NotifyContext, which wires a signal to a context.

Let’s look at both, in the Go 1.28 development tree.

The table of signals

The runtime has a table, one entry per signal number, describing what to do with each one:

 go
 
 
// src/runtime/signal_unix.go:17
// sigTabT is the type of an entry in the global sigtable array.
// sigtable is inherently system dependent, and appears in OS-specific files,
// but sigTabT is the same for all Unixy systems.
// The sigtable array is indexed by a system signal number to get the flags
// and printable name of each signal.
type sigTabT struct {
	flags int32
	name string
}

and on Linux:

 go
 
 
// src/runtime/sigtab_linux_generic.go:9
var sigtable = [...]sigTabT{
	/* 0 */ {0, "SIGNONE: no trap"},
	/* 1 */ {_SigNotify + _SigKill, "SIGHUP: terminal line hangup"},
	/* 2 */ {_SigNotify + _SigKill, "SIGINT: interrupt"},
	/* 3 */ {_SigNotify + _SigThrow, "SIGQUIT: quit"},
	/* 4 */ {_SigThrow + _SigUnblock, "SIGILL: illegal instruction"},
	/* 5 */ {_SigThrow + _SigUnblock, "SIGTRAP: trace trap"},
	/* 6 */ {_SigNotify + _SigThrow, "SIGABRT: abort"},
	/* 7 */ {_SigPanic + _SigUnblock, "SIGBUS: bus error"},
	/* 8 */ {_SigPanic + _SigUnblock, "SIGFPE: floating-point exception"},
	/* 9 */ {0, "SIGKILL: kill"},
	/* 10 */ {_SigNotify, "SIGUSR1: user-defined signal 1"},
	/* 11 */ {_SigPanic + _SigUnblock, "SIGSEGV: segmentation violation"},
	/* 12 */ {_SigNotify, "SIGUSR2: user-defined signal 2"},
	/* 13 */ {_SigNotify, "SIGPIPE: write to broken pipe"},
	/* 14 */ {_SigNotify, "SIGALRM: alarm clock"},
	/* 15 */ {_SigNotify + _SigKill, "SIGTERM: termination"},
	...
	/* 27 */ {_SigNotify + _SigUnblock, "SIGPROF: profiling alarm clock"},
	...
}

The flags are the policy. _SigNotify means “this signal can be caught by os/signal”. _SigThrow means “turn it into a Go panic”. _SigPanic means “panic if it happens in Go code, but die if it happens in C code”. _SigKill means “the default action is to kill the process”. _SigUnblock means “never block this signal in the mask” — those are the synchronous signals (SIGSEGV, SIGBUS, SIGFPE, SIGILL) that must be delivered immediately so they can become panics.

The flags also determine which signals are allowed to be blocked by the signal mask:

 go
 
 
// src/runtime/signal_unix.go:1394
// blockableSig reports whether sig may be blocked by the signal mask.
// We never want to block the signals marked _SigUnblock;
// these are the synchronous signals that turn into a Go panic.
// We never want to block the preemption signal if it is being used.
// In a Go program--not a c-archive/c-shared--we never want to block
// the signals marked _SigKill or _SigThrow, as otherwise it's possible
// for all running threads to block them and delay their delivery until
// we start a new thread. When linked into a C program we let the C code
// decide on the disposition of those signals.
func blockableSig(sig uint32) bool {
	flags := sigtable[sig].flags
	if flags&_SigUnblock != 0 {
		return false
	}
	if sig == sigPreempt && preemptMSupported && debug.asyncpreemptoff == 0 {
		return false
	}
	if isarchive || islibrary {
		return true
	}
	return flags&(_SigKill|_SigThrow) == 0
}

Installing the handler

At startup, the runtime walks the table and installs its own handler for every signal it wants:

 go
 
 
// src/runtime/signal_unix.go:110
// Initialize signals.
// Called by libpreinit so runtime may not be initialized.
//
//go:nosplit
//go:nowritebarrierrec
func initsig(preinit bool) {
	if !preinit {
		// It's now OK for signal handlers to run.
		signalsOK = true
	}

	// For c-archive/c-shared this is called by libpreinit with
	// preinit == true.
	if (isarchive || islibrary) && !preinit {
		return
	}

	for i := uint32(0); i < _NSIG; i++ {
		t := &sigtable[i]
		if t.flags == 0 || t.flags&_SigDefault != 0 {
			continue
		}

		// We don't need to use atomic operations here because
		// there shouldn't be any other goroutines running yet.
		fwdSig[i] = getsig(i)

		if !sigInstallGoHandler(i) {
			// Even if we are not installing a signal handler,
			// set SA_ONSTACK if necessary.
			if fwdSig[i] != _SIG_DFL && fwdSig[i] != _SIG_IGN {
				setsigstack(i)
			} else if fwdSig[i] == _SIG_IGN {
				sigInitIgnored(i)
			}
			continue
		}

		handlingSig[i] = 1
		setsig(i, abi.FuncPCABIInternal(sighandler))
	}
}

The handler that gets installed is sighandler, and the sigaction it uses is configured with SA_ONSTACK (run on the alternate signal stack) and with every signal blocked during the handler:

 go
 
 
// src/runtime/os_linux.go:478
func setsig(i uint32, fn uintptr) {
	var sa sigactiont
	sa.sa_flags = _SA_SIGINFO | _SA_ONSTACK | _SA_RESTORER | _SA_RESTART
	sigfillset(&sa.sa_mask)
	...
	sa.sa_handler = fn
	sigaction(i, &sa, nil)
}

fwdSig[i] remembers whatever handler was installed before Go started, so that Go can forward the signal to the original handler when Go does not want it — for instance when the signal arrives on a thread that is not running Go code.

Where a signal lands

Here is the rule that surprises people: the kernel delivers a process-directed signal to an arbitrary thread that does not have that signal blocked. Not “the main thread”. Not “the thread that sent it”. Any thread whose signal mask allows it.

Because signal masks are per-thread, “does this thread accept the signal” is a per-thread question, and the answer changes over time as threads come and go. Go’s answer to “what if no thread will take it” is to keep one dedicated thread whose mask it manages precisely:

 go
 
 
// src/runtime/signal_unix.go:1076
// ensureSigM starts one global, sleeping thread to make sure at least one thread
// is available to catch signals enabled for os/signal.
func ensureSigM() {
	if maskUpdatedChan != nil {
		return
	}
	maskUpdatedChan = make(chan struct{})
	disableSigChan = make(chan uint32)
	enableSigChan = make(chan uint32)
	go func() {
		// Signal masks are per-thread, so make sure this goroutine stays on one
		// thread.
		LockOSThread()
		defer UnlockOSThread()
		// The sigBlocked mask contains the signals not active for os/signal,
		// initially all signals except the essential. When signal.Notify()/Stop is called,
		// sigenable/sigdisable in turn notify this thread to update its signal
		// mask accordingly.
		sigBlocked := sigset_all
		for i := range sigtable {
			if !blockableSig(uint32(i)) {
				sigdelset(&sigBlocked, i)
			}
		}
		sigprocmask(_SIG_SETMASK, &sigBlocked, nil)
		for {
			select {
			case sig := <-enableSigChan:
				if sig > 0 {
					sigdelset(&sigBlocked, int(sig))
				}
			case sig := <-disableSigChan:
				if sig > 0 && blockableSig(sig) {
					sigaddset(&sigBlocked, int(sig))
				}
			}
			sigprocmask(_SIG_SETMASK, &sigBlocked, nil)
			maskUpdatedChan <- struct{}{}
		}
	}()
}

The dedicated thread starts with everything blockable blocked. When you call signal.Notify(c, os.Interrupt), the runtime removes SIGINT from that mask, making it deliverable on that thread, and then waits for the update to be applied:

 go
 
 
// src/runtime/signal_unix.go:187
// sigenable enables the Go signal handler to catch the signal sig.
// It is only called while holding the os/signal.handlers lock,
// via os/signal.enableSignal and signal_enable.
func sigenable(sig uint32) {
	if sig >= uint32(len(sigtable)) {
		return
	}

	// SIGPROF is handled specially for profiling.
	if sig == _SIGPROF {
		return
	}

	t := &sigtable[sig]
	if t.flags&_SigNotify != 0 {
		ensureSigM()
		enableSigChan <- sig
		<-maskUpdatedChan
		if atomic.Cas(&handlingSig[sig], 0, 1) {
			atomic.Storeuintptr(&fwdSig[sig], getsig(sig))
			setsig(sig, abi.FuncPCABIInternal(sighandler))
		}
	}
}

enableSigChan <- sig followed by <-maskUpdatedChan is a handshake: by the time Notify returns, the mask has actually been changed. That is what makes “raise a signal immediately after Notify” safe — the signal cannot be raised into a void, because the thread that can receive it has already been told.

sigsend: the handler’s entire job

The handler cannot block, cannot allocate and cannot take a mutex, so it does the minimum: it sets a bit.

 go
 
 
// src/runtime/sigqueue.go:68
// sigsend delivers a signal from sighandler to the internal signal delivery queue.
// It reports whether the signal was sent. If not, the caller typically crashes the program.
// It runs from the signal handler, so it's limited in what it can do.
func sigsend(s uint32) bool {
	bit := uint32(1) << uint(s&31)
	if s >= uint32(32*len(sig.wanted)) {
		return false
	}

	sig.delivering.Add(1)
	// We are running in the signal handler; defer is not available.

	if w := atomic.Load(&sig.wanted[s/32]); w&bit == 0 {
		sig.delivering.Add(-1)
		return false
	}

	// Add signal to outgoing queue.
	for {
		mask := sig.mask[s/32]
		if mask&bit != 0 {
			sig.delivering.Add(-1)
			return true // signal already in queue
		}
		if atomic.Cas(&sig.mask[s/32], mask, mask|bit) {
			break
		}
	}

	// Notify receiver that queue has new bit.
Send:
	for {
		switch sig.state.Load() {
		default:
			throw("sigsend: inconsistent state")
		case sigIdle:
			if sig.state.CompareAndSwap(sigIdle, sigSending) {
				break Send
			}
		case sigSending:
			// notification already pending
			break Send
		case sigReceiving:
			if sig.state.CompareAndSwap(sigReceiving, sigIdle) {
				if GOOS == "darwin" || GOOS == "ios" {
					sigNoteWakeup(&sig.note)
					break Send
				}
				notewakeup(&sig.note)
				break Send
			}
		}
	}

	sig.delivering.Add(-1)
	return true
}

Read that carefully; several things are going on.

The bitmask. sig.mask is a [(_NSIG + 31) / 32]uint32 — one bit per signal number. Setting a bit is atomic and cannot fail, cannot block and cannot allocate. That is the entire “queue”.

sig.wanted is the gate. If nobody called Notify for this signal, the bit is not set in wanted and sigsend returns false, which means “Go does not want this signal” and the runtime takes the default action — usually dying.

Signals are coalesced. if mask&bit != 0 { return true } — if the signal is already pending, the second one is dropped. This is standard POSIX behaviour (non-realtime signals are not queued) and it is why os/signal cannot be used as a counter.

The wakeup. Here is the “self-pipe”-style part. The handler has just written a bit into shared memory; the goroutine that will read it is asleep on a note. Waking it up requires a system call, and the only system call that is async-signal-safe enough to make here is the one in the Darwin branch:

 go
 
 
// src/runtime/os_darwin.go:96
// because the functions pthread_mutex_lock, pthread_cond_signal, and
// pthread_mutex_unlock, called by semawakeup, are not async-signal-safe.
// There is only one case where we need to wake up a note from a signal
// handler: the sigsend function. The signal handler code does not require
// all the features of notes: it does not need to do a timed wait.
// This is a separate implementation of notes, based on a pipe, that does
// not support timed waits but is async-signal-safe.
func sigNoteSetup(*note) {
	if sigNoteRead != 0 || sigNoteWrite != 0 {
		// Generalizing this would require avoiding the pipe-fork-closeonexec race, which entangles syscall.
		throw("duplicate sigNoteSetup")
	}
	var errno int32
	sigNoteRead, sigNoteWrite, errno = pipe()
	if errno != 0 {
		throw("pipe failed")
	}
	closeonexec(sigNoteRead)
	closeonexec(sigNoteWrite)

	// Make the write end of the pipe non-blocking, so that if the pipe
	// buffer is somehow full we will not block in the signal handler.
	// Leave the read end of the pipe blocking so that we will block
	// in sigNoteSleep.
	setNonblock(sigNoteWrite)
}

// sigNoteWakeup wakes up a thread sleeping on a note created by sigNoteSetup.
func sigNoteWakeup(*note) {
	var b byte
	write(uintptr(sigNoteWrite), unsafe.Pointer(&b), 1)
}

That is a textbook self-pipe: a byte written to a pipe in the handler, read by the sleeping consumer. On Linux the same job is done by notewakeup, which uses a futex and is async-signal-safe, so the pipe is only needed on Darwin and iOS, where pthread_cond_signal is not.

The three-state protocol. sig.state is sigIdle, sigSending or sigReceiving, and the transitions are compare-and-swaps. The comment at the top of the file states the invariant:

 go
 
 
// src/runtime/sigqueue.go:15
// Synchronization between sigsend and signal_recv is based on the sig.state
// variable. It can be in three states:
// * sigReceiving means that signal_recv is blocked on sig.Note and there are
// no new pending signals.
// * sigSending means that sig.mask *may* contain new pending signals,
// signal_recv can't be blocked in this state.
// * sigIdle means that there are no new pending signals and signal_recv is not
// blocked.
//
// Transitions between states are done atomically with CAS.
//
// When signal_recv is unblocked, it resets sig.Note and rechecks sig.mask.
// If several sigsends and signal_recv execute concurrently, it can lead to
// unnecessary rechecks of sig.mask, but it cannot lead to missed signals
// nor deadlocks.

That last sentence is the guarantee the whole design exists to provide: it cannot lead to missed signals.

The consumer side

One goroutine drains the bitmask and turns it back into signals:

 go
 
 
// src/runtime/sigqueue.go:126
// Called to receive the next queued signal.
// Must only be called from a single goroutine at a time.
//
//go:linkname signal_recv os/signal.signal_recv
func signal_recv() uint32 {
	for {
		// Serve any signals from local copy.
		for i := uint32(0); i < _NSIG; i++ {
			if sig.recv[i/32]&(1<<(i&31)) != 0 {
				sig.recv[i/32] &^= 1 << (i & 31)
				return i
			}
		}

		// Wait for updates to be available from signal sender.
	Receive:
		for {
			switch sig.state.Load() {
			default:
				throw("signal_recv: inconsistent state")
			case sigIdle:
				if sig.state.CompareAndSwap(sigIdle, sigReceiving) {
					if GOOS == "darwin" || GOOS == "ios" {
						sigNoteSleep(&sig.note)
						break Receive
					}
					notetsleepg(&sig.note, -1)
					noteclear(&sig.note)
					break Receive
				}
			case sigSending:
				if sig.state.CompareAndSwap(sigSending, sigIdle) {
					break Receive
				}
			}
		}

		// Incorporate updates from sender into local copy.
		for i := range sig.mask {
			sig.recv[i] = atomic.Xchg(&sig.mask[i], 0)
		}
	}
}

The atomic.Xchg at the end is the “take the whole mask at once” step: the consumer swaps the shared mask for its private copy in one atomic operation per word, so no bit can be lost between the swap and the scan.

And os/signal drives it with the world’s simplest loop:

 go
 
 
// src/os/signal/signal_unix.go:21
func loop() {
	for {
		process(syscall.Signal(signal_recv()))
	}
}

process fans the signal out to every registered channel, without blocking:

 go
 
 
// src/os/signal/signal.go:245
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) {
			// send but do not block for it
			select {
			case c <- sig:
			default:
			}
		}
	}

	// Avoid the race mentioned in Stop.
	for _, d := range handlers.stopping {
		if d.h.want(n) {
			select {
			case d.c <- sig:
			default:
			}
		}
	}
}

Note the default: in the select: the send is non-blocking. If your channel is full, the signal is dropped. That is why the Notify documentation says the caller must provide enough buffer space:

 go
 
 
// src/os/signal/signal.go:110
// Notify causes package signal to relay incoming signals to c.
// If no signals are provided, all incoming signals will be relayed to c.
// Otherwise, just the provided signals will.
//
// Package signal will not block sending to c: the caller must ensure
// that c has sufficient buffer space to keep up with the expected
// signal rate. For a channel used for notification of just one signal value,
// a buffer of size 1 is sufficient.

The Stop race

signal.Stop(c) has a genuine race to handle: a signal might be in the handler, in the queue, or on its way to your channel, at the moment you call Stop. If the signal then arrives at your channel after Stop returned, the contract “When Stop returns, it is guaranteed that c will receive no more signals” would be violated — and worse, for SIGINT the program would neither exit nor deliver the signal.

The package solves it with a “stopping” list and a quiescence wait:

 go
 
 
// src/os/signal/signal.go:190
// Stop causes package signal to stop relaying incoming signals to c.
// It undoes the effect of all prior calls to [Notify] using c.
// When Stop returns, it is guaranteed that c will receive no more signals.
func Stop(c chan<- os.Signal) {
	handlers.Lock()

	h := handlers.m[c]
	if h == nil {
		handlers.Unlock()
		return
	}
	delete(handlers.m, c)

	for n := 0; n < numSig; n++ {
		if h.want(n) {
			handlers.ref[n]--
			if handlers.ref[n] == 0 {
				disableSignal(n)
			}
		}
	}

	// Signals will no longer be delivered to the channel.
	// We want to avoid a race for a signal such as SIGINT:
	// it should be either delivered to the channel,
	// or the program should take the default action (that is, exit).
	// To avoid the possibility that the signal is delivered,
	// and the signal handler invoked, and then Stop deregisters
	// the channel before the process function below has a chance
	// to send it on the channel, put the channel on a list of
	// channels being stopped and wait for signal delivery to
	// quiesce before fully removing it.

	handlers.stopping = append(handlers.stopping, stopping{c, h})

	handlers.Unlock()

	signalWaitUntilIdle()

	handlers.Lock()

	for i, s := range handlers.stopping {
		if s.c == c {
			handlers.stopping = slices.Delete(handlers.stopping, i, i+1)
			break
		}
	}

	handlers.Unlock()
}

The wait itself is in the runtime:

 go
 
 
// src/runtime/sigqueue.go:170
// signalWaitUntilIdle waits until the signal delivery mechanism is idle.
// This is used to ensure that we do not drop a signal notification due
// to a race between disabling a signal and receiving a signal.
// This assumes that signal delivery has already been disabled for
// the signal(s) in question, and here we are just waiting to make sure
// that all the signals have been delivered to the user channels
// by the os/signal package.
//
//go:linkname signalWaitUntilIdle os/signal.signalWaitUntilIdle
func signalWaitUntilIdle() {
	// Although the signals we care about have been removed from
	// sig.wanted, it is possible that another thread has received
	// a signal, has read from sig.wanted, is now updating sig.mask,
	// and has not yet woken up the processor thread. We need to wait
	// until all current signal deliveries have completed.
	for sig.delivering.Load() != 0 {
		Gosched()
	}

	// Although WaitUntilIdle seems like the right name for this
	// function, the state we are looking for is sigReceiving, not
	// sigIdle. The sigIdle state is really more like sigProcessing.
	for sig.state.Load() != sigReceiving {
		Gosched()
	}
}

sig.delivering is the counter incremented at the top of sigsend. When it drops to zero, no handler is in flight. And when the state is sigReceiving, the consumer goroutine is asleep in notetsleepg with the mask already swapped — so nothing is in the pipe.

NotifyContext

Go 1.16 added the glue between the two halves of this article:

 go
 
 
// src/os/signal/signal.go:275
// NotifyContext returns a copy of the parent context that is marked done
// (its Done channel is closed) when one of the listed signals arrives,
// when the returned stop function is called, or when the parent context's
// Done channel is closed, whichever happens first.
//
// The stop function unregisters the signal behavior, which, like [signal.Reset],
// may restore the default behavior for a given signal. For example, the default
// behavior of a Go program receiving [os.Interrupt] is to exit. Calling
// NotifyContext(parent, os.Interrupt) will change the behavior to cancel
// the returned context. Future interrupts received will not trigger the default
// (exit) behavior until the returned stop function is called.
//
// If a signal causes the returned context to be canceled, calling
// [context.Cause] on it will return an error describing the signal.
//
// The stop function releases resources associated with it, so code should
// call stop as soon as the operations running in this Context complete and
// signals no longer need to be diverted to the context.
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:
				c.cancel(signalError(s.String() + " signal received"))
			case <-c.Done():
			}
		}()
	}
	return c, c.stop
}

A signal becomes a cancellation cause, and the signalError type is arranged so that errors.Is(err, context.Canceled) still matches:

 go
 
 
// src/os/signal/signal.go:352
type signalError string

func (s signalError) Error() string {
	return string(s)
}

func (s signalError) Is(target error) bool {
	if target == context.Canceled {
		return true
	}
	return false
}

The context tree

Now the other half. context.Context is an interface with four methods, and the cancellation machinery is a tree of cancelCtx nodes:

 go
 
 
// src/context/context.go:430
// A cancelCtx can be canceled. When canceled, it also cancels any children
// that implement canceler.
type cancelCtx struct {
	Context

	mu sync.Mutex // protects following fields
	done atomic.Value // of chan struct{}, created lazily, closed by first cancel call
	children map[canceler]struct{} // set to nil by the first cancel call
	err atomic.Value // set to non-nil by the first cancel call
	cause error // set to non-nil by the first cancel call
}

Each cancelCtx holds a set of children and a done channel. Cancelling a parent closes its done channel and cancels every child, recursively:

 go
 
 
// src/context/context.go:551
// cancel closes c.done, cancels each of c's children, and, if
// removeFromParent is true, removes c from its parent's children.
// cancel sets c.cause to cause if this is the first time c is canceled.
func (c *cancelCtx) cancel(removeFromParent bool, err, cause error) {
	if err == nil {
		panic("context: internal error: missing cancel error")
	}
	if cause == nil {
		cause = err
	}
	c.mu.Lock()
	if c.err.Load() != nil {
		c.mu.Unlock()
		return // already canceled
	}
	c.err.Store(err)
	c.cause = cause
	d, _ := c.done.Load().(chan struct{})
	if d == nil {
		c.done.Store(closedchan)
	} else {
		close(d)
	}
	for child := range c.children {
		// NOTE: acquiring the child's lock while holding parent's lock.
		child.cancel(false, err, cause)
	}
	c.children = nil
	c.mu.Unlock()

	if removeFromParent {
		removeChild(c.Context, c)
	}
}

Three details worth noting:

The first cancel wins. if c.err.Load() != nil { return } — a second cancel is a no-op, so the error a context reports is the reason it was cancelled the first time.
The parent’s lock is held while cancelling children. That is why the comment says “NOTE: acquiring the child’s lock while holding parent’s lock” — it is a deliberate lock-ordering decision, and the tree structure guarantees it cannot deadlock (a child never holds its own lock while acquiring its parent’s).
closedchan is a shared, already-closed channel. A context that is cancelled before anyone asks for its Done channel does not allocate one; it reuses a global closed channel.

The children map is how the tree is built:

 go
 
 
// src/context/context.go:478
// propagateCancel arranges for child to be canceled when parent is.
// It sets the parent context of cancelCtx.
func (c *cancelCtx) propagateCancel(parent Context, child canceler) {
	c.Context = parent

	done := parent.Done()
	if done == nil {
		return // parent is never canceled
	}

	select {
	case <-done:
		// parent is already canceled
		child.cancel(false, parent.Err(), Cause(parent))
		return
	default:
	}

	if p, ok := parentCancelCtx(parent); ok {
		// parent is a *cancelCtx, or derives from one.
		p.mu.Lock()
		if err := p.err.Load(); err != nil {
			// parent has already been canceled
			child.cancel(false, err.(error), p.cause)
		} else {
			if p.children == nil {
				p.children = make(map[canceler]struct{})
			}
			p.children[child] = struct{}{}
		}
		p.mu.Unlock()
		return
	}

	if a, ok := parent.(afterFuncer); ok {
		// parent implements an AfterFunc method.
		c.mu.Lock()
		stop := a.AfterFunc(func() {
			child.cancel(false, parent.Err(), Cause(parent))
		})
		c.Context = stopCtx{
			Context: parent,
			stop: stop,
		}
		c.mu.Unlock()
		return
	}

	goroutines.Add(1)
	go func() {
		select {
		case <-parent.Done():
			child.cancel(false, parent.Err(), Cause(parent))
		case <-child.Done():
		}
	}()
}

That function has three strategies, chosen in order:

The parent is already cancelled — cancel the child immediately.
The parent is a cancelCtx — register the child in the parent’s children map. No goroutine, no allocation beyond the map entry. This is the fast path and it covers the overwhelming majority of real code, because WithCancel on a WithCancel parent stays inside the cancelCtx world.
The parent is some other Context — the only way to find out that an arbitrary Context was cancelled is to watch its Done channel, so the runtime spawns a goroutine per child.

That third case is the price of the interface being open-ended. A custom Context implementation that is not a cancelCtx costs one goroutine per derived context, for the life of the derived context.

The tree is torn down when a child is cancelled explicitly:

 go
 
 
// src/context/context.go:400
func removeChild(parent Context, child canceler) {
	if s, ok := parent.(stopCtx); ok {
		s.stop()
		return
	}
	p, ok := parentCancelCtx(parent)
	if !ok {
		return
	}
	p.mu.Lock()
	if p.children != nil {
		delete(p.children, child)
	}
	p.mu.Unlock()
}

Removing the child from the parent’s map is what stops a long-lived parent from accumulating children forever. If you forget to call the cancel function, the child stays in the parent’s map and the parent holds a reference to it — a leak that go vet can find for you (lostcancel).

Canceled versus DeadlineExceeded

The two sentinel errors are not the same thing, and the difference is meaningful:

 go
 
 
// src/context/context.go:166
// Canceled is the error returned by [Context.Err] when the context is canceled
// for some reason other than its deadline passing.
var Canceled = errors.New("context canceled")

// DeadlineExceeded is the error returned by [Context.Err] when the context is canceled
// due to its deadline passing.
var DeadlineExceeded error = deadlineExceededError{}

type deadlineExceededError struct{}

func (deadlineExceededError) Error() string { return "context deadline exceeded" }
func (deadlineExceededError) Timeout() bool { return true }
func (deadlineExceededError) Temporary() bool { return true }

Canceled is a plain errors.New value: a package-level singleton you can compare with ==. DeadlineExceeded is a distinct type, because it has to carry the Timeout() bool method so that net/http and friends can tell a timeout from a cancellation. That means:

err == context.Canceled works for cancellation.
err == context.DeadlineExceeded also works, because the value is a zero-size struct and comparing two of them is true — but the idiomatic test is errors.Is(err, context.DeadlineExceeded).
errors.Is(err, context.DeadlineExceeded) is false for a plain cancellation.

A deadline context is a timerCtx, which is a cancelCtx plus a timer:

 go
 
 
// src/context/context.go:664
// A timerCtx carries a timer and a deadline. It embeds a cancelCtx to
// implement Done and Err. It implements cancel by stopping its timer then
// delegating to cancelCtx.cancel.
type timerCtx struct {
	cancelCtx
	timer *time.Timer // Under cancelCtx.mu.

	deadline time.Time
}

and the deadline is enforced with a time.AfterFunc — which is to say, with the per-P timer heap from the previous article:

 go
 
 
// src/context/context.go:654
	c.mu.Lock()
	defer c.mu.Unlock()
	if c.err.Load() == nil {
		c.timer = time.AfterFunc(dur, func() {
			c.cancel(true, DeadlineExceeded, cause)
		})
	}
	return c, func() { c.cancel(true, Canceled, nil) }

Note the asymmetry at the end: the AfterFunc path cancels with DeadlineExceeded, the explicit cancel function cancels with Canceled. If your deadline fires and you call cancel, whichever happens first wins.

And the cause is a separate thing from the error. context.Cause(ctx) returns the cause you passed to WithCancelCause, or the error itself if there was none. That is how NotifyContext can report “interrupt signal received” while ctx.Err() still returns context.Canceled.

Trade-offs

What the signal design buys you: no lost signals, no blocking in the handler, and a clean separation between “the kernel told us something” and “a goroutine decides what to do about it”. The three-state CAS protocol means concurrent senders and one receiver can never deadlock or miss a bit.

What it costs:

Signals are coalesced. Ten SIGINTs in a row produce one delivery.
The channel send is lossy. If your channel is full, the signal is dropped. You must size the buffer yourself.
One extra goroutine and one extra thread. The os/signal loop goroutine and the dedicated mask thread exist for the whole life of the program.
Notify is not free. It takes a global lock, updates a map, and synchronously waits for the mask change to be applied.

What the context design buys you: cancellation is a value that flows down a tree, not a channel you have to plumb. Any number of layers of WithCancel compose, and cancelling the root cancels everything under it.

What it costs:

A goroutine per non-cancelCtx parent. Derive from a custom Context implementation and you pay a goroutine.
The tree must be pruned. Forget defer cancel() and the parent holds the child forever.
Cancellation is not rollback. ctx.Done() tells you to stop; it does not undo work already done, and it does not interrupt a goroutine that is not watching.

Caveats

signal.Notify changes the default behaviour. Once you Notify for SIGINT, the program no longer dies on Ctrl-C; it is your job to exit. If your handler decides to continue, the user cannot interrupt you any more.

The second SIGINT is often the escape hatch. A common pattern is to Notify for SIGINT, cancel the context on the first one, and exit on the second.

signal.Notify with a full channel drops the signal. Not “queues it” — drops it.

os/signal is Unix-centric. On Windows, the signals are synthesized from console control events, and the whole model is different.

context.Canceled and context.DeadlineExceeded are not interchangeable. Code that returns a context error to a caller should preserve which one it was; http.Server turns DeadlineExceeded into a 504 and everything else into a 503.

ctx.Err() blocks until the Done channel is closed. That looks like a bug in Err:

 go
 
 
// src/context/context.go:464
func (c *cancelCtx) Err() error {
	// An atomic load is ~5x faster than a mutex, which can matter in tight loops.
	if err := c.err.Load(); err != nil {
		// Ensure the done channel has been closed before returning a non-nil error.
		// closedchan is closed at init and shared by every canceled context, so
		// receiving from it would take one process-global lock for nothing.
		if done := c.Done(); done != closedchan {
			<-done
		}
		return err.(error)
	}
	return nil
}

It is not a bug: the comment explains that the error is stored before the channel is closed, and Err waits for the close so that a caller that sees a non-nil error is guaranteed that <-ctx.Done() would return immediately.

A cancelled context does not interrupt work. It is advisory. A goroutine sitting in a syscall or a tight loop will keep going.

NotifyContext’s stop function restores the default behaviour. Calling it for SIGINT means the next Ctrl-C kills the program again.

Wrapping up

The one thing to remember: Go’s signal handler does almost nothing — it sets a bit in a global bitmask with a compare-and-swap and wakes one goroutine, which then forwards signals to your channels. Nothing is lost, because the mask update is synchronised with Notify and the consumer swaps the whole mask atomically.

The part people get wrong: believing the signal is delivered to the main thread, or that Notify is a no-op until the next signal. The kernel picks a thread with the signal unblocked, Go keeps one dedicated thread whose mask it manages for exactly this purpose, and Notify does not return until that thread’s mask has been changed.

What to go do about it: use signal.NotifyContext instead of signal.Notify plus a manual goroutine — it wires the signal to a context with the correct cause, and it gives you the stop function that restores the default behaviour when you are done.

Go Preempts Goroutines with a Signal: Asynchronous Preemption Since Go 1.14

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: A goroutine that never calls anything has to be stoppable anyway — otherwise the garbage collector could never finish. Go used to rely on the goroutine hitting a function call, but since Go 1.14 the runtime sends the thread a SIGURG, checks whether the interrupted program counter is an async safe point (using the compiler’s PCDATA_UnsafePoint table), and if so rewrites the signal context to look like the thread just called asyncPreempt.

Preemption is the mechanism that lets Go have cheap goroutines. If a goroutine could never be stopped, then a loop with no function calls would hold the garbage collector hostage forever, and GOMAXPROCS would be a lie.

Go has two ways to stop a goroutine, and the runtime’s own header comment describes both:

 go
 
 
// src/runtime/preempt.go:5
// Goroutine preemption
//
// A goroutine can be preempted at any safe-point. Currently, there
// are a few categories of safe-points:
//
// 1. A blocked safe-point occurs for the duration that a goroutine is
// descheduled, blocked on synchronization, or in a system call.
//
// 2. Synchronous safe-points occur when a running goroutine checks
// for a preemption request.
//
// 3. Asynchronous safe-points occur at any instruction in user code
// where the goroutine can be safely paused and a conservative
// stack and register scan can find stack roots. The runtime can
// stop a goroutine at an async safe-point using a signal.
//
// At both blocked and synchronous safe-points, a goroutine's CPU
// state is minimal and the garbage collector has complete information
// about its entire stack. This makes it possible to deschedule a
// goroutine with minimal space, and to precisely scan a goroutine's
// stack.
//
// Synchronous safe-points are implemented by overloading the stack
// bound check in function prologues. To preempt a goroutine at the
// next synchronous safe-point, the runtime poisons the goroutine's
// stack bound to a value that will cause the next stack bound check
// to fail and enter the stack growth implementation, which will
// detect that it was actually a preemption and redirect to preemption
// handling.
//
// Preemption at asynchronous safe-points is implemented by suspending
// the thread using an OS mechanism (e.g., signals) and inspecting its
// state to determine if the goroutine was at an asynchronous
// safe-point. Since the thread suspension itself is generally
// asynchronous, it also checks if the running goroutine wants to be
// preempted, since this could have changed. If all conditions are
// satisfied, it adjusts the signal context to make it look like the
// signaled thread just called asyncPreempt and resumes the thread.
// asyncPreempt spills all registers and enters the scheduler.

Read that twice. The key sentence is the last one: the runtime does not preempt in the signal handler. It adjusts the signal context so that, when the thread resumes, it looks like the thread itself called asyncPreempt.

The synchronous path: poison the stack bound

The cheap way to preempt a goroutine is to make its next function prologue fail. The runtime owns a field called stackguard0, which holds the stack bound that every prologue compares against. Set it to a poison value and the next call goes down the “stack overflow” path — where the runtime notices it was actually a preemption request and handles it.

 go
 
 
// src/runtime/proc.go:6929
func preemptone(pp *p) bool {
	mp := pp.m.ptr()
	if mp == nil || mp == getg().m {
		return false
	}
	gp := mp.curg
	if gp == nil || gp == mp.g0 {
		return false
	}
	if readgstatus(gp)&^_Gscan == _Gsyscall {
		// Don't bother trying to preempt a goroutine in a syscall.
		return false
	}

	gp.preempt = true

	// Every call in a goroutine checks for stack overflow by
	// comparing the current stack pointer to gp->stackguard0.
	// Setting gp->stackguard0 to StackPreempt folds
	// preemption into the normal stack overflow check.
	gp.stackguard0 = stackPreempt

This is free: no signal, no context switch. But it only works if the goroutine ever calls another function. A tight loop like for i := 0; i < 1e9; i++ { total += i } has no prologue to trip, so the request would sit there forever. That is exactly the case asynchronous preemption exists for.

The asynchronous path: SIGURG

The runtime picks a signal that nobody uses. signal_unix.go explains the choice at length:

 go
 
 
// src/runtime/signal_unix.go:64
// 4. We need to deal with platforms without real-time signals (like
// macOS), so those are out.
//
// We use SIGURG because it meets all of these criteria, is extremely
// unlikely to be used by an application for its "real" meaning (both
// because out-of-band data is basically unused and because SIGURG
// doesn't report which socket has the condition, making it pretty
// useless), and even if it is, the application has to be ready for
// spurious SIGURG. SIGIO wouldn't be a bad choice either, but is more
// likely to be used for real.
const sigPreempt = _SIGURG

preemptM is what sends it. It is called with the target goroutine’s scan bit held, and it releases that bit before returning:

 go
 
 
// src/runtime/signal_unix.go:363
// preemptM sends a preemption request to the M running gp. This request may
// be handled asynchronously and may be coalesced with other requests to
// the M. When the request is received, if the running G or P are
// marked for preemption and the goroutine is at an asynchronous
// safe-point, it will preempt the goroutine. It always atomically
// increments the M's preemptGen after handling a preemption request.
//
// gp.preempt must be set, and gp must be in _Gscanrunning, with its _Gscan
// bit held by the caller.
// preemptM releases the _Gscan bit before returning.
func preemptM(gp *g) {
	// Save the M before releasing the _Gscan bit, which lets gp change Ms.
	// preemptM is best effort, so it's fine if we signal a stale M.
	mp := gp.m
	casfrom_Gscanstatus(gp, _Gscanrunning, _Grunning)

and then, at the bottom of the function:

 go
 
 
// src/runtime/signal_unix.go:385
	if mp.signalPending.CompareAndSwap(0, 1) {
		if GOOS == "darwin" || GOOS == "ios" {
			pendingPreemptSignals.Add(1)
		}

		// If multiple threads are preempting the same M, it may send many
		// signals to the same M such that it hardly make progress, causing
		// live-lock problem. Apparently this could happen on darwin. See
		// issue #37741.
		// Only send a signal if there isn't already one pending.
		signalM(mp, sigPreempt)
	}

The signalPending flag means one signal per M at a time. Ten threads all asking the same M to stop should not deliver ten signals.

On Linux, “send a signal to this M” means tgkill, i.e. the kill syscall with a thread id:

 go
 
 
// src/runtime/os_linux.go:579
// signalM sends a signal to mp.
func signalM(mp *m, sig int) {
	tgkill(getpid(), int(mp.procid), sig)
}

The signal handler

The signal arrives on the thread the runtime wants to stop. The handler runs on the gsignal stack, and the interesting part is doSigPreempt:

 go
 
 
// src/runtime/signal_unix.go:341
// doSigPreempt handles a preemption signal on gp.
func doSigPreempt(gp *g, ctxt *sigctxt) {
	// Check if this G wants to be preempted and is safe to
	// preempt.
	if wantAsyncPreempt(gp) {
		if ok, newpc := isAsyncSafePoint(gp, ctxt.sigpc(), ctxt.sigsp(), ctxt.siglr()); ok {
			// Adjust the PC and inject a call to asyncPreempt.
			ctxt.pushCall(abi.FuncPCABI0(asyncPreempt), newpc)
		}
	}

	// Acknowledge the preemption.
	gp.m.preemptGen.Add(1)
	gp.m.signalPending.Store(0)

	if GOOS == "darwin" || GOOS == "ios" {
		pendingPreemptSignals.Add(-1)
	}
}

pushCall is the trick. On amd64 it is four instructions’ worth of logic:

 go
 
 
// src/runtime/signal_amd64.go:80
func (c *sigctxt) pushCall(targetPC, resumePC uintptr) {
	// Make it look like we called target at resumePC.
	sp := uintptr(c.rsp())
	sp -= goarch.PtrSize
	*(*uintptr)(unsafe.Pointer(sp)) = resumePC
	c.set_rsp(uint64(sp))
	c.set_rip(uint64(targetPC))
}

Push the resume PC onto the thread’s stack, point the instruction pointer at asyncPreempt, and let the thread continue. When asyncPreempt returns, the ret will pop the resume PC and the goroutine continues exactly where it was — except that it has been through the scheduler.

Note wantAsyncPreempt is checked first. The signal may have been delivered late, or coalesced with something else, so the handler re-reads the current state rather than trusting the request:

 go
 
 
// src/runtime/preempt.go:375
// wantAsyncPreempt returns whether an asynchronous preemption is
// queued for gp.
func wantAsyncPreempt(gp *g) bool {
	// Check both the G and the P.
	return (gp.preempt || gp.m.p != 0 && gp.m.p.ptr().preempt) && readgstatus(gp)&^_Gscan == _Grunning
}

Deciding whether it is safe: `isAsyncSafePoint`

Not every instruction can be interrupted. If the thread is halfway through a write barrier, or inside a runtime function, stopping it and conservatively scanning the stack would be wrong — or would deadlock.

 go
 
 
// src/runtime/preempt.go:398
func isAsyncSafePoint(gp *g, pc, sp, lr uintptr) (bool, uintptr) {
	mp := gp.m

	// Only user Gs can have safe-points. We check this first
	// because it's extremely common that we'll catch mp in the
	// scheduler processing this G preemption.
	if mp.curg != gp {
		return false, 0
	}

	// Check M state.
	if mp.p == 0 || !canPreemptM(mp) {
		return false, 0
	}

	// Check stack space.
	if sp < gp.stack.lo || sp-gp.stack.lo < asyncPreemptStack {
		return false, 0
	}

and then the interesting part, the compiler-provided table:

 go
 
 
// src/runtime/preempt.go:451
	up, startpc := pcdatavalue2(f, abi.PCDATA_UnsafePoint, pc)
	if up == abi.UnsafePointUnsafe {
		// Unsafe-point marked by compiler. This includes
		// atomic sequences (e.g., write barrier) and nosplit
		// functions (except at calls).
		return false, 0
	}
	if fd := funcdata(f, abi.FUNCDATA_LocalsPointerMaps); fd == nil || f.flag&abi.FuncFlagAsm != 0 {
		// This is assembly code. Don't assume it's well-formed.
		// TODO: Empirically we still need the fd == nil check. Why?
		//
		// TODO: Are there cases that are safe but don't have a
		// locals pointer map, like empty frame functions?
		// It might be possible to preempt any assembly functions
		// except the ones that have funcFlag_SPWRITE set in f.flag.
		return false, 0
	}

PCDATA_UnsafePoint is a per-function table mapping program counters to safety. The encoding lives in internal/abi:

 go
 
 
// src/internal/abi/symtab.go:124
// Special values for the PCDATA_UnsafePoint table.
const (
	UnsafePointSafe = -1 // Safe for async preemption
	UnsafePointUnsafe = -2 // Unsafe for async preemption

	// UnsafePointRestart1(2) apply on a sequence of instructions, within
	// which if an async preemption happens, we should back off the PC
	// to the start of the sequence when resuming.
	// We need two so we can distinguish the start/end of the sequence
	// in case that two sequences are next to each other.
	UnsafePointRestart1 = -3
	UnsafePointRestart2 = -4

	// Like UnsafePointRestart1, but back to function entry if async preempted.
	UnsafePointRestartAtEntry = -5
)

UnsafePointRestart1/Restart2 are how the compiler marks a restartable instruction sequence: if you are preempted in the middle of it, the PC is rewound to the start of the sequence so the whole thing can be redone. That is how the runtime can safely interrupt, say, a multi-word store.

There is also a blunt instrument: the runtime never preempts its own code.

 go
 
 
// src/runtime/preempt.go:468
	// Check the inner-most name
	u, uf := newInlineUnwinder(f, pc)
	name := u.srcFunc(uf).name()
	if stringslite.HasPrefix(name, "runtime.") ||
		stringslite.HasPrefix(name, "internal/runtime/") ||
		stringslite.HasPrefix(name, "reflect.") {
		// For now we never async preempt the runtime or
		// anything closely tied to the runtime. Known issues
		// include: various points in the scheduler ("don't
		// preempt between here and here"), much of the defer
		// implementation (untyped info on stack), bulk write
		// barriers (write barrier check), atomic functions in
		// internal/runtime/atomic, reflect.{makeFuncStub,methodValueCall}.

`asyncPreempt`: spilling the registers

Once the thread resumes, it is running asyncPreempt, which is assembly. On amd64 it saves every general-purpose register onto the goroutine’s stack, because any of them might hold a pointer:

 asm
 
 
// src/runtime/preempt_amd64.s:8
TEXT ·asyncPreempt(SB),NOSPLIT|NOFRAME,$0-0
	PUSHQ BP
	MOVQ SP, BP
	// Save flags before clobbering them
	PUSHFQ
	// obj doesn't understand ADD/SUB on SP, but does understand ADJSP
	ADJSP $112
	// But vet doesn't know ADJSP, so suppress vet stack checking
	NOP SP
	// Save GPs
	MOVQ AX, 0(SP)
	MOVQ CX, 8(SP)
	MOVQ DX, 16(SP)
	MOVQ BX, 24(SP)
	MOVQ SI, 32(SP)
	MOVQ DI, 40(SP)
	MOVQ R8, 48(SP)
	MOVQ R9, 56(SP)
	MOVQ R10, 64(SP)
	MOVQ R11, 72(SP)
	MOVQ R12, 80(SP)
	MOVQ R13, 88(SP)
	MOVQ R14, 96(SP)
	MOVQ R15, 104(SP)

The Go continuation is deliberately nosplit and write-barrier free:

 go
 
 
// src/runtime/preempt.go:315
// asyncPreempt2 is the Go continuation of asyncPreempt.
//
// It must be deeply nosplit because there's untyped data on the stack from
// asyncPreempt.
//
// It must not have any write barriers because we need to limit the amount of
// stack it uses.
//
//go:nosplit
//go:nowritebarrierrec
func asyncPreempt2() {
	// We can't grow the stack with untyped data from asyncPreempt, so switch to
	// the system stack right away.
	mcall(func(gp *g) {
		gp.asyncSafePoint = true

		// Move the extended register state from the P to the G. We do this now that
		// we're on the system stack to avoid stack splits.
		xRegSave(gp)

		if gp.preemptStop {
			preemptPark(gp)
		} else {
			gopreempt_m(gp)
		}
		// The above functions never return.
	})

The asyncSafePoint flag matters later: it tells the GC that this goroutine’s stack was scanned conservatively, so the stack cannot be shrunk while it is in that state.

After the preemption

gopreempt_m ends up in goschedImpl, which is the same path as runtime.Gosched() except for the trace event and one detail:

 go
 
 
// src/runtime/proc.go:4328
func goschedImpl(gp *g, preempted bool) {
	pp := gp.m.p.ptr()
	trace := traceAcquire()
	status := readgstatus(gp)
	if status&^_Gscan != _Grunning {
		dumpgstatus(gp)
		throw("bad g status")
	}
	if trace.ok() {
		// Trace the event before the transition. It may take a
		// stack trace, but we won't own the stack after the
		// transition anymore.
		if preempted {
			trace.GoPreempt()
		} else {
			trace.GoSched()
		}
	}
	casgstatus(gp, _Grunning, _Grunnable)

Note that a preempted goroutine goes onto the global run queue, not the local one (unless the GC is waiting for it). That keeps the preempted goroutine from immediately being rescheduled onto the same P, which would make preemption useless for latency purposes.

What triggers a preemption?

Three things:

The GC. Before a GC cycle, the runtime asks every P to stop its goroutine so the mark phase can start.
sysmon. The background thread forces a preemption if a P has been running the same goroutine for too long. The time slice is 10 ms:

 go
 
 
// src/runtime/proc.go:6689
// forcePreemptNS is the time slice given to a G before it is
// preempted.
const forcePreemptNS = 10 * 1000 * 1000 // 10ms

You. runtime.Gosched() and the //go:yield pragma.

The GC case is the one that makes asynchronous preemption non-negotiable: a goroutine in a tight loop with no calls would never reach a safe point, and the GC would never finish. With SIGURG, the loop is interrupted at the next instruction the compiler marked safe.

The preemptible-loops experiment

There is a goexperiment.preemptibleloops build tag in the tree, off by default. It makes the compiler insert an explicit rescheduling check on every loop backedge:

 go
 
 
// src/internal/goexperiment/exp_preemptibleloops_on.go:3
//go:build goexperiment.preemptibleloops

package goexperiment

const PreemptibleLoops = true
const PreemptibleLoopsInt = 1

and the compiler pass that does the work is enabled by that flag:

 go
 
 
// src/cmd/compile/internal/ssacompile/compile.go:449
	{Name: "insert resched checks", Fn: insertLoopReschedChecks,
		Disabled: !buildcfg.Experiment.PreemptibleLoops}, // insert resched checks in loops.

The idea is the same as the synchronous preemption trick, applied to loops: compare the stack pointer against the stack bound at the bottom of the loop, and if the bound has been poisoned, call morestack — which the runtime then recognises as a preemption request. It trades a comparison and a branch per loop iteration for cheaper, more deterministic preemption. The compiler’s own comment describes the mechanism:

 go
 
 
// src/cmd/compile/internal/ssacompile/loopreschedchecks.go:47
// insertLoopReschedChecks inserts rescheduling checks on loop backedges.
func insertLoopReschedChecks(f *ssa.Func) {
	// TODO: when split information is recorded in export data, insert checks only on backedges that can be reached on a split-call-free path.

	// Loop reschedule checks compare the stack pointer with
	// the per-g stack bound. If the pointer appears invalid,
	// that means a reschedule check is needed.

Trade-offs

What asynchronous preemption buys you. A goroutine in a loop with no function calls is still stoppable. Before Go 1.14 it was not: the classic “busy loop blocks the GC” bug was real, and the only fixes were to add a function call or to call runtime.Gosched().

What it costs. A signal, a signal handler, a register spill, and a conservative stack scan. Signals are not cheap: on Linux, tgkill is a syscall, and the delivery of a signal to a thread that is running takes a kernel round trip. The runtime limits how often this can happen per M with the signalPending flag and a rate limit in suspendG.

Conservative scanning. At an async safe point the runtime does not know precisely which words in the stack are pointers, so it scans conservatively. That is why gp.asyncSafePoint is set, and why the runtime refuses to shrink such a stack afterwards.

The runtime never preempts itself. Any function whose name starts with runtime. or reflect. is off limits, which rules out a whole class of bugs but also means a long loop inside the runtime cannot be interrupted.

Caveats

A goroutine blocked in a syscall cannot be preempted. preemptone gives up explicitly when the target is in _Gsyscall. The runtime’s answer there is to take the P away from the thread rather than stop the goroutine.

runtime.LockOSThread does not prevent preemption — it prevents the goroutine from moving to another thread, but the goroutine can still be stopped and rescheduled on the same thread.

Assembly functions are not preemptible. isAsyncSafePoint rejects anything without a locals pointer map, and anything marked SPWRITE.

A cgo call blocks preemption for the duration of the C call. The runtime cannot interrupt arbitrary C code, and it will not try.

The preemptible-loops experiment is off by default. If you build with GOEXPERIMENT=preemptibleloops you get loop-backedge checks, and the compiler pass is still marked as work in progress.

GODEBUG=asyncpreemptoff=1 disables the whole mechanism, which is a useful bisection tool when you suspect a preemption bug.

Wrapping up

The one thing to remember: Go has two preemption mechanisms, and the asynchronous one is the interesting one. The runtime sends SIGURG to the target thread, checks the interrupted PC against the compiler’s PCDATA_UnsafePoint table, and if the spot is safe, rewrites the signal context so the thread resumes inside asyncPreempt — which spills the registers and enters the scheduler.

The part people get wrong: the preemption does not happen in the signal handler. The handler only adjusts the signal context. The goroutine is stopped by ordinary code resuming at a different program counter, which is why the runtime can use the same machinery for the stack-safety check it already had.

What to go do about it: if you have a latency-sensitive service and you suspect GC pauses or scheduler latency, read the GODEBUG=schedtrace output together with GODEBUG=asyncpreemptoff=1 runs; and if you are writing assembly or using //go:nosplit, remember that you are opting out of asynchronous preemption entirely.

Signals on Opensource internals

How Go's CPU Profiler Works: SIGPROF, the Signal Stack and 100 Hz Sampling

The 100 Hz decision

Arming the timer

The signal stack

The handler: identify the goroutine, unwind the stack

Writing to the ring buffer

The three-word header

The memory profile is a different animal

Why CPU-bound goroutines dominate

Trade-offs

Caveats

Wrapping up

Further reading

How Go Handles Signals and Context Cancellation Without Losing Signals

The table of signals

Installing the handler

Where a signal lands

sigsend: the handler’s entire job

The consumer side

The Stop race

NotifyContext

The context tree

Canceled versus DeadlineExceeded

Trade-offs

Caveats

Wrapping up

Further reading

Go Preempts Goroutines with a Signal: Asynchronous Preemption Since Go 1.14

The synchronous path: poison the stack bound

The asynchronous path: SIGURG

The signal handler

Deciding whether it is safe: isAsyncSafePoint

asyncPreempt: spilling the registers

After the preemption

What triggers a preemption?

The preemptible-loops experiment

Trade-offs

Caveats

Wrapping up

Further reading

Deciding whether it is safe: `isAsyncSafePoint`

`asyncPreempt`: spilling the registers