MapTool Memory Usage

What is the Stack?

When MapTool starts, the Java Virtual Machine (the program that lets MapTool run on your computer!) configures a number of settings for the program. Two of these settings involve the available memory given to MapTool: main memory, and the stack.

Main Memory Allocation

The main memory allocated to MapTool simply indicates how much of your computer's RAM MapTool can play with - if you have, for instance, 2GB of RAM, you can tell MapTool that it can play around with 1GB; likewise if you want, you can say "MapTool can only use 256KB of RAM!"

Stack Size

There is another memory amount that Java sets up when MapTool launches, and this one has to do not with the total amount of memory that MapTool gets, but the amount of memory any particular thread of a program can eat up at a given time. This memory is called the stack.

The stack is especially important when you are using macros to perform calculations: the more complex a macro gets (and some macros can get very complex!) the more stack memory it will consume.

Eventually, a macro can get so complex, it eats up all the stack it is permitted, and then cries out for more. When this happens, you get a Stack Overflow error, and the macro will simply Not Work.

Configuring the Stack

In the beginning, MapTool used whatever default stack size Java felt like setting. The actual amount varied from computer to computer and operating system to operating system, but it was generally enough for the simple macros that were in use at the time.

As the power and flexibility of the macro code increased, macros began to bump up against the limits of the default stack, and users began adjusting their stack size to compensate.

Setting the Stack Size in a .BAT File

One of the ways to start MapTool is via the various batch files that are included when you download and unzip a copy of MapTool. These files are called things like Launch Maptool-512M-Memory.bat (for Windows machines) and Launch MapTool.sh (for Linux and Mac OS X). The number in the filename indicates the amount of main memory allocated to MapTool. The contents of these batch files looks like:

javaw -Xmx512M -Xss512K -jar maptool-*.jar run

The critical pieces here are the ones that begin with -X. The first, -Xmx512M indicates how much main memory (in this case, 512MB) is allocated to the Java virtual machine.

The second, -Xss512K is how much memory is allocated to the stack (the "ss" is for "stack size").

In versions of MapTool prior to 1.3.b54, the -Xss512K is absent. To set the stack size allocated (overriding the defaults that are picked by Java or the value indicated), do the following:

1. Open the batch file in a text editor like Notepad.

2. Edit the -Xss512K line to be another value, for instance, -Xss1M or -Xss2M (M is for megabytes, K is for kilobytes).

3. Save the file, and then start MapTool using that batch file.

WARNING: When you are changing the stack size, the best settings are usually 512K, 1M, or 2M. DO NOT set it to 512M! That will cause Bad Things to happen.

Setting the Stack Size using MapToolLauncher

If you start MapTool with the Windows launcher, the third field is where you can indicate stack size.

The Windows launcher defaults to a 2MB stack, which is perfectly acceptable for pretty much all uses. If you change it, that new value will be saved for the next time.

Setting the Stack Size from WebStart

If you start MapTool using the Java WebStart option, you can change the settings here, too.

1. Go to The Launch Page

2. Click the CUSTOMIZATION link.

3. Enter the values you want to use when you WebStart one of the applications.

4. Click on the links above to start the application you wish to use.