Goal

This document describes the usage of the StoreJanitor.

Description

The implementation is quit simple! Every implementation of a Store can register in the StoreJanitor. It checks in a configurable interval if memory is running low. If low, it greps via Round Robin a victim (Store) and frees xx% of all emlements in this Store. After that the StoreJanitor sleeps and waits for the next iteration.

The StoreJanitor is very useful for web applications that use the store as a in-memory cache. The StoreJanitor helps in avoiding OutOfMemory exceptions.

Configuration

The Store Janitor can be configured with a few options:

  • freememory : How many bytes shall be always free in the JVM (Default: 1mb)
  • heapsize : Maximum possible size of the JVM memory consumption (Default: 64mb)
  • cleanupthreadinterval : How often (sec) shall run the cleanup thread (Default: 10s)
  • adaptivethreadinterval (experimental): Enable adaptive algorithm to determine thread interval (Default: false) When true, cleanupthreadinterval defines the maximum cleanup interval. Cleanup interval then is determined based on the memory fill rate: the faster memory is filled in, and the less free memory is left, the shorter is the cleanup time.
  • threadpriority : priority of the thread (1-10). (Default: 10)
  • percent_to_free : What fraction of the store to free when memory is low (1-100). (Default: 10%)
  • invokegc : Invoke the gc on low memory first (true|false; default: false)

The right configuration is very important, because wrong settings can cause a high system load. Let's have a look at a sample configuration.

Example configuration

  • Tomcat settings in tomcat.sh or tomcat.bat: 
%_RUNJAVA% %TOMCAT_OPTS% -Dtomcat.home="%TOMCAT_HOME%" \
  -Xmx200000000 org.apache.tomcat.startup.Tomcat %2 %3 %4 %5 %6 %7 %8 %9
  • StoreJanitor settings:

The freememory and heapsize paramter always depends on the Xmx parameter. 

  <!--+
      | Store Janitor: the store garbage collector and memory usage controller.
      |
      | Be careful with the heapsize and freememory parameters. Wrong values
      | can cause high cpu usage. Example configuration:
      | Jvm settings:
      |    -Xmx200000000
      | store-janitor settings:
      |    <parameter name="freememory" value="5000000"/>
      |    <parameter name="heapsize" value="196000000"/>
      |
      | It is recommended to have heapsize equal to -Xmx, especially on Sun's
      | JVM which are unable to shrink its heap once it grows above minimum.
      | Freememory should be greater than amount of memory necessary for normal
      | application operation.
      | BUT: The heap size of the memory of the JVM is a little bit less than
      |      the value you specify for -Xmx, so you have to set the heapsize
      |      for the store janitor to a value which is lower (2% less seems
      |      to be a working value).
      +-->
  <store-janitor logger="core.store.janitor">
     <!-- How much free memory shall be available in the jvm -->
     <parameter name="freememory" value="2048000"/>
     <!-- Indicates the limit of the jvm memory consumption. The default max
          heapsize for Sun's JVM is (almost) 64Mb -->
     <parameter name="heapsize" value="66600000"/>
     <!-- How often shall the cleanup thread check memory -->
     <parameter name="cleanupthreadinterval" value="10"/>
     <!-- Experimental adaptive algorithm for cleanup interval
     <parameter name="adaptivethreadinterval" value="true"/>
     -->
     <!-- Indicates the thread priority of the cleanup thread -->
     <parameter name="threadpriority" value="5"/>
     <!-- How much percent of the elements of each registered Store
          shall be removed when low on memory. Default 10% -->
     <parameter name="percent_to_free" value="10"/>
     <!-- Invoke the garbage collector when low memory is reached -->
     <parameter name="invokegc" value="false"/>
  </store-janitor>

It is recommended to have heapsize equal to -Xmx, especially on Sun's JVM which are unable to shrink its heap once it grows above minimum. freememory should be greater than amount of memory necessary for normal application operation. But the heap size of the memory of the JVM is a little bit less than the value you specify for -Xmx, so you have to set the heapsize for the store janitor to a value which is lower (2% less seems to be a working value)

The cleanupthreadinterval defines the interval of the background thread which checks memory in seconds. Also this paramter should configured wisely. A to short interval can cause also a high system load. The threadpriority defines the priority of the background thread. 1 is lowest level and 10 the highest.

The percent_to_free parameter describes, how much percent of the elements of each registered Store shall be removed when low on memory.