Built-In Sizing Computation and Enforcement

Internal Ehcache mechanisms track data-element sizes and enforce the limits set by CacheManager sizing pools.

Elements put in a memory-limited cache will have their memory sizes measured. The entire Element instance added to the cache is measured, including key and value, as well as the memory footprint of adding that instance to internal data structures. Key and value are measured as object graphs – each reference is followed and the object reference also measured. This goes on recursively.

Shared references will be measured by each class that references it. This will result in an overstatement. Shared references should therefore be ignored.

For the purposes of measurement, references can be ignored using the @IgnoreSizeOf annotation. The annotation may be declared at the class level, on a field, or on a package. You can also specify a file containing the fully qualified names of classes, fields, and packages to be ignored.

This annotation is not inherited, and must be added to any subclasses that should also be excluded from sizing.

The following example shows how to ignore the Dog class.

@IgnoreSizeOf
public class Dog {
private Gender gender;
private String name;
}

The following example shows how to ignore the sharedInstance field.

public class MyCacheEntry {
@IgnoreSizeOf
private final SharedClass sharedInstance;
...
}

Packages may be also ignored if you add the @IgnoreSizeOf annotation to appropriate package-info.java of the desired package. Here is a sample package-info.java for and in the com.pany.ignore package:

@IgnoreSizeOf
package com.pany.ignore;
import net.sf.ehcache.pool.sizeof.filter.IgnoreSizeOf;

Alternatively, you may declare ignored classes and fields in a file and specify a net.sf.ehcache.sizeof.filter system property to point to that file.

# That field references a common graph between all cached entries
com.pany.domain.cache.MyCacheEntry.sharedInstance
# This will ignore all instances of that type
com.pany.domain.SharedState
# This ignores a package
com.pany.example

Note that these measurements and configurations apply only to on-heap storage. Once Elements are moved to disk, they are serialized as byte arrays. The serialized size is then used as the basis for measurement.

As noted above, sizing caches involves traversing object graphs, a process that can be limited with annotations. This process can also be controlled at both the CacheManager and cache levels.

Control how deep the size-of engine can go when sizing on-heap elements by adding the following element at the CacheManager level:

This element has the following attributes

maxDepth – Controls how many linked objects can be visited before the size-of engine takes any action. This attribute is required.

maxDepthExceededBehavior – Specifies what happens when the max depth is exceeded while sizing an object graph:

"continue" – (DEFAULT) Forces the size-of engine to log a warning and continue the sizing operation. If this attribute is not specified, "continue" is the behavior used.

"abort" – Forces the SizeOf engine to abort the sizing, log a warning, and mark the cache as not correctly tracking memory usage. With this setting, Ehcache.hasAbortedSizeOf() returns true.

The SizeOf policy can be configured at the CacheManager level (directly under <ehcache>) and at the cache level (under <cache> or <defaultCache>). The cache policy always overrides the CacheManager if both are set.

Use the <sizeOfPolicy> as a sub-element in any <cache> block to control how deep the size-of engine can go when sizing on-heap elements belonging to the target cache. This cache-level setting overrides the CacheManager size-of setting.

If warnings or errors appear that seem related to size-of measurement (usually caused by the size-of engine walking the graph), generate more log information on sizing activities:

Enable debug logs on net.sf.ehcache.pool.sizeof in your chosen implementation of SLF4J.