While creating the UnsafeArrayList, I encountered a problem that I felt I could optimise. The UnsafeArrayList copies objects into off-heap memory, instead of what a normal ArrayList would do, which is to store references to the object in an array on the heap. For example an UnsafeArrayList<FourLong> holds instances of FourLongs, whose fields consume a total of 32 bytes (4×8 bytes) of memory. By design, when set() or get() are called, the UnsafeArrayList copies these 32 bytes into or out of a contiguous segment of memory.

To achieve the copying, sun.misc.Unsafe’s putLong() is repeatedly called, moving 8 bytes at a time. For example, this simple loop will copy a long’s worth of memory each iteration, from src, into dest:

final long COPY_STRIDE = 8;
final Unsafe unsafe = UnsafeHelper.getUnsafe();

public void copy(Object dest, long src) {
	long destOffset = 0;
	long destEnd = UnsafeHelper.sizeOf(dest);

	while (destOffset < dstEnd) {
		unsafe.putLong(dest, dstOffset, unsafe.getLong(src));
		destOffset += COPY_STRIDE;
		src += COPY_STRIDE;
	}
}

Note, we use putLong, not because the UnsafeArrayList is storing objects made up of longs, but because this is the Unsafe method that can copy the most in one go. This putLong method is thus being used as the building block to build a more complex looping copy method. Note, this works great for memory which is aligned on a 8 byte boundary, and the total copy is a multiple of 8 bytes. For the sake of this article, we make the assumption that this is always true.

In the FourLong’s case, the copy method would iterates four times. This is predictable, and occurs every time we get() on a UnsafeArrayList<FourLong> instance. Since this copy loop will be executed every time get() is called, it is worth seeing if we can make it execute faster. A common optimisation is for the developer to manually unroll the loop, avoiding the loop counter, and producing potentially quicker code¹. In this case, manually unrolling the code is not possible because the parameterised type could be any size. For example, a UnsafeArrayList<Point> would only need to copy 8 bytes (two 4 byte ints). You would hope that the JIT would notice the loop always iterates the same number of times (for a particular list), and be able to remove the loop. Sadly, it does not seem to do this, perhaps because the JVM does not know what side effects unsafe.{get,put}Long have. To measure the cost of the looping we compare the previous code to this:

final int COPY_STRIDE = 8;
final Unsafe unsafe = UnsafeHelper.getUnsafe();

public void copy(Object dest, long src) {
	assert(UnsafeHelper.sizeOf(dest) == 4 * COPY_STRIDE)

	long destOffset = 0;

	unsafe.putLong(dest, destOffset, unsafe.getLong(src));
	destOffset += COPY_STRIDE;
	src += COPY_STRIDE;

	unsafe.putLong(dest, destOffset, unsafe.getLong(src));
	destOffset += COPY_STRIDE;
	src += COPY_STRIDE;

	unsafe.putLong(dest, destOffset, unsafe.getLong(src));
	destOffset += COPY_STRIDE;
	src += COPY_STRIDE;

	unsafe.putLong(dest, destOffset, unsafe.getLong(src));
}

When benchmarked, this manually unrolled code runs 2 times faster! This got me thinking, since a particular UnsafeArrayList instance is always going to copy the same sized object, again and again and again, it could perhaps generate bytecode during creation, that unrolled the loop.

Enter Byte Buddy

Thus investigation into Byte Buddy began, a library designed for generating bytecode at runtime. The rest of this article explains how to use Byte Buddy for this goal.

To start, I used Intellij IDEA’s “Show Bytecode” option, to inspect the code generated by my hand unrolled code.

; Initialisation
  ; long destOffset = 0;
  LCONST_0  ; Load the long zero
  LSTORE 4  ; Store it in “destOffset”

; Copy
  ; unsafe.putLong(dest, destOffset, unsafe.getLong(src));
  ALOAD 0  ; Load “this”
  ; The the “unsafe” member from this.
  GETFIELD net/bramp/unsafe/Test.unsafe : Lsun/misc/Unsafe;

  ALOAD 1  ; Load dest
  LLOAD 4  ; Load dstOffset
  ALOAD 0  ; Load this
  ; The the “unsafe” member from this.
  GETFIELD net/bramp/unsafe/Test.unsafe : Lsun/misc/Unsafe;

  LLOAD 2  ; Load src
  ; unsafe.getLong(src), storing result on stack.
  INVOKEVIRTUAL sun/misc/Unsafe.getLong (J)J
  ; unsafe.putLong(dest, dstOffset, {stack result})
  INVOKEVIRTUAL sun/misc/Unsafe.putLong (Ljava/lang/Object;JJ)V

;; Increment
  ; dstOffset += 8;
  LLOAD 4   ; Load dstOffset
  LDC 8     ; Load 8
  LADD      ; Add dstOffset and 8
  LSTORE 4  ; Store result to dstOffset

  ; src += 8;
  LLOAD 2   ; Load src
  LDC 8     ; Load 8
  LADD      ; Add src and 8
  LSTORE 2  ; Store result to src

After reading a primer to bytecode, this generated bytecode looked quite simple. It can be broken up into three steps, initialisation, copy, and increment. At runtime, Byte Buddy can be used to generate bytecode that is an unrolled equivalent, such that there is 1 initialisation step, N copy steps, and N-1 increment steps, where N is based on the size of the object the UnsafeArrayList plans to copy.

Reading through the Byte Buddy API it seems the best way to achieve this is to create an abstract class, which will form the base of a generated class. Then at runtime create an instantiation of this abstract class, specialised with the unrolled copy bytecode.

For example, the base class would look like this:

public abstract class UnsafeCopier {
	protected final Unsafe unsafe;

	public UnsafeCopier(Unsafe unsafe) {
		this.unsafe = checkNotNull(unsafe);
	}

	abstract void copy(Object dest, long src);
}

Leaving us to implement the copy(…) method optimally for the size of object being copied.

Using the Builder pattern I created the UnrolledUnsafeCopierBuilder class. The build() method will calculate the size of the class being copied, then using Byte Buddy generate the copy implementation, and returns a specialised instance UnsafeCopier.

public UnsafeCopier build(Unsafe unsafe) {
	final long length = UnsafeHelper.sizeOf(clazz);

	Class<?> dynamicType = new ByteBuddy()
		.subclass(UnsafeCopier.class)
		.method(named("copy"))
		.intercept(new CopierImplementation(length)).make()
		.load(getClass().getClassLoader(), ClassLoadingStrategy.Default.WRAPPER)
		.getLoaded();

	return (UnsafeCopier) dynamicType
		.getDeclaredConstructor(Unsafe.class)
		.newInstance(unsafe);
}

This begins by calculating the size of the class. Then using a ByteBuddy instance, creates a new dynamicType, which extends UnsafeCopier. This subclass then obtains its copy method with code generated by CopierImplementation(length). Finally, this new dynamicType is used to create an instance of the copier, which is now specialised for copying instances of clazz.

The real meat of the code is in CopierImplementation, which can be explained in pieces:

class CopierImplementation implements ByteCodeAppender, Implementation {

	public static final long COPY_STRIDE = 8;

	final long length;

	public CopierImplementation(long length) {
		this.length = length;
	}

	private StackManipulation buildStack() throws ... {
		...
		final StackManipulation setupStack = ...
		final StackManipulation copyStack = ...
		final StackManipulation incrementStack = ...

		final int iterations = (int) (length / COPY_STRIDE);
		final StackManipulation[] stack = new StackManipulation[1 + 2 * iterations];
		
		stack[0] = setupStack;
		for (int i = 0; i < iterations; i++) {
			stack[i * 2 + 1] = copyStack;
			stack[i * 2 + 2] = incrementStack;
		}

		// Override the last incrementStack with a "return"
		stack[stack.length - 1] = MethodReturn.VOID;

		return new StackManipulation.Compound(stack);
	}

	...
}

Byte Buddy uses StackManipulation objects to define what bytecode to generate. These StackManipulation objects can be built up hierarchically and contain all the bytecode instructions to execute. We define a separate StackManipulation object for each step, and in the buildStack() method combine the steps multiple times into one array. In particular, this stack array contains one initialise step, N copy steps, and N-1 increment steps, with a return instruction on the end.

Recall from the early bytecode listing, that the initialisation was two bytecode operations, a LCONST, and LSTORE. In Byte Buddy, we can thus do the following:

final StackManipulation setupStack = new StackManipulation.Compound(
	LongConstant.ZERO,                       // LCONST_0
	MethodVariableStore.LONG.storeOffset[4]  // LSTORE 4
);

Byte Buddy provides the primitives for most bytecode instructions, and can be built up in these StackManipulation arrays. However, some instructions are missing, for example LADD (needed by the increment step). But it is simple enough to create one from scratch, as shown outside of this article.

Next the copy step is defined which is a few more instructions than the increment, but relatively simple:

final Field unsafeField = UnsafeCopier.class.getDeclaredField("unsafe");
final Method getLongMethod = Unsafe.class.getMethod("getLong", long.class);
final Method putLongMethod = Unsafe.class.getMethod("putLong",Object.class, long.class, long.class);

final StackManipulation copyStack = new StackManipulation.Compound(
	// unsafe.putLong(dest, destOffset, unsafe.getLong(src));
	MethodVariableAccess.REFERENCE.loadOffset[0], // ALOAD 0 this

	FieldAccess.forField(new FieldDescription.ForLoadedField(unsafeField))
	                                   .getter(), // GETFIELD

	MethodVariableAccess.REFERENCE.loadOffset[1], // ALOAD 1 dest
	MethodVariableAccess.LONG.loadOffset[4],      // LLOAD 4 destOffset

	MethodVariableAccess.REFERENCE.loadOffset[0], // ALOAD 0 this
	FieldAccess.forField(new FieldDescription.ForLoadedField(unsafeField))
	                                   .getter(), // GETFIELD

	MethodVariableAccess.LONG.loadOffset[2],      // LLOAD 2 src

	MethodInvocation.invoke(new MethodDescription.ForLoadedMethod(getLongMethod)),
	MethodInvocation.invoke(new MethodDescription.ForLoadedMethod(putLongMethod))
);

Again, the bytecode instructions are created as a sequence of StackManipulation, replicating the bytecode the java compiler code had generated earlier. This example contains a couple of new StackManipulation classes, in particular the Field and Method Descriptions classes.

The final step is the increment step, which won’t be explained, but for the interested reader the source can be found here.

One last piece of information Byte Buddy needs, is the size of the stack needed for the copy() method, including any space local variables may need. The StackManipulation comes in handy here, as it is able to infer some of these details from the byte code it represents. In particular, the following code calculates the stack size:

public Size apply(MethodVisitor methodVisitor, Implementation.Context implementationContext,
   MethodDescription instrumentedMethod) {

	...

	// Call buildStack() (from above) to generate the bytecode
	StackManipulation stack = buildStack();

	// Calculate the size of this bytecode
	StackManipulation.Size finalStackSize = stack.apply(methodVisitor, implementationContext);

	// Now return the size of this bytecode, plus two, which is the size of the local
	// destOffset variable.
	return new Size(finalStackSize.getMaximalSize(), instrumentedMethod.getStackSize() + 2);
}

An important part here, is the +2, which makes room for the long destOffset variable. If that was missing, the generated bytecode would incorrectly write over instructions on the stack, and most likely crash the JVM.

Now at runtime the UnsafeArrayList’s constructor can use the UnrolledUnsafeCopierBuilder to generate a specialised UnsafeCopier designed for the exact class the UnsafeArrayList is storing.

Results

Now we have most of what we need, it is worth benchmarking this code. Using JMH, we can write three microbenchmarks. One using the original looping code, one using the hand unrolled code, and one using the Byte Buddy unrolled code. The code for the benchmarks is on GitHub, and follows a similar methodology to that in a previous article.

The results are as you may expect:

The loop code can execute ~218 times per microseconds, whereas both the Byte Buddy, and hand unrolled code had near identical performance, of ~430-437 iterations per microsecond, nearly twice as fast. Of course, not measured here is the startup cost of generating the unrolled code. It is assumed this technique would only be used when the generated code would exist for a long time. Otherwise the setup cost undoes any per execution savings.

Conclusion

In summary, we managed to unroll a loop at runtime by generating on demand bytecode for that specific purpose. This was possible by inspecting machine generated bytecode, and using Byte Buddy to generate equivalent bytecode at runtime, customised specifically with the correct number of unrolled iterations.

This technique may seem completely crazy, and I don’t suggest its used unless you know what you are doing. That includes, actually measuring you have a performance problem which could be fixed with this, and not being able to depend on the JVM’s own JIT to do this optimisation for you.

Helpful Links: GitHub Home | Gitub Code | JavaDoc

Previously we introduced a UnsafeArrayList, an ArrayList style collection that instead of storing references to the objects, it would use sun.misc.Unsafe and UnsafeHelper to copy the objects into heap allocated memory. This has the unique property of keeping all objects contiguous in memory, and avoids a pointer indirection, at the cost of needing to copy values in and out. This article aims to benchmark this list, and understand its unique characteristics.

Methodology

To test the performance of this new style of list, a series of benchmarks were devised. The new JMH benchmark framework was used, and final benchmark code is available here.

Multiple iterations were run, and unless stated results were calculated with a 99% confidence interval. A couple of warmup iteration were always run and discarded. All tests were run on a Ubuntu Linux 3.19.0-22 desktop, with a 64bit Intel® Core™ i3-2125 CPU @ 3.30GHz, and 16 GiB of 1333 MHz DDR3 RAM. The JVM was OpenJDK (version 1.8.0_45-internal).

For each benchmark new ArrayLists and UnsafeArrayLists were constructed, and populated with newly created objects. The size of the lists were varied, up to a maximum that could be held in memory without disk swapping. Two artificial workloads were created,

1. Reading items from the lists start to finish, and
2. Processing the elements in a random order.

The first was reproduced by simply reading the first field of every element of the list in order, and the second by sorting the list based on the object’s fields (with a simple quicksort).

Three test classes of different sizes were created to be stored within the ArrayLists, one class had two long fields, one had four long fields, and finally one with eight long fields . Named TwoLongs, FourLongs and EightLongs requiring 16, 32, and 64 bytes for the fields respectively. Each iteration these classes were created with random values in the fields.

The Results

Iterate

Starting with the smallest test object, TwoLongs, to read the first field of all 80 million elements within an ArrayList took on average 2.266 ± 0.229 seconds. To do the same with the UnsafeArrayList (which doesn’t store objects, and instead copies elements in/out) took on average 1.79 ±0.03 seconds (an 24% improvement).

Remember in the previous article, UnsafeArrayList has two methods for retrieving an element T get(int index) and a T get(T dest, int index). The former creates a new object and copies the fields. The latter copies the fields in place of a given destination object, allowing the reuse of a single temp object, and avoiding creations of new objects, thus is labelled “InPlace” in the above results.

It is therefore surprising that the UnsafeArrayList can iterate 24% faster than an ArrayList, when it has the additional overhead of creating an object, and copying fields into it. Compared to an ArrayList which is just reading existing objects.

Some theory is needed to understand what might be happening here. A modern CISC CPU can execute an instruction in a few clock cycles, let’s say ~0.5 nanoseconds, however, reading from RAM takes ~10 nanoseconds. While the CPU is waiting for the response from RAM it is effectively blocked. To compensate the CPU deploys a few tricks, two of which could be helping here. Firstly, the CPU tries to predicting and prefetch the next memory request. Secondly, the CPU will execute instructions out of order, thus not waiting for the memory if a later instruction does not depend on the read.

In the ArrayList case, the array of reference is stored in contiguous memory. However, the actual objects (that the references point to) could be anywhere in RAM. As the program loops through it is making reads from effectively random locations in memory, that can’t be predicted, and thus stalls the CPU.

There is no doubt in the UnsafeArrayList the CPU is prefetching the next elements before it is needed. Additionally the cost of creating these short lived objects is most likely very small because they live and die in eden space and are thus simple to create and garbage collect. I also would not be surprised if the CPU or the JIT compiler was able to do some kind of vectorising on the input. That is, concurrently operating on multiple entries at the same time.

If we then test the T get(T dest, int index) method (labelled IterateInPlace), it can iterate through the array in an impressive 0.442 ±0.023 seconds. That’s 5 times faster than the ArrayList, and 4 times faster than the T get(int index). This is certainly because the objects are not created for each get.

It was not measured here, but it is possible to confirm what the CPU is doing, by using hardware based performance counters. These are special registers within the CPU that can be configured to measure cache hit/miss rates, prefetches, instructions per cycle, and many other metrics. These can be invaluable to understand what’s truly going on, as in most cases humans are bad at understanding performance bottlenecks through intuition alone. Tools such as oprofile, perf, dtrace and systemtap can be used for this.

To do a quick sanity check, in the ArrayList case it takes an average of 28.325 nanoseconds per element. According to wikipedia it takes between 9.00-18.75 nanoseconds to read from DDR3 memory at 1333 Mhz. Thus this number doesn’t seem unexpected, as the ArrayList has to issue two memory reads, firstly reading sequentially from an array of references, and then reading from the object (which is at an unpredictable address).

With the UnsafeArrayList in-place test, it takes an average of 5.53 nanoseconds per element. As the fields are stored contiguously in memory, the CPU can efficiency pipeline the requests, amortizing the 9-18 ns memory read cost. Here the speed is most likely limited by either the memory’s bandwidth, or the CPU’s clock cycles. To read 80 million memory addresses in 0.442 seconds, requires 180 Megatransfers per second, and assuming each object is two longs, or 16 bytes requires ~2.68 GiB/s of throughput. Neither of those values approach the upper limit of what DDR3 is capable of, thus I suspect the time is a combination of this and CPU instructions.

Sorting

The second benchmark measured the speed at which the lists could be read and written to somewhat randomly, and in particular sorted. This should cause a less predictable reads from memory. To sort 80 million elements in the ArrayList took 70.31 ±3.939 seconds, and only 18.69 ±3.158 seconds for the UnsafeArrayList using the in-place get. The relative times is not as impressive as the previous test, but still the UnsafeArrayList is ~3.7 times as quick. I’m unsure exactly why the UnsafeArrayList would be faster, but I suspect it is related to the fewer memory indirections, and prefetching effect the copying of fields has.

It’s also worth noting, the increase performance becomes less profound as the size of the stored class increases. For the FourLong the difference between ArrayList and UnsafeArrayList is 3.2x, and for EightLong the difference is 2.4x. This can easily be explained by the increasing cost of copying the fields in and out of the list. Even so, I would argue that the copy cost is in part hidden, as it is effectively prefetching the object’s fields into the CPU cache. Saving a memory load when the field is actually used (most likely shortly after it is pulled from the list).

Other observations

Overlooked is the smaller memory requirements for the UnsafeArrayList. A TwoLong instance is 16 bytes of data, plus 16 bytes of JVM object header. Thus an ArrayList of 40 million instances take 2.4 GiB of RAM (32 bytes x 80M), plus an additional 305MiB for an array of 80 million references (assuming compressed object pointers takes 4 bytes each). Totalling 2.68 GiB, whereas the UnsafeArray takes 16 bytes per entry, totaling only 1.2GiB (roughly half the size!).

Of course if the array is holding larger classes (such as the EightLong), the per object overhead is smaller, in these cases 6.25GiB vs 4.76GiB, roughly 75% the size.

One last observation of interest is the confidence intervals for the results. A larger error implies more variability in the test runs. For example, if the garbage collector ran during some of the runs, and slowed down the test, it would increase this error. In all the tests using the UnsafeArrayList in-place methods, the confidence interval is smaller, implying more constancy and predictability. This can be important in certain situations, such as real-time systems.

Conclusion

We benchmarked the UnsafeArrayList, against a normal ArrayList in two artificial workloads. We found that in both the start-to-finish iteration, and in the sorting case, that the UnsafeArrayList was 4-5x faster than its counterpart. This result itself is interesting when designing high performance data structures, however, the use of sun.misc.Unsafe is considered dangerous, and thus the performance comes with many caveats and risks. In fact, it was recently announced that the Unsafe class is being deprecated and hidden in java 9. So instead, this was just an insightful journey into how the CPU can optomise particular workloads, and how Java can be pushed to extreme speeds.

Your results may vary, and as always you should benchmark your exact workload instead of a hypothetical one, but this was still an interesting experiment.

I recently came across an article from the Mechanical Sympathy blog, that used the flyweight pattern to build a “compact off-heap” array of objects. They basically allocated an area of memory large enough to store N copies of their object. Then using a single instance of a proxy object, would pack/unpack fields into this memory. For example, let’s say we needed to store an array of Point objects. We could construct a simple array like so:

Point[] points = new Point[N];

The inefficiency here is that each instance of a Point requires 12-16 bytes of overhead to store metadata about the object (such as class, GC state, etc), and each additional instance adds to the cost of garbage collection. Additionally, the array actually contains references to Point objects stored elsewhere in RAM. These references require a memory indirection when accessing the actual instances.

In the Mechanical Sympathy article, they instead packed all the fields of the instances into a contiguous array. For simplification I changed their example, but it was something like this:

int[] memory = new int[N*2];

class ProxyPoint {
    private int index = 0;

    public void setIndex(int index) {
        this.index = index;
    }

    public int getX() {
    	return memory[index*2 + 0]
    }

    public int getY() {
    	return memory[index*2 + 1]
    }
}

With this approach there is no overhead for each Point object (as there is only ever one PointProxy, and one array). This also has the interesting property that the fields for all the Points are stored in the same contiguous region of memory. Which leads to some great cache/CPU benefits. For example, if you read all the points sequentially, adjacent objects share the same CPU cache line, and the CPU can predictably prefetch the next point. This would not be possible with an array of references to Points, as each Point could potentially be stored anywhere in RAM.

Now with this primer, it would be interesting to have a normal Java List that stored fields packed together like this. The above solution only works if you create a proxy object ahead of time knowing what class you would be storing. Using the recently released UnsafeHelper class (discussed previously), I went about to build something that looked like a standard generic ArrayList, that could store any type. But with the benefit of storing all elements in contiguous region of memory.

The final solution is UnsafeArrayList.java. This implements the Java List interface, but instead of storing references to objects, it copies the object into a contiguous region of memory. If you are a C++ programmer, you can think of this as a std::vector<Point> instead of a std::vector<Point*>. This minor change comes with it’s own pros and cons, outlined later.

To begin with the list is constructed like so new UnsafeArrayList<Point>(Point.class). The Point.class is passed in so that the list knows what kind of objects it will be storing. This is required due to a limitation in Java’s implementation of generics, that makes it impossible for a class to know its own generic type.

The constructor begins by calculating the size of an instance, and uses the UnsafeHelper to calculates the offset to the first field within an instance.

public UnsafeArrayList(Class<T> type, int capacity) {
    this.firstFieldOffset = UnsafeHelper.firstFieldOffset(type);
    this.elementSize      = UnsafeHelper.sizeOf(type) - firstFieldOffset;
    this.unsafe           = UnsafeHelper.getUnsafe();

An area of memory is then allocated, like so:

    base = unsafe.allocateMemory(elementSize * capacity);

This base variable holds the address to the beginning of the memory, and can only be used via the Unsafe class. The memory is large enough to hold capacity objects of elementSize bytes.

Unlike a Java reference, this base address allows pointer arithmetic, and thus to access a particular element we have a simple method to calculate the memory offset:

    private long offset(int index) {
        return base + (index * elementSize);
    }

Then to set an element within this List, we copy its fields into the allocated memory:

    @Override
    public T set(int index, T element) {
        unsafe.copyMemory(element, firstFieldOffset, // src, src_offset
                          null, offset(index),       // dst, dst_offset
                          elementSize);              // size

This copies from object element, starting at offset firstFieldOffset, into the raw memory address determined by offset(index).

The get method is a little more problematic, as the List interface expects get to return an instance of the object. Since we aren’t actually storing references to the objects (but copies of their fields), we need to construct an instance and populate it. This is quite costly, and defeats the point of this UnsafeArrayList. Instead an additional get method is provided, that allows an object to be passed in, which will have its fields replaced.

    public T get(T dest, int index) {
        unsafe.copyMemory(null, offset(index),
                          dest, firstFieldOffset,
                          elementSize);
        return dest;
    }

For completeness a standard get(int index) method is provided, which creates a new instance of the object (using unsafe.allocateInstance() instead of new Type).

    public T get(int index) {
        return get((T) unsafe.allocateInstance(type), index);
    }

You can inspect the rest of the code via GitHub, but these are the main parts.

In conclusion, this approach has some pros and cons, but was mostly created for fun.

• Pros

• List<> interfaces that stores objects in contiguous memory

• Better cache locality and CPU performance

• Minimal memory overhead

• Cons

• Uses sun.misc.Unsafe

• Additional CPU cycles needed to copies objects in and out of array

• Copies the class out of the garbage collector’s view, thus if a stored object contains the only references to other objects, the garbage collector will not know it is still used.

In the next article, we’ll benchmark this UnsafeArrayList, and investigate the performance impact of the cache locality, and other overheads.

I recently came across the sun.misc.Unsafe class, a poorly documented, internal API that gives your java program direct access to the JVM’s memory. Of course accessing the JVM’s memory can be considered unsafe, but allows for some exciting opportunities.

You can use Unsafe to inspect and manipulate the layout of your objects in RAM, allocate memory off the heap, do interesting things with threads, or even hack in multiple inheritance. Multiple people have written about Unsafe before, and there are some really good articles, so we won’t cover it here.

Using unsafe is not too difficult, but I found the need for a few helper methods, thus I created a collection of classes wrapping the Unsafe code, starting with UnsafeHelper. The main methods of interest are getUnsafe(), sizeOf(), firstFieldOffset(), toByteArray() and hexDump(). The javadoc is the best place to look for documentation, however I’ll quickly explain their use.

To get an sun.misc.Unsafe instance, you have to extract it from a private static field within sun.misc.Unsafe class. For ease, the UnsafeHelper.getUnsafe() method does that.

When accessing an object, you typically need to know the size of the object (in bytes), and be able to find the offset to individual fields. If you understand the memory layout the JVM uses, you’ll know there is a header in front of the Object’s fields. Typically it looks like this, but varies based on CPU architecture, platform, etc:

To hide some of the details, headerSize() returns the size of the header, and sizeOf() return the total size an object including the header in bytes. firstFieldOffset() is then useful as it provides the the offset to the first field. Note that headerSize() and firstFieldOffset() do not always return identical results, as padding (not part of the header) may be used to correctly align the first field.

Next toByteArray() will take an object, and copy it (and its header) into a byte array. Useful for easily inspecting, and serialising the object. Finally, hexDump() uses the toByteArray() to grab an object, and print out a hex representation of the memory, for example:

/**
 * hexDump(new Class4()) prints:
 * 0x00000000: 01 00 00 00 00 00 00 00  8A BF 62 DF 67 45 23 01
 */
static class Class4 {
    int i = 0x01234567;
}

/**
 * Longs are always 8 byte aligned, so 4 bytes of padding
 * hexDump(new Class8()) prints:
 * 0x00000000: 01 00 00 00 00 00 00 00  9B 81 61 DF 00 00 00 00
 * 0x00000010: EF CD AB 89 67 45 23 01
 */
static class Class8 {
    long l = 0x0123456789ABCDEFL;
}

In the first example, Class4, a simple class with a single int field, takes up 16 bytes of memory, with the first 8 used by the JVM, the 2nd 4 bytes being a class pointer (basically how the object knows what kind of class it is), and the last four actually being the value of the field. The second example shows a similar header, but with bytes 12-16 being used as padding, so that the long field value is 8 byte aligned.

These helper methods are available in new project on Github, and downloadable via Maven. Just download the jar file, or include a maven dependency, and import net.bramp.unsafe.UnsafeHelper.

<dependency>
    <groupId>net.bramp.unsafe</groupId>
    <artifactId>unsafe-helper</artifactId>
    <version>1.0</version>
</dependency>

Next article, we’ll make use of this new UnsafeHelper to build a special List which copies objects, instead of storing references.