MapTool Memory Usage: Difference between revisions

Latest revision as of 23:59, 7 March 2023

INTERMEDIATE
THIS IS AN INTERMEDIATE ARTICLE

How Maptool Uses Memory

When MapTool starts, the Java virtual machine (the program that lets MapTool run on your computer!) configures a number of settings for the program. Three of these settings affect the memory given to MapTool: heap memory (the memory MapTool uses to store data and resources), and stack memory (the amount of memory threads are allowed to use).

Heap memory

The heap memory allocated to MapTool indicates how much memory MapTool uses to store objects (maps, tokens, image files, macros, etc.) Heap memory allocation is controlled by two options: -Xms sets the starting heap size (the initial amount of memory MapTool is allocated) and -Xmx sets the maximum heap size (the maximum amount of memory MapTool is allowed to access).

If you set the maximum heap size too low, MapTool may run out of memory and crash, freeze, or have other problems. MapTool clients that are connecting to a server should use the same memory settings as the server when possible; otherwise clients may freeze or lose connection when using larger or more complex maps.

Stack memory

The stack memory is the amount of memory each thread is given; threads are sub-processes that handle application functions like network access, macro execution, and drawing the UI. Stack memory allocation is controlled by one option: -Xss sets the stack size (each thread is given exactly the amount specified; there is no starting or maximum stack size).

Some macro frameworks will require larger stack sizes as they perform more complex calculations and functions; they will usually specify their stack requirements. If a thread runs out of stack memory you will see a StackOverflow error and the macro will not work.

Configuring memory allocation for MapTool

In the beginning, MapTool used whatever default stack size and heap size Java felt like setting. The actual amount varied from 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 the stack size to compensate. As frameworks and maps became larger and more complex, users began adjusting the maximum heap size.

The amount of memory is specified in kilobytes or megabytes; "512K" is 512 kilobytes, while "512M" is 512 megabytes.

WARNING: Stack memory is allocated in addition to heap memory and each thread receives the same amount of stack memory. If you set the stack memory allocation too high, the Java VM can consume far more memory than is necessary which will affect overall computer performance.

See MapTool Preferences#JVM Memory Settings for instructions on configuring memory allocation for MapTool.

If you want to run MapTool twice on OS X ...

You might want this for testing purposes, or perhaps you're using a dual-monitor setup where one screen shows MapTool running as a GM and the other shows MapTool running as a Player (such as a HDTV or LCD projector). In other words, you open MapTool once and start a server, then open it again and connect to the server as a client.

Open Terminal
Type open -n "MapTool.app" (or whatever name your MapTool is saved as) and press Enter

Otherwise, when you double-click an application on OS X it simply re-activates the application window that's already running. I don't know of any way of running open -n from the GUI although it would be a pretty simple AppleScript program. (It looks like it's solved here: http://superuser.com/questions/67190/how-can-i-get-an-dock-icon-to-launch-a-program-multiple-times And then this page has a description of how to do the same thing with a Ctrl-Click menu option: http://lifehacker.com/#!5766390/how-to-open-two-instances-of-an-application-in-os-x )

As MapTool is quite a small program, another way to do it is just duplicating and renaming the program (as "MapTool-client" for instance). This would not usually be a clean way to handle it, but again, it's a small software. The good point is you now have two programs with different names. Once the two are launched, it's easy to tell which is which in the Dock or when command-tabbing to switch from one to the other.

@@ Line 1: / Line 1: @@
-==What is the Stack?==
+{{Intermediate}}
+==How Maptool Uses Memory==
+When MapTool starts, the Java virtual machine (the program that lets MapTool run on your computer!) configures a number of settings for the program. Three of these settings affect the memory given to MapTool: ''heap memory'' (the memory MapTool uses to store data and resources), and ''stack memory'' (the amount of memory threads are allowed to use).
-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'''.
+===Heap memory===
+The heap memory allocated to MapTool indicates how much memory MapTool uses to store objects (maps, tokens, image files, macros, etc.) Heap memory allocation is controlled by two options: <code>-Xms</code> sets the ''starting heap size'' (the initial amount of memory MapTool is allocated) and <code>-Xmx</code> sets the ''maximum heap size '' (the maximum amount of memory MapTool is allowed to access).
-===Main Memory Allocation===
+If you set the maximum heap size too low, MapTool may run out of memory and crash, freeze, or have other problems. MapTool clients that are connecting to a server should use the same memory settings as the server when possible; otherwise clients may freeze or lose connection when using larger or more complex maps.
-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 memory===
+The stack memory is the amount of memory each ''thread'' is given; threads are sub-processes that handle application functions like network access, macro execution, and drawing the UI. Stack memory allocation is controlled by one option: <code>-Xss</code> sets the ''stack size'' (each thread is given exactly the amount specified; there is no starting or maximum stack size).
-===Stack Size===
+Some macro frameworks will require larger stack sizes as they perform more complex calculations and functions; they will usually specify their stack requirements. If a thread runs out of stack memory you will see a '''StackOverflow''' error and the macro will not work.
-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''.
+==Configuring memory allocation for MapTool==
+In the beginning, MapTool used whatever default stack size and heap size Java felt like setting. The actual amount varied from 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 the stack size to compensate. As frameworks and maps became larger and more complex, users began adjusting the maximum heap size.
-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.
+The amount of memory is specified in kilobytes or megabytes; "512K" is 512 kilobytes, while "512M" is 512 megabytes.
-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.
+<font color="red">'''WARNING'''</font>: '''Stack memory is allocated in addition to heap memory and ''each thread receives the same amount of stack memory.'' If you set the stack memory allocation too high, the Java VM can consume far more memory than is necessary which will affect overall computer performance.
-==Configuring the Stack==
+See [[MapTool Preferences#JVM Memory Settings]] for instructions on configuring memory allocation for MapTool.
-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.
+==If you want to run MapTool twice on OS X ...==
-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.
+You might want this for testing purposes, or perhaps you're using a dual-monitor setup where one screen shows MapTool running as a GM and the other shows MapTool running as a Player (such as a HDTV or LCD projector).  In other words, you open MapTool once and start a server, then open it again and connect to the server as a client.
-===Setting the Stack Size in a .BAT or .SH File===
+# Open '''Terminal'''
+# Type {{code|open -n "MapTool.app"}} (or whatever name your MapTool is saved as) and press '''Enter'''
-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:
+Otherwise, when you double-click an application on OS X it simply re-activates the application window that's already running.  I don't know of any way of running {{code|open -n}} from the GUI although it would be a pretty simple AppleScript program.  (It looks like it's solved here:  http://superuser.com/questions/67190/how-can-i-get-an-dock-icon-to-launch-a-program-multiple-times  And then this page has a description of how to do the same thing with a Ctrl-Click menu option: http://lifehacker.com/#!5766390/how-to-open-two-instances-of-an-application-in-os-x )
-{{code|javaw -Xmx512M -Xss512K -jar maptool-*.jar run}}
+As MapTool is quite a small program, another way to do it is just duplicating and renaming the program (as "MapTool-client" for instance). This would not usually be a clean way to handle it, but again, it's a small software. The good point is you now have two programs with different names. Once the two are launched, it's easy to tell which is which in the Dock or when command-tabbing to switch from one to the other.
-The critical pieces here are the ones that begin with {{code|-X}}. The first, {{code|-Xmx512M}} indicates how much main memory (in this case, 512MB) is allocated to the Java virtual machine.
+[[Category:MapTool]][[Category:Tutorial]]
-The second, {{code|-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 {{code|-Xss512K}} is absent. To set the stack size allocated (overriding the defaults that are picked by Java or the value indicated), do the following:
-. Open the batch file in a text editor like Notepad.
-. Edit the {{code|-Xss512K}} line to be another value, for instance, {{code|-Xss1M}} or {{code|-Xss2M}} (M is for megabytes, K is for kilobytes).
-. Save the file, and then start MapTool using that batch file.
-<font color="red">'''WARNING'''</font>: When you are changing the stack size, the best settings are usually 512K, 1M, or 2M. <font color="red">'''DO NOT set it to 512M'''!</font> 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.
-# Go to [http://www.rptools.net/index.php?page=launch The Launch Page]
-# Click the '''CUSTOMIZATION''' link.
-# Enter the values you want to use when you WebStart one of the applications.
-# 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 <code>initial-heap-size</code> entry and the <code>-Xms</code> entry
-* To change the maximum memory heap size, change the <code>max-heap-size</code> entry and the <code>-Xmx</code> entry
-* To change the stack memory size, change the <code>-Xss</code> 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 [http://www.rptools.net 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 [http://www.rptools.net/index.php?page=launch 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.
-# Ctrl-click (or right-click) on the application icon (the filename should end with .app).
-# Choose Show Package Contents and a Finder window will open.
-# Open the Contents folder and locate the Info.plist file.
-# Ctrl-click (or right-click) on that file and choose Open With > Other...
-# In the Choose Application dialog that opens, locate TextEdit and double-click on it.
-# 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>
-# 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.
-# Use Cmd-Q and then choose Save. You can close the Finder window that opened as well.
-You're all done!
-[[Category:MapTool]]