MapTool Memory Usage

From RPTools Wiki
Revision as of 02:40, 24 December 2010 by JElmore (talk | contribs) (Added section on modifying the .jnlp file)
Jump to navigation Jump to search

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 or .SH 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). 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.

If you have a saved .jnlp (WebStart) file, you can edit the memory settings by hand.

  • Open the .jnlp file in a text editor
  • Look for the following section (the actual memory values may differ in your copy):
   <j2se version="1.5+"
       initial-heap-size="64m"
       max-heap-size="512m"
       java-vm-args="-Xmx512m -Xms64m -Xss2m"/>
  • To change the starting memory heap size, change the initial-heap-size entry and the -Xms entry
  • To change the maximum memory heap size, change the max-heap-size entry and the -Xmx entry
  • To change the stack memory size, change the -Xss entry
  • Save the .jnlp file

Setting the Stack Size in Mac OSX

These instructions apply to OSX users who have downloaded the .dmg file from the RPTools web site and installed MapTool from it. They were most recently tested on Snow Leopard 10.6.3. OSX users who are running MapTool using the WebStart approach won't need these instructions since the CUSTOMIZATION link on the Launch page allows the memory settings to be configured there.

(Unfortunately, Apple doesn't make this process easy. Their belief seems to be that the application provider should allow these values to be changed from inside the application but they didn't consider that the Java memory settings cannot be changed from inside Java. )

The installer in the .dmg creates what Apple calls an "app" -- it's a directory with the .app filename extension that contains all of the files necessary for the application. This includes the configuration file when the program is Java-based.

Here's the procedure for editing the configuration file (called a property list). Note that I'm describing the technique that uses the OSX TextEdit program because the only property list editor I have on my machine is under the /Developer directory -- which is an optional install for OSX so most people won't have it.

  1. Ctrl-click (or right-click) on the application icon (the filename should end with .app).
  2. Choose Show Package Contents and a Finder window will open.
  3. Open the Contents folder and locate the Info.plist file.
  4. Ctrl-click (or right-click) on that file and choose Open With > Other...
  5. In the Choose Application dialog that opens, locate TextEdit and double-click on it.
  6. The Info.plist file is now open. There is an entry in the file called VMOptions (mine was about two-thirds of the way down the file) that should be changed to match the memory characteristics your GM wants you to use. Here's what mine looks like in case you want a reference for the following steps:
    <key>VMOptions</key>
    <array>
    <string>-Xmx768m</string>
    <string>-Xms64m</string>
    <string>-Xss3m</string>
    </array>
  7. Replace your entries with the example text in Step 6. However, your GM may have directed you to use a particular value for the "maximum memory" setting. If so, replace the 768 number with the new maximum. The GM may also ask you to change the "stack size" amount -- that's the 3 number following the ss. (The 64 number never needs to be changed.) If you have other entries between the <array> and </array> lines, they should be removed because you're specifying completely new values.
  8. Use Cmd-Q and then choose Save. You can close the Finder window that opened as well.

You're all done!

Retrieved from "https://rptools.hyperbooks.com/index.php?title=MapTool_Memory_Usage&oldid=5009"