JVM Configuration

Depending on your usage of Flux, you may find it necessary to configure or tune the JVM to optimize your experience.

The setenv.bat (Windows) and setenv.sh (Unix) scripts that ship with Flux already come configured with our recommended JVM configuration settings. If you are starting Flux in your own JVM, we recommend copying these settings for the ideal performance of Flux (for a typical use case).

However, as with any software system, you might find that your particular needs require changing the JVM settings. If you do need to configure the JVM, the settings you will typically need to adjust are listed below.

Heap (Memory) Settings

The heap space is controlled by two parameters, for the maximum and minimum memory size settings.

To set the maximum amount of RAM memory that the JVM (including Flux) can use, set the Xmx parameter like:

-Xmx512m

Memory settings are set by specifying a number, followed by the ‘m’ character (indicating that the number is specified in MB). Other acceptable values might be “-Xmx1024m” or “-Xmx2048m”, for example.

For Flux, we recommend a heap size of at least 512m. Some features of Flux that consume memory (like Caching) might require a larger value, especially if you are using non-default values when configuring those features. If you are experiencing out-of-memory errors with Flux, try increasing the Xmx parameter value or decreasing the cache size.

If you do not set the Xmx parameter, the default value is determined by the JVM. In Java 1.4 and earlier, the default value was 64M. This is not large enough for Flux, so take care to ensure that this parameter is set. In later Java versions as seen here for Java 1.6, the default maximum heap size is half of the physical memory up to a physical memory size of 192 megabytes and otherwise one-fourth of the physical memory up to a physical memory size of 1 gigabyte.

• For example, if your machine has 128 megabytes of physical memory, then the maximum heap size is 64 megabytes, and greater than or equal to 1 gigabyte of physical memory results in a maximum heap size of 256 megabytes.

The maximum heap size is not actually used by the JVM unless your program creates enough objects to require it. A much smaller amount, termed the initial heap size (as set in the -Xms parameter), is allocated during JVM initialization.

Server JVM heap configuration is now the same as the Client, except that the default maximum heap size for 32-bit JVMs is 1 gigabyte, corresponding to a physical memory size of 4 gigabytes, and for 64-bit JVMs is 32 gigabytes, corresponding to a physical memory size of 128 gigabytes.

To set the minimum amount of memory that the JVM can use, set the Xms parameter:

-Xms64m

Flux doesn’t require a minimum heap size to run (the setenv script does not set this parameter by default).

Network Settings

The following settings are related to networking; in particular, the way engines talk to the database and, in a clustered environment, to one another.

The java.net.preferIPv4Stack property indicates whether connections should use IPv4 or IPv6 in this JVM. This is a boolean (true/false) value and is set like:

-Djava.net.preferIPv4Stack=true

This should be set to “true” when using Flux.

The networkaddress.cache.ttl property indicates how long (in seconds) the JVM should cache successful name lookups for the name service. This is set like this:

-Dnetworkaddress.cache.ttl=900

We recommend setting this value to 900 (nine-hundred seconds).

The sun.net.client.defaultConnectTimeout, sun.net.client.defaultReadTimeout, and sun.rmi.transport.tcp.readTimeout indicate how long the JVM should wait before timing out attempted network connections. These settings are primarily used when engines are communicating with one another in a cluster, and indicate how long an engine should wait to connect to another engine over the network before falling back and using the database.

These values are specified in milliseconds like:

-Dsun.net.client.defaultConnectTimeout=120000 -Dsun.net.client.defaultReadTimeout=120000 -Dsun.rmi.transport.tcp.readTimeout=120000

We recommend setting all of these values to 120000 (two minutes).

Derby Database Settings

Flux uses the built-in Derby database by default. When using the built-in Derby database, Flux automatically configures Derby to ensure the best performance for the Flux engine in terms of deadlocking, speed, and memory usage. The following settings are included in setenv for use with the Derby database:

-Dderby.locks.escalationThreshold=2147483647 -Dderby.locks.deadlockTimeout=300 -Dderby.locks.waitTimeout=300 -Dderby.storage.initialPages=500 -Dderby.storage.pageCacheSize=10000

These settings should not be changed when using the Derby database with Flux.

In typical scenarios, Derby is expected to occupy about 300 MB of heap memory space. Derby is appropriate for a light load of workflows and file transfers. If you are using Flux for anything but a light workload, we recommend configuring Flux to run with an external database.

Java Garbage Collector (GC) Settings

Flux, in instances where significant use of prescripts and postscripts are present in a workflow that loops back on itself (i.e., a looping workflow), may exhibit a large heap space requirement and spend 5–20% of its time in garbage collection. Applying the following JVM settings reduces the garbage collection activity to less than 5% and keeps the heap size in check. Note: this is not a common issue in most Flux installations.

-XX:+UseConcMarkSweepGC -XX:+UseParNewGC