List handler

ListResultHandler()

Bases: BaseResultHandler

A result handler that preserves the submission (chunk) order when collecting results in parallel. This handler uses an internal dictionary to store chunks keyed by their chunk index, and flushes completed chunks in ascending order (0, 1, 2, ...) into a final list. This ensures that even if chunks complete out of order, the final results are returned in the correct submission order.

_buffered = {}

A temporary storage for chunks that are not yet flushed, keyed by their chunk index.

_collected = []

A list containing the final, ordered results after flushing.

_next_index = 0

The index of the next expected chunk to flush from the buffered dictionary.

add_chunk(chunk_results, chunk_index=None, *args, **kwargs)

Adds a chunk of results to the handler. This method is typically called when a parallel task (such as a Ray task) completes execution.

If a chunk_index is provided, the chunk is buffered until all prior chunks have been processed to maintain the original submission order. If no chunk_index is provided (i.e., when running sequentially), the chunk results are appended directly to the final results.

PARAMETER	DESCRIPTION
chunk_results	The list of results produced by a chunk. TYPE: list[Any]
chunk_index	The index of the chunk. This value is used to maintain the correct order. TYPE: int | None DEFAULT: None
*args	Additional positional arguments (unused). TYPE: tuple[Any] DEFAULT: ()
**kwargs	Additional keyword arguments (unused). TYPE: dict[str, Any] DEFAULT: {}

finalize(saver)

Finalizes the result collection process by flushing any remaining buffered chunks and persisting any unsaved results if a saver is provided.

This method should be called after all chunks have been submitted and completed. It ensures that any remaining results in the buffer are appended to the final results, and if a Saver is available, it saves the unsaved results.

PARAMETER	DESCRIPTION
saver	An instance of a Saver used to persist the final results. If None, no saving is performed. TYPE: Saver | None

get_results()

Retrieves all results collected by the handler in their original submission order.

RETURNS	DESCRIPTION
list[Any]	A list containing all the results in order.

periodic_save_if_needed(saver, save_interval)

Persists a slice of the currently collected results if a saving interval has been met.

This method is typically called by a TaskManager after each chunk is added. If a Saver is provided and the number of collected results meets or exceeds the specified save_interval, a slice of results is saved using the saver, and the saved results are removed from the in-memory collection.

PARAMETER	DESCRIPTION
saver	An instance of a Saver responsible for persisting results. If None, no saving is performed. TYPE: Saver | None
save_interval	The minimum number of results required before triggering a save. TYPE: int