Array Accessors

Zero garbage array accessors enable iteration over message array fields without allocating iterator objects. They use the XIterator pattern to provide zero-garbage traversal of arrays.

Overview

When a message or state object contains an array field, traditional Java iteration using for-each or Iterator creates temporary objects that contribute to garbage. Talon's zero garbage array accessors provide a way to iterate over arrays without any allocations.

XIterator Pattern

The XIterator pattern provides zero-garbage iteration through reusable iterator objects. When ADM generates code for array fields, it produces iterateXXX() methods that return an XIterator.

Generated Methods

For an array field declared as:

<message name="Order">
  <OrderLine name="lines" array="true"/>
</message>

The ADM code generator produces:

Method

Description

getLines()

Returns a List view of the array (allocates)

getLines(int index)

Returns the element at the specified index

iterateLines()

Returns an XIterator for zero-garbage iteration

addLine(OrderLine)

Adds an element to the array

removeLines(int index)

Removes element at index

clearLines()

Removes all elements

Zero Garbage Iteration

Use the XIterator for zero-garbage array traversal:

@EventHandler
public void onOrder(Order order) {
    // Zero garbage iteration
    XIterator<OrderLine> iter = order.iterateLines();
    while (iter.hasNext()) {
        OrderLine line = iter.next();
        // Process line
        double value = line.getQuantity() * line.getPrice();
    }
}

The XIterator is reused across calls and does not allocate.

Use Cases

Filtering:

XIterator<OrderLine> iter = order.iterateLines();
while (iter.hasNext()) {
    OrderLine line = iter.next();
    if (line.getQuantity() > 100) {
        // Process large orders
    }
}

Aggregation:

double total = 0.0;
XIterator<OrderLine> iter = order.iterateLines();
while (iter.hasNext()) {
    OrderLine line = iter.next();
    total += line.getQuantity() * line.getPrice();
}

Modifying Elements:

XIterator<OrderLine> iter = order.iterateLines();
while (iter.hasNext()) {
    OrderLine line = iter.next();
    // Modify in place
    line.setPrice(line.getPrice() * 1.1); // Apply 10% markup
}

Comparison with Standard Java Iteration

Standard (allocates):

// Creates iterator object
for (OrderLine line : order.getLines()) {
    processLine(line);
}

Zero Garbage:

// Reuses iterator object
XIterator<OrderLine> iter = order.iterateLines();
while (iter.hasNext()) {
    OrderLine line = iter.next();
    processLine(line);
}

The zero-garbage approach reuses the same XIterator instance on each call to iterateXXX(), eliminating allocations.