[commit: ghc] master: Note STM's vulnerability to non-allocating loops (9aa9458)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/9aa94586fde73e818e32e5cc0e6420f6ed36a80b/ghc

>---------------------------------------------------------------

commit 9aa94586fde73e818e32e5cc0e6420f6ed36a80b
Author: Ben Gamari <bgamari.foss at gmail.com>
Date:   Thu Nov 26 00:24:42 2015 +0100

    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


>---------------------------------------------------------------

9aa94586fde73e818e32e5cc0e6420f6ed36a80b
 docs/users_guide/bugs.rst | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/users_guide/bugs.rst b/docs/users_guide/bugs.rst
index 944925a..55551ea 100644
--- 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