With large problems, such as Monte Carlo simulations, the Java Virtual Machine (JVM) is likely to exceed the maximum memory. Even if you increase the heap space by using the option -Xmx when starting the JVM with a command line, some problems might simply be too big for what your module can do.

When the JVM is about to exceed the maximum memory, it calls the garbage collector in order to clear out all the objects that are no longer needed. If this call fails to provide free space, the JVM will eventually throw a java.lang.OutOfMemoryError. At this point, it is unfortunately too late. The user interface usually does not respond well and there is nothing to do except to close the application.

This class is used to control the memory before a OutOfMemoryError object is thrown. The class only has one static method that checks the available memory. If the available memory is below a given threshold, the method throws a ExpectedMemoryCapacityException. This class of exception is derived from RunTimeException. Consequently, there is no need for a method that implements MemoryWatchDog.checkAvailabmeMemory() to throw exceptions.

The threshold can be set either in terms of percentage of the total memory (through MAXIMUM_PROPORTION_USED public static member) or in terms of minimum free space available in MegaBytes (through MINIMUM_FREE_SPACE public static member). By default, MAXIMUM_PROPORTION_USED is set to 0.9 and MINIMUM_FREE_SPACE is set to 10.

Here is an example of implementation adapted to CAPSIS:

@Override
public Step processEvolution(Step s, EvolutionParameters e) throws Exception {
 
     int nbOfGrowthSteps = ((MyModel) e).getNbOfGrowthSteps;
 
     for (int i = 1; i <= nbOfGrowthSteps; i++) {
 
          ...
 
          //do whatever is needed for a single growth step//
 
          ...
 
          MemoryWatchDog.checkAvailableMemory();
 
     }
 
}

As soon as the memory is full up to 90% or the free space is as low as 10 Mg, the method MemoryWatchDog.checkAvailableMemory() throws a ExpectedMemoryCapacityException object. If the exception is caught somewhere in this method or from above methods, a message can be displayed in order to warn the user that the memory is about to be full. The interface remains usable and the user can save his or her project or try again with parameters that result in a smaller problem size.