path: root/docs/development/jvm.txt

Java Virtual Machine
====================


This document gathers technical informations about the Java VM to help
Java/Scala developers tuning their runtime settings on the Java VM.


VM Options
----------

* -Xmx option (maximum heap size)

  Heaps larger than 2GB are available starting with J2SE 1.3.1

  Default: 64M (32-bit UNIX and Windows)

* -Xms option (initial heap size)

  Minimum: 1025K (Linux-i586, Solaris-i586), etc.. (see [vm08])
  Default: 2M (32-bit UNIX and Windows)

* -Xss option (thread stack size)

  Minimum: 48K (Linux-i586), 64K (Solaris-i586), etc.. (see [vm08])
  Default: 256K (32-bit UNIX and Windows)

  NB. Stack size under Windows is a link-time setting, so the executable
      (java.exe) as created by Sun has this 256K limit built in. Windows
      however, has a simple utility to modify the stack space of an
      executable (see [vm03]).
      In a command window (or Cygwin shell), use the EDITBIN command to
      permanently modify the executable (WARNING! Do not reduce the stack
      size below 32K, see [vm04])

      EDITBIN /STACK:16000000 C:\Path\To\java.exe


Scala Environment Options
-------------------------

* JAVACMD variable (Java command)

  Scala default: java (v2.x)

* JAVA_OPTS variable (Java options)

  Scala default: -Xmx256M -Xms16M (v2.x)


In the following example, simply replace <jdk> by
"java-1.4", "java-1.5", "java-1.6", "java-1.7" or
"java-ibm-1.5" to experiment with different Java VMs:

> env JAVACMD=/home/linuxsoft/apps/<jdk>/bin/java \
      JAVA_OPTS="-Xmx256M -Xms16M -Xss128k" \
      test/scalatest test/files/shootout/message.scala



Resources
=========


VM Options and Tools
--------------------

[vm01] Some useful -XX options
       http://java.sun.com/javase/technologies/hotspot/vmoptions.jsp

[vm02] jvmstat 3.0
       http://java.sun.com/performance/jvmstat/

[vm03] Modify the actual java.exe executable on Windows
       http://www.eyesopen.com/docs/html/javaprog/node7.html

[vm04] Configuring server stack size
       https://ssa.usyd.edu.au/docs/eassag/eassag20.htm

[vm06] Tuning the Java Runtime System
       http://docs.sun.com/source/817-2180-10/pt_chap5.html

[vm07] JVM Tuning
       http://www.caucho.com/resin-3.0/performance/jvm-tuning.xtp

[vm08] Java HotSpot: load the VM from a non-primordial thread and effects
       on stack and heap limits.
       http://blogs.sun.com/ksrini/entry/hotspot_primordial_thread_jni_stack

[vm09] A Collection of JVM Options (13-Dec-2005)
       http://blogs.sun.com/watt/resource/jvm-options-list.html


Garbage Collection
------------------

[gc01] Tuning Garbage Collection with the 5.0 Java[tm] Virtual Machine
       http://java.sun.com/docs/hotspot/gc5.0/gc_tuning_5.html

[gc02] Tuning Garbage Collection with the 1.4.2 Java[tm] Virtual Machine
       http://java.sun.com/docs/hotspot/gc1.4.2/

[gc03] Tuning Garbage Collection with the 1.3.1 Java[tm] Virtual Machine
       http://java.sun.com/docs/hotspot/gc/

[gc04] Garbage Collector Ergonomics
       http://java.sun.com/j2se/1.5.0/docs/guide/vm/gc-ergonomics.html


$Id$