Skip to content

Latest commit

 

History

History
104 lines (79 loc) · 4.53 KB

README.adoc

File metadata and controls

104 lines (79 loc) · 4.53 KB
Raw

ehcache-sizeofengine

What is this?

This library lets you size Java Object instances in bytes.

SizeOf sizeOf = SizeOf.newInstance(); // (1)
long shallowSize = sizeOf.sizeOf(someObject); // (2)
long deepSize = sizeOf.deepSizeOf(someObject); // (3)

  1. Retrieves one of the multiple engines supported;

  2. Sizes someObject instance in bytes;

  3. Sizes someObject instance in bytes, as well as all objects it references.

The different engines

When retrieving a new SizeOf instance with the static org.ehcache.sizeof.SizeOf.newInstance, the library will try to create of the following engines, in that order:

  1. AgentSizeOf : Which tries to attach an agent to the JVM process and size objects using org.ehcache.sizeof.impl.AgentLoader.instrumentation; otherwise

  2. UnsafeSizeOf : Which will determine Class layouts in memory using sun.misc.Unsafe; or finally

  3. ReflectionSizeOf : Which will introspect Class instances and try determining object sizes that way.

Both the ReflectionSizeOf and the AgentSizeOf approach were very well covered in Dr. Heinz Kabutz’s Java Specialist Newsletter issue #78 and issue #142 respectively. Different JVMs and their configurations may affect these sizes, see blob/master/src/main/java/org/ehcache/sizeof/impl/JvmInformation.java[JvmInformation enum] for more details. Finally, the UnsafeSizeOf, we’ve discovered and, as far as we know, were the first ones to use.

Avoiding sizing certain types

In some cases you want to control how far the deep sizing goes. You can do this using the org.ehcache.sizeof.Filter SPI.

Using existing filter configurators

You simply need to add the jars of the modules that you want along side this project’s jar

Configuring the Filter yourself

In order to ignore fields or instances of certain classes when sizing object graphs, you’ll have to

  1. Create a ServiceLoader project, for net.sf.ehcache.sizeofengine.FilterConfigurator

    • Have your jar contain a text file named META-INF/services/org.ehcache.sizeof.FilterConfigurator

    • The file should contain the fully qualified class name of your implementation

  2. Implement FilterConfigurator's configure method to configure the Filter of classes and fields

  3. put your jar on your application’s classpath, along side of the ehcache jar and this ehcache-sizeofengine jar

  4. Use Ehcache’s Automatic Resource Control for your heap tier

Example

public static final class StupidConfigurator implements FilterConfigurator {

    @Override
    public void configure(final Filter ehcacheFilter) {
        // Will not size any instance of Number, and given the second arg, no subtype neither
        ehcacheFilter.ignoreInstancesOf(Number.class, false);
    }
}

There can be as many FilterConfigurator on the classpath as required, they’ll have configure the filter once. The Filter is shared across all SizeOfEngine instances created.

Using it

Maven

Releases are available from Maven Central.

<dependency>
    <groupId>org.ehcache</groupId>
    <artifactId>sizeof</artifactId>
    <version>${sizeof.version}</version>
</dependency>

Snapshots are available from the Sonatype OSS snapshots repository. In order to access the snapshots, you need to add the following repository to your pom.xml:

<repository>
    <id>sonatype-nexus-snapshots</id>
    <name>Sonatype Nexus Snapshots</name>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    <releases>
        <enabled>false</enabled>
    </releases>
    <snapshots>
        <enabled>true</enabled>
    </snapshots>
</repository>