runtime: treat CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, CTRL_SHUTDOWN_EVENT as SIGTERM on Windows

This matches the existing behavior of treating CTRL_C_EVENT, CTRL_BREAK_EVENT as a synthesized SIGINT event.

See https://docs.microsoft.com/en-us/windows/console/handlerroutine for a good documentation source upstream to confirm these values.

As for the usage of these events, the "Timeouts" section of that upstream documentation is important to note, especially the limited window in which to do any cleanup before the program will be forcibly killed (defaults typically 5s, but as low as 500ms, and in many cases configurable system-wide).

These events are especially relevant for Windows containers, where these events (particularly `CTRL_SHUTDOWN_EVENT`) are one of the only ways containers can "gracefully" shut down (moby/moby#25982 (comment)).

This was verified by making a simple `main()` which implements the same code as in `ExampleNotify_allSignals` but in a `for` loop, building a `main.exe`, running that in a container, then doing `docker kill -sTERM` on said container.  The program prints `Got signal: SIGTERM`, then exits after the aforementioned timeout, as expected.  Behavior before this patch is that the program gets no notification (and thus no output) but still exits after the timeout.

Fixes #7479

Change-Id: I2af79421cd484a0fbb9467bb7ddb5f0e8bc3610e
GitHub-Last-Rev: 9e05d63
GitHub-Pull-Request: #33311
Reviewed-on: https://go-review.googlesource.com/c/go/+/187739
Run-TryBot: Alex Brainman <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
Reviewed-by: Alex Brainman <[email protected]>

Author: tianon

src/os/signal/doc.go

@@ -211,6 +211,14 @@ will cause os.Interrupt to be sent on the channel, and the program will
 not exit. If Reset is called, or Stop is called on all channels passed
 to Notify, then the default behavior will be restored.
 
+Additionally, if Notify is called, and Windows sends CTRL_CLOSE_EVENT,
+CTRL_LOGOFF_EVENT or CTRL_SHUTDOWN_EVENT to the process, Notify will
+return syscall.SIGTERM. Unlike Control-C and Control-Break, Notify does
+not change process behavior when either CTRL_CLOSE_EVENT,
+CTRL_LOGOFF_EVENT or CTRL_SHUTDOWN_EVENT is received - the process will
+still get terminated unless it exits. But receiving syscall.SIGTERM will
+give the process an opportunity to clean up before termination.
+
 Plan 9
 
 On Plan 9, signals have type syscall.Note, which is a string. Calling

src/runtime/defs_windows.go

@@ -41,9 +41,13 @@ const (
 	DUPLICATE_SAME_ACCESS   = C.DUPLICATE_SAME_ACCESS
 	THREAD_PRIORITY_HIGHEST = C.THREAD_PRIORITY_HIGHEST
 
-	SIGINT           = C.SIGINT
-	CTRL_C_EVENT     = C.CTRL_C_EVENT
-	CTRL_BREAK_EVENT = C.CTRL_BREAK_EVENT
+	SIGINT              = C.SIGINT
+	SIGTERM             = C.SIGTERM
+	CTRL_C_EVENT        = C.CTRL_C_EVENT
+	CTRL_BREAK_EVENT    = C.CTRL_BREAK_EVENT
+	CTRL_CLOSE_EVENT    = C.CTRL_CLOSE_EVENT
+	CTRL_LOGOFF_EVENT   = C.CTRL_LOGOFF_EVENT
+	CTRL_SHUTDOWN_EVENT = C.CTRL_SHUTDOWN_EVENT
 
 	CONTEXT_CONTROL = C.CONTEXT_CONTROL
 	CONTEXT_FULL    = C.CONTEXT_FULL

src/runtime/defs_windows_386.go

@@ -15,9 +15,13 @@ const (
 	_DUPLICATE_SAME_ACCESS   = 0x2
 	_THREAD_PRIORITY_HIGHEST = 0x2
 
-	_SIGINT           = 0x2
-	_CTRL_C_EVENT     = 0x0
-	_CTRL_BREAK_EVENT = 0x1
+	_SIGINT              = 0x2
+	_SIGTERM             = 0xF
+	_CTRL_C_EVENT        = 0x0
+	_CTRL_BREAK_EVENT    = 0x1
+	_CTRL_CLOSE_EVENT    = 0x2
+	_CTRL_LOGOFF_EVENT   = 0x5
+	_CTRL_SHUTDOWN_EVENT = 0x6
 
 	_CONTEXT_CONTROL = 0x10001
 	_CONTEXT_FULL    = 0x10007

src/runtime/defs_windows_amd64.go

@@ -15,9 +15,13 @@ const (
 	_DUPLICATE_SAME_ACCESS   = 0x2
 	_THREAD_PRIORITY_HIGHEST = 0x2
 
-	_SIGINT           = 0x2
-	_CTRL_C_EVENT     = 0x0
-	_CTRL_BREAK_EVENT = 0x1
+	_SIGINT              = 0x2
+	_SIGTERM             = 0xF
+	_CTRL_C_EVENT        = 0x0
+	_CTRL_BREAK_EVENT    = 0x1
+	_CTRL_CLOSE_EVENT    = 0x2
+	_CTRL_LOGOFF_EVENT   = 0x5
+	_CTRL_SHUTDOWN_EVENT = 0x6
 
 	_CONTEXT_CONTROL = 0x100001
 	_CONTEXT_FULL    = 0x10000b

src/runtime/defs_windows_arm.go

@@ -16,9 +16,13 @@ const (
 	_DUPLICATE_SAME_ACCESS   = 0x2
 	_THREAD_PRIORITY_HIGHEST = 0x2
 
-	_SIGINT           = 0x2
-	_CTRL_C_EVENT     = 0x0
-	_CTRL_BREAK_EVENT = 0x1
+	_SIGINT              = 0x2
+	_SIGTERM             = 0xF
+	_CTRL_C_EVENT        = 0x0
+	_CTRL_BREAK_EVENT    = 0x1
+	_CTRL_CLOSE_EVENT    = 0x2
+	_CTRL_LOGOFF_EVENT   = 0x5
+	_CTRL_SHUTDOWN_EVENT = 0x6
 
 	_CONTEXT_CONTROL = 0x10001
 	_CONTEXT_FULL    = 0x10007

src/runtime/os_windows.go

@@ -894,6 +894,8 @@ func ctrlhandler1(_type uint32) uint32 {
 	switch _type {
 	case _CTRL_C_EVENT, _CTRL_BREAK_EVENT:
 		s = _SIGINT
+	case _CTRL_CLOSE_EVENT, _CTRL_LOGOFF_EVENT, _CTRL_SHUTDOWN_EVENT:
+		s = _SIGTERM
 	default:
 		return 0
 	}

src/syscall/types_windows.go

@@ -176,8 +176,11 @@ const (
 	FILE_MAP_READ    = 0x04
 	FILE_MAP_EXECUTE = 0x20
 
-	CTRL_C_EVENT     = 0
-	CTRL_BREAK_EVENT = 1
+	CTRL_C_EVENT        = 0
+	CTRL_BREAK_EVENT    = 1
+	CTRL_CLOSE_EVENT    = 2
+	CTRL_LOGOFF_EVENT   = 5
+	CTRL_SHUTDOWN_EVENT = 6
 )
 
 const (