The 3.1 release provides improved Zero Garbage Access for array types via iterators. See Zero Garbage Array Accessors

In This Section

 

Overview

The X Platform's Application Data Modeling (ADM) framework allows modeling of message and entity fields as arrays. For applications that are highly latency sensitive, it is useful to be able to work with such fields in a zero garbage fashion so that gc pauses can be avoided. Arrays are tricky to deal with from a garbage perspective because pooling of arrays presented directly to an application is quite difficult to achieve (imagine trying to pool arrays of every possible size needed by an application). So for array fields the X Platform provides list accessors which allow more efficient array management behind the scenes while also encapsulating the size of the backing storage. Application messages and entities generated with XBuf encoding type and pooling enabled can achieve zero garbage manipulation of array fields via XBuf's setXXXList and getXXXList. This article discusses techniques for avoiding garbage using these accessor variants. 

Use Cases 

 The examples below show how to work with an enum array field of type MyEnum.

Array Field Access and Iteration

 

// use a for loop when iterating a list element to avoid allocating an Iterator
// the code below is garbage free
List<MyEnum> list = message.getMyEnumList();
for(int i = 0; i < list.size(); i++) {
  // do something
}
 
// this is not zero garbage!
for(MyEnum enum : message.getMyEnumList()) {
  // do something
}
 
// this is not zero garbage!
MyEnum [] array = message.getMyEnum();
for(MyEnum enum : array ) {
  // do something
}
 

 

 

The List returned by the getXXXList() method should be treated as read only. For performance reasons the returned list is not guaranteed to enforce read only semantics.

 

Array Field Setters

 

// you may pass the array as a list to the list setter.
// for xbuf generated messages and entities this is a
// zero garbage operation
 
final ArrayList<MyEnum> preallocated = new ArrayList<MyEnum>(5);
...
preallocated.clear();
preallocated.add(MyEnum.VALUE1);
// copies the values from preallocated into the message's backing buffer
message.setMyEnumList(preallocated);

 

Copying A List to Application State

Because messages are pooled, it is illegal for an application to retain references to the list returned by the array list accessor methods beyond the scope of the message handler. When an array from a message needs to be stored in application state it is recommended that a target list or array be preallocated at application startup to avoid promotions and garbage during normal application processing. The following illustrates an application coded stats object that preallocates an ArrayList and copies the values from a message.

 

public class MyStateObject {
    // preallocated array to hold values from a message
    private final ArrayList<MyEnum> values = new ArrayList<MyEnum>(5);
 
    public final void update(final Message message) {
       values.clear();
       // providing values is big enough this is a zero garbage operation
       message.getMyEnumList().copyTo(values);
    }
}

 

Limitations