Using Agrona JVM agent for unaligned memory access discovery

Goal: detecting unaligned memory accesses

Many CPU architectures exhibit significant performance issues when words are accessed on non word sized boundaries. That is the starting address of a word should be a multiple of its size in bytes. 64-bit integers should only begin on byte address divisible by 8, 32-bit integers should only begin on byte addresses divisible by 4, and so on.

Some CPU architectures do even not support unaligned accesses at all, and if the JVM tries to do such an access, it will be killed by the operating system. While using the official JDK ByteBuffer API ensure that all accesses will be aligned, Agrona provides performance-efficient buffers that are not doing all the checks done in the JDK, and unaligned accesses are possible.

In order to track these unaligned accesses down, Agrona agent was introduced (as of v0.9.3). Using this agent will redefine all implementations of DirectBuffer and let them throw a BufferAlignmentException whenever they attempt an unaligned access. These additional checks can have a performance overhead and the main use cases for the agent are debugging and unit testing.

Adding the agent from the command line

You need to add -javagent:agrona-agent-<version>.jar to your command line. The agent requires Byte Buddy to work properly, if you don't have it in your classpath, you can use agrona-agent-<version>-all.jar instead: Byte Buddy is already packaged with it.

Adding the agent programmatically

For unit testing, you might want to include the agent directly from your code by adding this line of code:

    BufferAlignmentAgent.agentmain("", ByteBuddyAgent.install());

and remove it with:

    BufferAlignmentAgent.removeTransformer();