Improving Serialization and Memory Efficiency With a LongConverter

Chronicle Wire is a powerful open-source serialization library for high-performance data exchange in various binary and text formats, including YAML.

Strings in your data structures can have significant overhead regarding memory usage and access patterns. For each String, you have two objects, the String object, and the char[] or byte[], which contains the actual text. Strings are also immutable, and object pooling tends to create many objects for garbage collection in initialization and deserialization.

class MyDto {
    String field; // Reference to a String object.
}

class String {
    final char[] value; // Reference to a char[] containing the text.
}

The char[] contains the actual text.

By comparison, using a long requires no additional memory or memory access. However, it can only contain 64 bits of data. With careful encoding, this limitation can be effectively managed. The two most commonly used LongConverters in Chronicle Wire are Base-85 encoded strings and nano-second resolution timestamps. 

Base-85 Encoding

With Base-85 encoding, you can encode up to 10 characters in a 64-bit long. This method is highly efficient for handling short text strings.

Nanosecond Timestamps

For timestamps, you can encode a yyyy/MM/dd’T’sss.SSSSSSSSS into a 64-bit long, providing nanosecond resolution.

Practical Example

Consider an example using both of these:

class Order extends BytesInBinaryMarshallable {
    @NanoTime 
    private long timestamp;
    @ShortText
    private long trader;
}

In YAML this can be encoded as:

!Order {
  timestamp: 2024-06-14T12:41:58.4512345,
  trader: alice
}

This YAML representation takes 68 bytes. However, the same data is more compact using 16 bytes when using longs. The message is smaller, and serializing and deserializing are much more efficient.

toString() as YAML

The toString() of the class will produce the YAML, and that can be deserialized as the original data.

// Keep the type short in YAML, but it is not required.
ClassAliasPool.CLASS_ALIASES.addAlias(Order.class);

// create an instance with a nano-second resolution timestamps and trader name called “trader”
Order order = new Order();
order.timestamp = SystemTimeProvider.CLOCK.currentTimeNanos(); 
order.trader = ShortText.INSTANCE.parse("alice"));

// prints the object in YAML
System.out.println(order);

// prints: order.timestamp = 17da1070c7ef5d00
System.out.println("order.timestamp = " + Long.toHexString(order.timestamp));

// prints: order.trader = 8aeffe61
System.out.println("order.trader = " + Long.toHexString(order.trader));

// start with a data in YAML
String cs = "" +
        "!Order {\n" +
        "  timestamp: 2024-06-14T12:41:58.8178963,\n" +
        "  trader: alice\n" +
        "}";

// deserialize the object
Order o = Marshallable.fromString(cs);

Benefits of Using LongConverters

Reduced Memory Usage

64-bit long values do not require additional allocations beyond the object itself, unlike Strings or ZonedDateTime, which involve multiple objects.

Efficient Serialization/Deserialization

Handling longs is faster than dealing with complex String or date objects, leading to lower latency and higher throughput.

Making Annotations More Concise

The annotations above are shorthand for:

class Order {
    @LongConvertion(NanoTime.class)
    private final long timestamp;

    @LongConvertion(ShortText.class)
    private final long trader;
}

However, Chronicle Wire can support specifying a custom annotation as a shorthand for an @LongConvertion. This annotation specifies the LongConverter to use as it has a LongConvertion annotation.

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.PARAMETER})
@LongConversion(ShortText.class)
public @interface ShortText {
    /**
     * An instance of {@link ShortTextLongConverter} specifically 
     * configured for Base85 conversions.
     */
    // NOTE: this is a public static final field on the annotation
    LongConverter INSTANCE = ShortTextLongConverter.INSTANCE;
}

This allows defining a shorthand for what would otherwise be a wordy annotation.

Other Integer Types

A LongConverter can also be used for shorter primitive fields such as byte, char, short, and int. A 32-bit int value can store five letters in Base-85 with @ShortText, and a byte can store a single character. A 32-bit int could also store a date or time of day with a custom converter. We have used char and short to store data with limited possible values, but are generally very specific to the use case.

Custom Converters

Additional converters can be provided by implementing LongConverter mapping text to a long and vice-versa.

Conclusion

By leveraging LongConverters, Chronicle Wire provides a significant performance boost, making it ideal for applications that require high performance and low latency, such as financial trading systems and real-time data processing.

This approach exemplifies how careful data encoding and efficient memory usage can lead to substantial performance improvements in high-frequency, low-latency applications.