Skip to content

How to build a simple binary codec using Agrona

Problem

You would like to build a simple codec to move data across IPC or Aeron, but don't need the features of Simple Binary Encoding.

Solution

Allocate a MutableDirectBuffer and write/read the data required. Hold an offset for the intitial byte, and move the writing/reading of data along according to the length of the previously written field.

Sample

Sample writing a short and an int:

1
2
mutableBuffer.putShort(offset, valueShort);
mutableBuffer.putInt(offset + Short.BYTES, valueInt);

Reading the data would be:

1
2
short valueShortRead = mutableBuffer.getShort(offset);
int valueIntRead = mutableBuffer.getInt(offset + Short.BYTES);

Discussion

Binary codecs offer a significant space and execution time advantage over other formats such as JSON, but come at the cost of having to design an efficient structure to move data. If you're unfamiliar with finance, it may be suprising to know that this style of binary codecs are common. As a public sample, NASDAQ ITCH and OUCH are fixed offset, fixed length protocols, which can be authored and consumed with Agrona Direct Buffer styled mechanisms. Simple Binary Encoding offers a more structured approach, allowing variable length repeating groups and variable length fields such as strings. Internally, Simple Binary Encoding is using Direct Buffer and the exact same methods such as putInt and getInt.

When dealing with byte buffers - as you do in Aeron - sending 'human readable' JSON and binary codecs are practically the same in terms of developer friendliness. In both cases, the raw byte buffers must be converted to something human readable.

See Also