Chapter 9: Poly/ML Heap Parameters

The heap is divided into two areas, one for immutable objects and one for mutable objects. In ML, most objects are immutable, that is they cannot be changed once they have been created, for example strings, lists, functions and trees. The only mutable objects are refs, these are objects that can have their contents changed.

The -h flag controls the maximum size of the local heap. The argument to -h is the size in Kb, and must be at least 500. Each of the mutable and immutable areas controlled by the garbage collector is allowed to grow up to the smaller of this heap area limit and an architecture-dependent limit. These architecture-dependent limits are:

	SPARC	POWER
Mutable	32Mb	32Mb
Immutable	160Mb	160Mb

The -mb and -ib flags control the mutable buffer and immutable buffer sizes respectively. The argument to each of these flags is a size in Kb which must be between 100 and the value of the -hflag. These buffers hold new objects created since the last full garbage collection. All new objects are mutable until their contents are fixed, so they are created in the mutable buffer. When this buffer is full a partial garbage collection is needed. This compacts the mutable buffer and moves all immutable objects (the majority) over to the immutable buffer.

The mutable buffer is nearly empty after a partial garbage collection. The immutable buffer fills slowly at each partial garbage collection. When the immutable buffer is more than 90% full, or if the mutable buffer is more than 50% full after the partial garbage collection, then a full garbage collection is performed. The arguments to the -ip and -mp flags control these percentages, and must lie in the range 0 to 100.

The full garbage collection scans the entire heap and compacts all the objects. Then it allocates more memory if needed so that at least the -ib and -mb amounts are free. If it cannot allocate the buffer space then Poly/ML interrupts the computations and reports that the heap is full.

Note: when Poly/ML performs a full garbage collection, it temporarily allocates an auxiliary bitmap on the C stack. This bitmap contains two bits of data for each 32-bit word contained in the Poly/ML heap. For example, using a 64Mb local heap will cause the C stack to grow by 4Mb during a full garbage collection. If Poly/ML is unable to expand the C stack as required - for example, if you have set a stack limit, using the Unix limit stack command, that is too low - it will perform an unceremonious exit.

If you increase the -mb number you will decrease the frequency of partial garbage collections. But each partial garbage collection will scan more objects. A mutable buffer of 1024Kb is a nice balance between collecting too often and pausing for long periods.

If you increase the -ib number you will decrease the frequency of full garbage collections caused by the immutable buffer filling up. An immutable buffer of 1024Kb seems to be a nice balance between causing full garbage collections and wasting memory on the accumulation of dead objects.

If you decrease the -h value it may reduce the swap space requirements of Poly/ML. But if it is reduced too far then Poly/ML will interrupt compilations and report that the heap is full. Poly/ML doesn't exit to Unix, it just returns to the Poly/ML prompt. The heap is considered full when the space required for objects plus the space required for the buffer exceeds the -h limit. This applies to either immutables or mutables.

If you decrease the -ip percentage or decrease the -mp percentage you will increase the frequency of full garbage collections and decrease the frequency of partial garbage collections.

Note: if the -h flag is specified explicitly but the -mb and -ib flags are not present, then they default to the -h value divided by 5. Since this does not take account of the architectural limits then specifying very large -h values can cause the initial area sizes to be too large to successfully start Poly/ML. If this is a problem, you should specify the -ib and -mb flags explicitly.