Implementation:Apache Flink SingletonResultIterator
| Knowledge Sources | |
|---|---|
| Domains | Connectors, File_Connector |
| Last Updated | 2026-02-09 00:00 GMT |
Overview
A simple, mutable, recyclable record iterator that returns exactly one record at a time, implementing BulkFormat.RecordIterator.
Description
SingletonResultIterator is a final generic class that extends RecyclableIterator and implements BulkFormat.RecordIterator. It is designed for scenarios where a bulk format reader produces records one at a time rather than in batches. The iterator holds a single RecordAndPosition element, which is returned on the first call to next() and then cleared (set to null) so that subsequent calls return null, signaling exhaustion.
The class supports object reuse through its mutable design. Internally, it maintains a MutableRecordAndPosition instance that is reused across calls to set(). The set() method populates the record and its checkpoint position (offset and skip count) where the position must point to after the record for correct checkpoint semantics.
The iterator also supports recycling via its parent class RecyclableIterator, accepting an optional Runnable recycler callback at construction time. This enables integration with the Pool utility for heavyweight object management.
Usage
Use SingletonResultIterator when implementing a BulkFormat.Reader that produces one record per read batch. Call set() to load a record with its position, return the iterator from the reader, and the consumer will call next() to retrieve the single record. After the record is consumed, the iterator can be recycled back for reuse.
Code Reference
Source Location
- Repository: Apache_Flink
- File: flink-connectors/flink-connector-files/src/main/java/org/apache/flink/connector/file/src/util/SingletonResultIterator.java
- Lines: 1-75
Signature
@PublicEvolving
public final class SingletonResultIterator<E> extends RecyclableIterator<E>
implements BulkFormat.RecordIterator<E> {
public SingletonResultIterator();
public SingletonResultIterator(@Nullable Runnable recycler);
public void set(final E element, final long offset, final long skipCount);
@Nullable
@Override
public RecordAndPosition<E> next();
}
Import
import org.apache.flink.connector.file.src.util.SingletonResultIterator;
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| element | E | Yes | The record to be returned by the iterator, set via set(). |
| offset | long | Yes | The file offset pointing to after this record, used for checkpoint position. |
| skipCount | long | Yes | The number of records to skip from the offset, used for checkpoint position. |
| recycler | Runnable | No | Optional callback to recycle the iterator back to a pool after use. |
Outputs
| Name | Type | Description |
|---|---|---|
| next() | RecordAndPosition<E> (nullable) | Returns the single record with position on first call, null on subsequent calls. |
Usage Examples
// Create a singleton iterator with a recycler callback
Pool<SingletonResultIterator<RowData>> pool = new Pool<>(1);
SingletonResultIterator<RowData> iterator = new SingletonResultIterator<>(
() -> pool.recycler().recycle(iterator)
);
pool.add(iterator);
// In the reader: set the record and its position
SingletonResultIterator<RowData> iter = pool.pollEntry();
iter.set(rowData, 1024L, 1L);
// Consumer retrieves the single record
RecordAndPosition<RowData> result = iter.next(); // returns the record
RecordAndPosition<RowData> done = iter.next(); // returns null
// Recycle the iterator for reuse
iter.releaseBatch();