XStrings

XStrings provide a zero garbage alternative to Java Strings for ultra-low-latency applications. XStrings are mutable, string-like objects that can be pooled and preallocated so that string handling neither allocates nor promotes during message processing.

Overview

An XString is a mutable, zero garbage alternative to java.lang.String. Java Strings are immutable and allocate on every manipulation, which makes them unsuitable for values that change on each message. An XString can be written in place, compared without allocating, and copied to and from messages without creating garbage.

Eliminating garbage is only half the problem. Objects held in application state survive long enough to be promoted across heap generations, and promotion is expensive. Avoiding it requires that the strings held in state be pooled and preallocated rather than created as needed. That is what a poolable string type provides.

Declaring a Poolable String

Poolable string types are declared in the ADM model, not in application code. A String field or semantic type carrying poolable="true" causes the code generator to emit a dedicated subclass of XString for it, together with the factory used to pool and preallocate instances:

<types>
    <type name="ComplianceId" base="String" length="24" poolable="true"
          doc="Identifier attached to an order for compliance reporting."/>
</types>

<fields>
    <field name="complianceId" type="ComplianceId" id="1"/>
</fields>

A field may also be marked poolable directly, in which case the generated type is named after the field rather than the semantic type. The declaration syntax, the generated type, and the naming rules are covered in full under Poolable String Types.

Working with Poolable Strings

Fields of a poolable string type are given accessors that copy the value in and out rather than handing out a reference:

Method

Description

getXXXTo(factory)

Copies the field's value into an instance sourced from the given factory and returns it. Zero garbage when the factory is pool backed and has instances available.

setXXXFrom(value)

Sets the field from an already encoded XString, avoiding a re-encode.

getXXX() / setXXX(String)

The plain String accessors, which allocate. Useful outside the hot path.

There are two patterns in common use.

Holding a value in application state

Source the string from a preallocated factory and copy the message value into it. This is the pattern to use whenever the value outlives the handler:

private final ComplianceId.Factory complianceIdFactory =
    ComplianceId.newFactory("complianceId", 24, true, 1024, false, false);

@EventHandler
public void onNewOrder(NewOrder order, OrderState state) {
    // Copy the value out of the message into an instance from the pool.
    ComplianceId complianceId = order.getComplianceIdTo(complianceIdFactory);

    // Copy it into an outbound message.
    OrderAccepted accepted = OrderAccepted.create();
    accepted.setComplianceIdFrom(complianceId);

    // Retain it in application state.
    state.setComplianceId(complianceId);
}

Copying out of the message is not optional here. If the message itself is pooled, its field values are reset once the handler returns, so a reference retained in state would be left holding a value that no longer belongs to it.

Using a working variable

Where the value does not outlive the handler, a single reusable instance is enough:

private final ComplianceId complianceIdTemp = ComplianceId.create(true);

@EventHandler
public void onNewOrder(NewOrder order) {
    // Safe to overwrite on each invocation because handlers are single threaded
    // and the value is not retained beyond this call.
    order.getComplianceIdTo(complianceIdTemp);

    OrderAccepted accepted = OrderAccepted.create();
    accepted.setComplianceIdFrom(complianceIdTemp);
}

Note that this pattern retains the reference and so does not exercise the pooling capability of the type. It avoids allocation, not promotion.

Preallocation

Preallocation is a property of the factory, not of the field. A factory created with a preallocation count fills its pool up front, so that instances taken during message processing are already resident and do not have to be allocated and later promoted:

// name, stringLength, pooled, preallocationCount, threaded, isNative
ComplianceId.Factory factory =
    ComplianceId.newFactory("complianceId", 24, true, 1024, false, false);

stringLength sizes the backing buffer of each instance. Size it for the longest value you expect. A value that exceeds it forces the backing storage to grow, which allocates.
pooled determines whether the factory is backed by a pool at all. Preallocation is only meaningful when it is.
preallocationCount is the number of instances created up front.
threaded makes the backing pool thread safe. Leave it false for the single threaded handler path.
isNative selects native backing buffers where enabled and supported.

Each generated type also exposes a default FACTORY for cases where a configured factory is not warranted.

Pools created this way are configurable at runtime alongside the platform's other pools. See Tuning Pools.

A Note on RawString

XString supersedes RawString, which remains present but is deprecated. New code should use XString and the generated poolable types; existing uses of RawString should migrate.