Note STM's vulnerability to non-allocating loops

Test Plan: Read it

Reviewers: austin, fryguybob

Reviewed By: austin

Subscribers: thomie, fryguybob

Differential Revision: https://phabricator.haskell.org/D1523

GHC Trac Issues: #10639, #367

diff --git a/docs/users_guide/bugs.rst b/docs/users_guide/bugs.rst
index 944925a..55551ea 100644 (file)
--- a/docs/users_guide/bugs.rst
+++ b/docs/users_guide/bugs.rst
@@ -372,12 +372,14 @@ Bugs in GHC
 -  GHC's runtime system implements cooperative multitasking, with
    context switching potentially occurring only when a program
    allocates. This means that programs that do not allocate may never
-   context switch. See :ghc-ticket:`367` for further discussion.
+   context switch. This is especially true of programs using STM, which
+   may deadlock after observing inconsistent state. See :ghc-ticket:`367`
+   for further discussion.
 
    If you are hit by this, you may want to compile the affected module
-   with ``-fno-omit-yields``. This flag ensures that yield points are
-   inserted at every function entrypoint (at the expense of a bit of
-   performance).
+   with ``-fno-omit-yields`` (see :ref:`options-f`). This flag ensures that
+   yield points are inserted at every function entrypoint (at the expense of a
+   bit of performance).
 
 -  GHC can warn about non-exhaustive or overlapping patterns (see
    :ref:`options-sanity`), and usually does so correctly. But not