Usage:
-XssNNN where NNN is a number indicating the amount of memory. For example
-Xss256m indicates a stack size of 256 megabytes.
The units can be specified as:
• k, K – kilobytes
• m, M – megabytes
• g, G – gigibytes
• t, T – terabytes
WARNING: If a unit is not specified then the number indicates an exact
number of bytes, e.g. -Xss64 means just 64 bytes.
Examples:
Set the stack size to 512 kilobytes:
java -Xss512k
Set the stack size to 2 megabytes:
java -Xss2m
Description:
The -Xss argument controls the size of the Java thread stack. This is an area of
memory allocated to each thread in the JVM, and is distinct from the heap.
The thread stack is used for local variables in the scope of a method. When a
method is called, these local variables and the program position are pushed onto
the stack before jumping to the new method. When that method completes,
the variables and program position from the caller are popped off the stack and
restored.
When the stack is completely full, any attempt to call a method will throw a
StackOverflowError.
Most applications do not need to specify -Xss and will work fine without it.
An application may need to request a larger stack size than the default if it
is implemented with programming patterns based on recursion rather than
iteration. For example an implementation of the factorial function could be
written as:
public static long fact(long n) {
if (n < 2) {
return 1;
}
1
return n * fact(n - 1);
}
This implementation uses O(n) space on the stack – i.e. an amount of
space directly proportional to the input value – and so if called with a very
large input it can grow larger than the available stack space, thus throwing
StackOverflowError.
Rather than increasing the stack size using -Xss, it is usually better to convert a
recursive method to use iteration instead, for example in the following alternative
implementation of factorial:
public static long fact(long n) {
long result = 1;
for (long i = 1; i <= n; i++) {
result *= i;
}
return result;
}
Note that some JVM languages such as Kotlin can use tail-call recursion, which
means that source code written in the recursive style is compiled to bytecode
that uses iteration.
Applications sometimes exceed the available stack space due to coding bugs.
For example a bug in which a method accidentally calls itself without changing
inputs can very quickly exceed the stack. Changing the stack size using -Xss
does not help to fix such bugs.
Default Value:
The -Xss parameter does not have a fixed default value. If not specified then the
value is chosen at runtime appropriately by the JVM, depending on the amount
of physical memory available, the CPU architecture, the JVM mode (i.e. server
or client), and the JVM vendor, implementation and version.
To determine the default settings of a JVM instance the Print Flags Final option
can be used. It will show the settings of all flags including the thread stack size:
java -XX:+PrintFlagsFinal -version
Note that this option produces a lot of output, it will be necessary to search for
the ThreadStackSize value. For example on a device with 16Gb of RAM this
command shows (excerpted):
intx ThreadStackSize 2048 {pd product} {default}
The value shown (2048) is in Kb, i.e. the default stack size for this JVM is 2 Mb.
Errors:
The value of -Xss cannot be higher than the total available physical memory in
the device. The following error results when setting -Xss512T (i.e. 512 terabytes)
on a device with only 16Gb RAM:
Invalid thread stack size: -Xss512T
The specified size exceeds the maximum representable size.
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.
Arguments Related to -Xss;
TODO: link to -Xssi
Related Posts:
• To learn about different memory regions in the Java Virtual Machine, see
this video clip.
• IBM documentation regarding -Xss.
NOTE:
If you have additional comments, interesting experiences or even point of disagreement with this JVM argument description, please leave a comment. Your
insights will help the entire 10+ million java developer community to develop
one standard source of documentation for all the JVM arguments.
Edit your Comment