Class Backlog<T>

java.lang.Object

io.fluxzero.common.Backlog<T>

Type Parameters:

T - The type of item being buffered and processed.

All Implemented Interfaces:

Monitored<List<T>>

public class Backlog<T>
extends Object
implements Monitored<List<T>>

A thread-safe batching queue that asynchronously flushes its content to a consumer in configurable batch sizes.

This utility is useful for scenarios where multiple values are being added over time and you want to consume them in batches for efficiency—such as sending messages to a remote system, writing to a log, etc.

Flushes are executed on a single background thread, and results (e.g. completion or failure) are tracked via CompletableFutures. Optional monitors may observe each flushed batch.

Key Features

• Supports both synchronous and asynchronous consumers
• Flushes automatically after new items are added
• Tracks flush progress with CompletableFuture per add
• Customizable error handling via ErrorHandler
• Monitoring support via Monitored

Typical Use

Backlog<String> backlog = Backlog.forAsyncConsumer(batch -> {
    return sendToServer(batch); // returns CompletableFuture
});
backlog.add("a", "b", "c");

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Backlog.BatchConsumer<T>	A function that consumes a batch of items and returns a future that completes when processing is done.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Backlog(ThrowingFunction<List<T>, CompletableFuture<?>> consumer)
protected	Backlog(ThrowingFunction<List<T>, CompletableFuture<?>> consumer, int maxBatchSize)
protected	Backlog(ThrowingFunction<List<T>, CompletableFuture<?>> consumer, int maxBatchSize, ErrorHandler<List<T>> errorHandler)

Method Summary

Modifier and Type	Method	Description
CompletableFuture<Void>	add(Collection<? extends T> values)	Adds a collection of values to the backlog.
final CompletableFuture<Void>	add(T... values)	Adds values to the backlog.
protected void	completeResults(long untilPosition, Throwable e)
static <T> Backlog<T>	forAsyncConsumer(ThrowingFunction<List<T>, CompletableFuture<?>> consumer)	Creates a backlog for an asynchronous consumer with default max batch size and default logging error handler.
static <T> Backlog<T>	forAsyncConsumer(ThrowingFunction<List<T>, CompletableFuture<?>> consumer, int maxBatchSize)	Creates a backlog for an asynchronous consumer with custom max batch size and default logging error handler.
static <T> Backlog<T>	forAsyncConsumer(ThrowingFunction<List<T>, CompletableFuture<?>> consumer, int maxBatchSize, ErrorHandler<List<T>> errorHandler)	Creates a backlog for an asynchronous consumer with custom max batch size and error handler.
static <T> Backlog<T>	forConsumer(ThrowingConsumer<List<T>> consumer)	Creates a new backlog for a synchronous consumer and default batch size and default logging error handler.
static <T> Backlog<T>	forConsumer(ThrowingConsumer<List<T>> consumer, int maxBatchSize)	Creates a backlog with custom max batch size and default logging error handler.
static <T> Backlog<T>	forConsumer(ThrowingConsumer<List<T>> consumer, int maxBatchSize, ErrorHandler<List<T>> errorHandler)	Creates a backlog with custom max batch size and error handler.
Registration	registerMonitor(Consumer<List<T>> monitor)	Adds a monitor to observe flushed batches.
void	shutDown()	Shuts down the internal executor service cleanly.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Backlog

protected Backlog(ThrowingFunction<List<T>, CompletableFuture<?>> consumer)

Backlog

protected Backlog(ThrowingFunction<List<T>, CompletableFuture<?>> consumer,
 int maxBatchSize)

Backlog

protected Backlog(ThrowingFunction<List<T>, CompletableFuture<?>> consumer,
 int maxBatchSize,
 ErrorHandler<List<T>> errorHandler)

Method Details

forConsumer

public static <T> Backlog<T> forConsumer(ThrowingConsumer<List<T>> consumer)

Creates a new backlog for a synchronous consumer and default batch size and default logging error handler.

forConsumer

public static <T> Backlog<T> forConsumer(ThrowingConsumer<List<T>> consumer,
 int maxBatchSize)

Creates a backlog with custom max batch size and default logging error handler.

forConsumer

public static <T> Backlog<T> forConsumer(ThrowingConsumer<List<T>> consumer,
 int maxBatchSize,
 ErrorHandler<List<T>> errorHandler)

Creates a backlog with custom max batch size and error handler.

forAsyncConsumer

public static <T> Backlog<T> forAsyncConsumer(ThrowingFunction<List<T>, CompletableFuture<?>> consumer)

Creates a backlog for an asynchronous consumer with default max batch size and default logging error handler.

forAsyncConsumer

public static <T> Backlog<T> forAsyncConsumer(ThrowingFunction<List<T>, CompletableFuture<?>> consumer,
 int maxBatchSize)

Creates a backlog for an asynchronous consumer with custom max batch size and default logging error handler.

forAsyncConsumer

public static <T> Backlog<T> forAsyncConsumer(ThrowingFunction<List<T>, CompletableFuture<?>> consumer,
 int maxBatchSize,
 ErrorHandler<List<T>> errorHandler)

Creates a backlog for an asynchronous consumer with custom max batch size and error handler.

add

@SafeVarargs
public final CompletableFuture<Void> add(T... values)

Adds values to the backlog.

Parameters:

values - one or more values to enqueue

Returns:

a future that completes when the values are processed by the consumer.

add

public CompletableFuture<Void> add(Collection<? extends T> values)

Adds a collection of values to the backlog.

Parameters:

values - collection of values to enqueue

Returns:

a future that completes when the values are processed by the consumer.

completeResults

protected void completeResults(long untilPosition,
 Throwable e)

registerMonitor

public Registration registerMonitor(Consumer<List<T>> monitor)

Adds a monitor to observe flushed batches.

Specified by:

registerMonitor in interface Monitored<T>

Parameters:

monitor - the observer

Returns:

a Registration that can be used to remove the monitor

shutDown

public void shutDown()

Shuts down the internal executor service cleanly.