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.