Document reasons a HeapOverflow exception may be thrown

Summary

Location of documentation issue: the Haddocks of Control.Exception in base.

The HeapOverflow constructor of AsyncException can be thrown in two cases:

• Asynchronously, when the RTS detects that a limit set by -M has been exceeded.
• Synchronously, when a primop such as newByteArray# fails to allocate the requested memory.

For example, the latter case can arise if a user accidentally tries to allocate an extremely large ByteArray, Text, etc. in a program that is not using -M and perhaps not even using much memory in general (other than the single failed allocation). However the Haddocks for HeapOverflow are unclear and do not mention the second case at all.

Proposed improvements or changes

We should explain this possible source of HeapOverflow exceptions in the Haddocks.

We could also consider using an entirely different exception for primops that fail to allocate memory. After all, this exception is synchronous, and is meaningfully distinct from the case that the program as a whole has exceeded the -M limit. However this would require a CLC proposal and is a nontrivial breaking change. Thus it may be better to rely on the exception provenance work to attach stack traces to such exceptions.