Go Reference ยท Logging, Flags and Testing
Go os/signal package
Reference for Go's os/signal package: Notify, NotifyContext, Stop, Ignore and Reset, with channel buffering rules and graceful shutdown patterns.
The os/signal package delivers operating system signals to your program as values on a channel. You register a channel with signal.Notify, and from then on the runtime sends a value there each time one of the chosen signals arrives. The default behavior for those signals (usually terminating the process) is replaced by your handling.
The most common use is a graceful shutdown: wait for SIGINT (Ctrl+C) or SIGTERM (sent by kill, Docker and Kubernetes), finish in-flight work, then exit. Since Go 1.16, signal.NotifyContext wraps this in a context.Context that is canceled when the signal arrives.
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() <-ctx.Done() // blocks until Ctrl+C or SIGTERM
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Syntax
func Notify(c chan<- os.Signal, sig ...os.Signal) func NotifyContext(parent context.Context, signals ...os.Signal) (ctx context.Context, stop context.CancelFunc) func Stop(c chan<- os.Signal) func Ignore(sig ...os.Signal) func Ignored(sig os.Signal) bool func Reset(sig ...os.Signal)
| Name | Description |
|---|---|
Notify(c, sig...) |
Relays the listed signals to c. With no signals listed, it relays every signal. Can be called again on the same channel to add more. |
NotifyContext(parent, sig...) |
Returns a context canceled when one of the signals arrives, when stop is called, or when parent is canceled. |
Stop(c) |
Stops relaying to c. No more values arrive, but values already in the buffer stay. |
Ignore(sig...) |
Makes the program ignore the signals, and removes them from any channels. |
Ignored(sig) |
Reports whether sig is currently ignored. |
Reset(sig...) |
Cancels all Notify registrations for these signals and restores default behavior. |
Returns: NotifyContext returns the derived context and a stop function you should always call (usually with defer) to release resources and restore default handling.
Edge cases: signals that cannot be caught, SIGKILL and SIGSTOP, are never delivered. On Windows only os.Interrupt (Ctrl+C) and syscall.SIGTERM are meaningful; other signals such as SIGHUP or SIGUSR1 do not exist there.
Usage notes
- Use a buffered channel. The package never blocks when it sends. If your channel is unbuffered and nobody is receiving at that moment, the signal is dropped. A buffer of 1 is enough for one signal type; use a larger one if you watch several.
- Which signals?
os.InterruptisSIGINTon every platform.syscall.SIGTERMis what process managers send on shutdown. Handle both. - Registering overrides the default. After
NotifyforSIGINT, Ctrl+C no longer kills the program. Make sure the receiving code eventually exits, or the process cannot be stopped from the terminal. A common trick is callingstop()right after the first signal, so a second Ctrl+C terminates immediately. NotifyContextis usually better than rawNotifyfor servers: pass the context intohttp.Server.Shutdownand into your workers, as in the second example.- Signals in Docker. Docker sends
SIGTERMto the container's main process only. Use the exec form ofCMD(CMD ["./app"]) so your program is that process and not a child of a shell that swallows the signal. SIGPIPEis special: writing to a closed pipe on file descriptors 1 or 2 kills the program unless you handle it; on others it just returnsEPIPE.- Tests. Sending a signal to your own process with
syscall.Kill(Unix only) is a simple way to test shutdown code.
Related
context,os,sync/atomic- Lessons: Graceful Shutdown, Context, Running External Commands