[ VM / dart:io ] Update documentation for to warn '--pause-isolates-on-exit' is not respected when `exit` is called
Fixes issue #31747
Change-Id: Id8a5504f5a13c056a8f366e49be3f6e21652a649
Reviewed-on: https://dart-review.googlesource.com/c/89182
Reviewed-by: Siva Annamalai <asiva@google.com>
Commit-Queue: Siva Annamalai <asiva@google.com>
Auto-Submit: Ben Konyi <bkonyi@google.com>
diff --git a/sdk/lib/io/process.dart b/sdk/lib/io/process.dart
index a293b48..4cf78b9 100644
--- a/sdk/lib/io/process.dart
+++ b/sdk/lib/io/process.dart
@@ -21,6 +21,13 @@
* This does not wait for any asynchronous operations to terminate. Using
* [exit] is therefore very likely to lose data.
*
+ * While debugging, the VM will not respect the `--pause-isolates-on-exit`
+ * flag if [exit] is called as invoking this method causes the Dart VM
+ * process to shutdown immediately. To properly break on exit, consider
+ * calling [debugger] from `dart:developer` or [Isolate.pause] from
+ * `dart:isolate` on [Isolate.current] to pause the isolate before
+ * invoking [exit].
+ *
* The handling of exit codes is platform specific.
*
* On Linux and OS X an exit code for normal termination will always
