Docs on System.exit, debugging

Author: adamw

doc/other/best-practices.md

@@ -46,3 +46,9 @@ Accidental concurrency is often cited as a problem with using `Future`s: if you
 a method returns Ox's `Fork`. Hence, avoid returning `Fork`s from methods. Instead, model concurrency on the caller's
 side - if something should be run in parallel, the caller can do so, using `supervised` and `fork`, and by calling
 blocking methods within the forks.
+
+## Debugging virtual threads
+
+Virtual threads are normally not visible when using tools such as `jstack` or IntelliJ's debugger. To inspect their
+stack traces, you'll need to create a thread dump to a file using `jcmd [pid] Thread.dump_to_file [file]`, or use
+Intellij's thread dump utility, when paused in the debugger.

doc/utils/oxapp.md

@@ -24,6 +24,12 @@ When the application receives a SIGINT/SIGTERM, e.g. due to a CTRL+C, the root s
 forks) are interrupted. This allows for a clean shutdown: any resources that are attached to scopes, or managed using 
 `try-finally` blocks, are released. Application shutdown is handled by adding a `Runtime.addShutdownHook`.
 
+```{warning}
+When using `OxApp`, within an Ox-managed fork (thread), do not use `System.exit` or `sys.exit` to shut down your 
+application. This will cause a deadlock with the cleanup process. For more details see 
+[#368](https://github.com/softwaremill/ox/issues/368).
+```
+
 In the code below, the resource is released when the application is interrupted:
 
 ```scala mdoc:compile-only

generated-doc/out/other/best-practices.md

@@ -46,3 +46,9 @@ Accidental concurrency is often cited as a problem with using `Future`s: if you
 a method returns Ox's `Fork`. Hence, avoid returning `Fork`s from methods. Instead, model concurrency on the caller's
 side - if something should be run in parallel, the caller can do so, using `supervised` and `fork`, and by calling
 blocking methods within the forks.
+
+## Debugging virtual threads
+
+Virtual threads are normally not visible when using tools such as `jstack` or IntelliJ's debugger. To inspect their
+stack traces, you'll need to create a thread dump to a file using `jcmd [pid] Thread.dump_to_file [file]`, or use
+Intellij's thread dump utility, when paused in the debugger.

generated-doc/out/utils/oxapp.md

@@ -24,6 +24,12 @@ When the application receives a SIGINT/SIGTERM, e.g. due to a CTRL+C, the root s
 forks) are interrupted. This allows for a clean shutdown: any resources that are attached to scopes, or managed using 
 `try-finally` blocks, are released. Application shutdown is handled by adding a `Runtime.addShutdownHook`.
 
+```{warning}
+When using `OxApp`, within an Ox-managed fork (thread), do not use `System.exit` or `sys.exit` to shut down your 
+application. This will cause a deadlock with the cleanup process. For more details see 
+[#368](https://github.com/softwaremill/ox/issues/368).
+```
+
 In the code below, the resource is released when the application is interrupted:
 
 ```scala