documentation for "thread blocked indefinitely in an STM transaction"?

[jwaldmann]

I wonder if something could be done to improve understanding of

Prelude Control.Concurrent.STM> atomically $ do v <- newEmptyTMVar; takeTMVar v
*** Exception: thread blocked indefinitely in an STM transaction

How can I

• understand why exactly this exception was thrown (it's not mentioned on https://hackage.haskell.org/package/stm-2.5.0.0/docs/Control-Concurrent-STM-TMVar.html)
• find out what exception this really is (if I want to write a handler for it)

This is not about changing the semantics, just documentation.

A link to https://hackage.haskell.org/package/base-4.11.1.0/docs/Control-Exception-Base.html#t:BlockedIndefinitelyOnSTM would help?

[bgamari]

Adding a reference to https://hackage.haskell.org/package/base-4.11.1.0/docs/Control-Exception-Base.html#t:BlockedIndefinitelyOnSTM in the documentation of any function which might raise this exception sounds reasonable to me. We should do the same for MVars, if we don't already.