From 28de32c8b274d5eb55dd4a777abbcfe1945861d5 Mon Sep 17 00:00:00 2001 From: Timothee Cour Date: Mon, 5 Apr 2021 12:19:17 -0700 Subject: document caveats of quit (#17648) --- lib/system.nim | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'lib') diff --git a/lib/system.nim b/lib/system.nim index ba27da0c7..bd9ae2762 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -1185,10 +1185,6 @@ when defined(nimdoc): ## ## Before stopping the program the "exit procedures" are called in the ## opposite order they were added with `addExitProc `_. - ## `quit` never returns and ignores any exception that may have been raised - ## by the quit procedures. It does *not* call the garbage collector to free - ## all the memory, unless a quit procedure calls `GC_fullCollect - ## <#GC_fullCollect>`_. ## ## The proc `quit(QuitSuccess)` is called implicitly when your nim ## program finishes without incident for platforms where this is the @@ -1199,6 +1195,14 @@ when defined(nimdoc): ## have any compile time effect. If you need to stop the compiler inside a ## macro, use the `error `_ or `fatal ## `_ pragmas. + ## + ## .. danger:: In almost all cases, in particular in library code, prefer + ## alternatives, e.g. `doAssert false` or raise a `Defect`. + ## `quit` bypasses regular control flow in particular `defer`, + ## `try`, `catch`, `finally` and `destructors`, and exceptions that may have been + ## raised by an `addExitProc` proc, as well as cleanup code in other threads. + ## It does *not* call the garbage collector to free all the memory, + ## unless an `addExitProc` proc calls `GC_fullCollect <#GC_fullCollect>`_. elif defined(genode): include genode/env -- cgit 1.4.1-2-gfad0