43.9. $overheadPercentExitValue and $overheadTooHighExcpt

When MAINSAIL runs low on memory, it may perform garbage collection more and more frequently, until the program spends virtually all of its time on memory management and none on useful work. This behavior is known as thrashing. To detect thrashing, the system variable $overheadPercentExitValue is provided.

A program may set $overheadPercentExitValue to any value in the range 1 to 100, inclusive (a value of 0 disables $overheadPercentExitValue checking). When MAINSAIL attempts to allocate memory and the percentage of time spent in memory management exceeds the value, the exception $overheadTooHighExcpt is raised. If the exception is handled, MAINSAIL continues execution (the handler may free up some memory, or modify $overheadPercentExitValue); otherwise, MAINSAIL exits. Before the $overheadTooHighExcpt is raised, MAINSAIL sets the value of $overheadPercentExitValue to 0. The user program must explicitly set $overheadPercentExitValue to a non-zero value to have the exception raised again (assuming the program handles the exception).

When $overheadTooHighExcpt is raised, $exceptionStringArg1 is cvs($overheadPercentExitValue) before it was set to 0; $exceptionStringArg2 is cvs(numPages), where numPages is the number of pages that need to be allocated. If the program handles the exception, and sets $overheadPercentExitValue to a non-zero value, the exception will not be raised again for the particular allocation of numPages that just caused it to be raised, but it could be raised for subsequent allocations.

Once the overhead percent reaches a certain value, it may take some time for it to decrease significantly, so the handler of $overheadTooHighExcpt should probably not set $overheadPercentExitValue back to its original value since this is likely to cause the exception to be raised again very soon (unless the handler freed a large amount of memory, or the program runs for a significant amount of time before needing much more memory).

A concept somewhat similar to $overheadTooHighExcpt is $almostOutOfMemoryExcpt, which is raised if MAINSAIL is running low on memory; see Section 30.10.