Docs

Author: adamw

doc/other/best-practices.md

@@ -56,16 +56,18 @@ Intellij's thread dump utility, when paused in the debugger.
 ## Dealing with uninterruptible stdin
 
 Some I/O operations, like reading from stdin, block the thread on the `read` syscall and only unblock when data becomes
-available or the stream is closed. The problem with stdin specifically is that it can't be easily closed, making it
-impossible to interrupt such operations directly. This pattern extends to other similar blocking operations that behave
-like stdin.
+available or the stream is closed; such a call is uninterruptible. The problem with stdin specifically is that it can't
+be easily closed, making it impossible to interrupt such operations directly. This pattern extends to other similar
+blocking operations that behave like stdin.
 
 The solution is to delegate the blocking operation to a separate thread and use a [channel](../streaming/channels.md)
-for communication. This thread cannot be managed by Ox as Ox always attempts to run clean up when work is done and that 
-means interrupting all forks living in the scope that's getting shut down. Blocking I/O can't, however, be interrupted 
-on the JVM and the advised way of dealing with that is to just close the resource which in turn makes read/write methods 
-throw an `IOException`. In the case of stdin closing it is usually not what you want to do. To work around that you can
-sacrifice a thread and since receiving from a channel is interruptible, this makes the overall operation interruptible as well:
+for communication. This thread cannot be managed by Ox, as Ox always attempts to run cleanup on application shutdown and
+that means interrupting all forks. Some blocking I/O can't, however, be interrupted on the JVM and the advised way of
+dealing with that is to just close the resource which in turn makes read/write methods throw an `IOException`. In the
+case of stdin closing it is usually not what you want to do. 
+
+To work around that you can sacrifice a thread and since receiving from a channel is interruptible, this makes the
+overall operation interruptible as well:
 
 ```scala
 import ox.*, channels.*
@@ -89,7 +91,7 @@ object stdinSupport:
         throw iex
 ```
 
-This pattern allows you to use stdin (or similar blocking operations) with ox's timeout and interruption mechanisms,
+This pattern allows you to use stdin (or similar blocking operations) with Ox's timeout and interruption mechanisms,
 such as `timeoutOption` or scope cancellation.
 
 Note that for better stdin performance, you can use `Channel.buffered` instead of a rendezvous channel, or even use