Reduce chance of crashes in CTRL-C handler, rework handler example

Inside a signal handler, you cannot allocate memory because the signal
handler, being implemented with a C
[`signal`](https://en.cppreference.com/w/c/program/signal) call, can be
called _during_ a memory allocation - when that happens, the CTRL-C
handler causes a segfault and/or other inconsistent state.

Similarly, the call can happen from a non-nim thread or inside a C
library function call etc, most of which do not support reentrancy and
therefore cannot be called _from_ a signal handler.

The stack trace facility used in the default handler is unfortunately
beyond fixing without more significant refactoring since it uses
garbage-collected types in its API and implementation, but we can at
least allocate the buffer outside of the signal handler itself -
hopefully, this should reduce the frequency of crashes, if nothing else.

It will still crash from time to time on Windows in particular, but
since we're about to quit without cleanup, the loss of functionality is
simited (ie the stack trace will not show and a crash dump will happen
which the OS will notice).

Finally, the example of a ctrl-c handler performs the same mistake of
calling `echo` which is not well-defined - replace it with an example
that is mostly correct (except maybe for the lack of `volatile` for the
`stop` variable).

Author: arnetheduck

lib/system.nim

@@ -2192,22 +2192,37 @@ when not defined(js):
     when declared(initGC): initGC()
 
 when notJSnotNims:
-  proc setControlCHook*(hook: proc () {.noconv.})
+  proc setControlCHook*(hook: proc () {.noconv.}) {.raises: [], gcsafe.}
     ## Allows you to override the behaviour of your application when CTRL+C
     ## is pressed. Only one such hook is supported.
-    ## Example:
     ##
-    ##   ```nim
+    ## The handler runs inside a C signal handler and comes with similar
+    ## limitations.
+    ##
+    ## Allocating memory and interacting with most system calls, including using
+    ## `echo`, `string`, `seq`, raising or catching exceptions etc is undefined
+    ## behavior and will likely lead to application crashes.
+    ##
+    ## The OS may call the ctrl-c handler from any thread, including threads
+    ## that were not created by Nim, such as happens on Windows.
+    ##
+    ## ## Example:
+    ##
+    ## ```nim
+    ##   var stop: Atomic[bool]
     ##   proc ctrlc() {.noconv.} =
-    ##     echo "Ctrl+C fired!"
-    ##     # do clean up stuff
-    ##     quit()
+    ##     # Using atomics types is safe!
+    ##     stop.store(true)
     ##
     ##   setControlCHook(ctrlc)
+    ##
+    ##   while not stop.load():
+    ##     echo "Still running.."
+    ##     sleep(1000)
     ##   ```
 
   when not defined(noSignalHandler) and not defined(useNimRtl):
-    proc unsetControlCHook*()
+    proc unsetControlCHook*() {.raises: [], gcsafe.}
       ## Reverts a call to setControlCHook.
 
   when hostOS != "standalone":

lib/system/excpt.nim

@@ -58,6 +58,7 @@ proc showErrorMessage(data: cstring, length: int) {.gcsafe, raises: [].} =
       writeToStdErr(data, length)
 
 proc showErrorMessage2(data: string) {.inline.} =
+  # TODO showErrorMessage will turn it back to a string when a hook is set (!)
   showErrorMessage(data.cstring, data.len)
 
 proc chckIndx(i, a, b: int): int {.inline, compilerproc, benign.}
@@ -619,6 +620,18 @@ when not defined(noSignalHandler) and not defined(useNimRtl):
   type Sighandler = proc (a: cint) {.noconv, benign.}
     # xxx factor with ansi_c.CSighandlerT, posix.Sighandler
 
+  # TODO this allocation happens in the main thread while the CTRL-C handler
+  #      runs in any thread - since we're about to quit, hopefully nobody will
+  #      notice.
+  #      32kb is hopefully enough to not cause further allocations, since
+  #      allocations are not well-defined in a signal handler.
+  #      Unfortunately, `showErrorMessage2` and `rawWriteStackTrace` may still
+  #      perform allocations on their own which will continue to cause crashes.
+  #      Fixing this requires changing the API which in turn requires a larger
+  #      refactor of the stack trace handling mechanism, including its support
+  #      for libbacktrace.
+  var sigHandlerBuf = newStringOfCap(32*1024)
+
   proc signalHandler(sign: cint) {.exportc: "signalHandler", noconv.} =
     template processSignal(s, action: untyped) {.dirty.} =
       if s == SIGINT: action("SIGINT: Interrupted by Ctrl-C.\n")
@@ -643,10 +656,9 @@ when not defined(noSignalHandler) and not defined(useNimRtl):
       logPendingOps()
     when hasSomeStackTrace:
       when not usesDestructors: GC_disable()
-      var buf = newStringOfCap(2000)
-      rawWriteStackTrace(buf)
-      processSignal(sign, buf.add) # nice hu? currying a la Nim :-)
-      showErrorMessage2(buf)
+      rawWriteStackTrace(sigHandlerBuf)
+      processSignal(sign, sigHandlerBuf.add) # nice hu? currying a la Nim :-)
+      showErrorMessage2(sigHandlerBuf)
       when not usesDestructors: GC_enable()
     else:
       var msg: cstring