Class WalCompactor

java.lang.Object

com.loomcache.server.persistence.WalCompactor

All Implemented Interfaces:

AutoCloseable

public class WalCompactor
extends Object
implements AutoCloseable

Background WAL compaction service.

Automatically compacts the Write-Ahead Log by:

• Monitoring WAL file size
• Creating snapshots when size exceeds threshold
• Truncating old WAL entries atomically
• Running on a virtual thread for efficient async operation

Thread safety:

• Uses virtual threads for background tasks
• Atomic operations for snapshots and truncation
• Statistics use LongAdder for lock-free updates

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	WalCompactor.CompactionSnapshot	Snapshot boundary and state to use for one automatic compaction.
static final record	WalCompactor.CompactionStats	Compaction statistics record.

Constructor Summary

Constructors

Constructor	Description
WalCompactor(String nodeId, WalWriter walWriter, SnapshotManager snapshotManager, long compactionThreshold, long snapshotIntervalMs)	Create a WAL compactor.
WalCompactor(String nodeId, WalWriter walWriter, SnapshotManager snapshotManager, long compactionThreshold, long snapshotIntervalMs, @Nullable Supplier<@Nullable WalCompactor.CompactionSnapshot> automaticCompactionSnapshotSupplier)	Create a WAL compactor with an optional automatic compaction snapshot callback.

Method Summary

Modifier and Type	Method	Description
void	clearAutomaticCompactionSnapshotSupplier()	Disable scheduled automatic compaction.
void	close()	Close the compactor and release resources.
void	forceCompaction(long snapshotIndex, long snapshotTerm, Supplier<byte[]> stateSupplier)	Manually force a compaction regardless of size threshold.
WalCompactor.CompactionStats	getCompactionStats()	Get current compaction statistics.
long	getCompactionThreshold()	Get the compaction threshold in bytes.
long	getSnapshotInterval()	Get the snapshot interval in milliseconds.
void	setAutomaticCompactionSnapshotSupplier(Supplier<@Nullable WalCompactor.CompactionSnapshot> supplier)	Configure the callback used by scheduled automatic compaction.
void	start(long checkIntervalMs)	Start background compaction monitoring.
void	stop()	Stop background compaction monitoring.

Methods inherited from class Object

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

Constructor Details

WalCompactor

public WalCompactor(String nodeId,
 WalWriter walWriter,
 SnapshotManager snapshotManager,
 long compactionThreshold,
 long snapshotIntervalMs)

Create a WAL compactor.

Parameters:

nodeId - The node ID for logging

walWriter - The WAL writer instance

snapshotManager - The snapshot manager instance

compactionThreshold - Bytes threshold to trigger compaction (e.g., 100MB)

snapshotIntervalMs - Minimum ms between snapshots

WalCompactor

public WalCompactor(String nodeId,
 WalWriter walWriter,
 SnapshotManager snapshotManager,
 long compactionThreshold,
 long snapshotIntervalMs,
 @Nullable Supplier<@Nullable WalCompactor.CompactionSnapshot> automaticCompactionSnapshotSupplier)

Create a WAL compactor with an optional automatic compaction snapshot callback.

Parameters:

nodeId - The node ID for logging

walWriter - The WAL writer instance

snapshotManager - The snapshot manager instance

compactionThreshold - Bytes threshold to trigger compaction

snapshotIntervalMs - Minimum ms between automatic snapshots

automaticCompactionSnapshotSupplier - Supplier for safe automatic compaction snapshots, or null to require manual compaction

Method Details

setAutomaticCompactionSnapshotSupplier

public void setAutomaticCompactionSnapshotSupplier(Supplier<@Nullable WalCompactor.CompactionSnapshot> supplier)

Configure the callback used by scheduled automatic compaction.

The callback must only return a snapshot whose index and term are known committed/applied and whose state bytes match that boundary. Returning null skips the current automatic compaction attempt.

Parameters:

supplier - snapshot callback

clearAutomaticCompactionSnapshotSupplier

public void clearAutomaticCompactionSnapshotSupplier()

Disable scheduled automatic compaction. Manual forceCompaction(long, long, Supplier) remains available.

start

public void start(long checkIntervalMs)

Start background compaction monitoring.

Spawns a virtual thread that periodically checks WAL size and triggers compaction when threshold is exceeded.

Parameters:

checkIntervalMs - Interval between size checks (milliseconds)

stop

public void stop()

Stop background compaction monitoring.

forceCompaction

public void forceCompaction(long snapshotIndex,
 long snapshotTerm,
 Supplier<byte[]> stateSupplier)
                     throws IOException

Manually force a compaction regardless of size threshold.

This operation:

1. Reads all entries from WAL
2. Creates a snapshot of the state
3. Atomically truncates WAL

Parameters:

snapshotIndex - The committed/applied index included in the snapshot

snapshotTerm - The term of snapshotIndex

stateSupplier - Supplier providing the current state machine state as bytes

Throws:

IOException - If compaction fails

getCompactionStats

public WalCompactor.CompactionStats getCompactionStats()

Get current compaction statistics.

Returns:

CompactionStats record with current metrics

close

public void close()
           throws IOException

Close the compactor and release resources.

Specified by:

close in interface AutoCloseable

Throws:

IOException - If close fails

getCompactionThreshold

public long getCompactionThreshold()

Get the compaction threshold in bytes.

Returns:

The threshold value

getSnapshotInterval

public long getSnapshotInterval()

Get the snapshot interval in milliseconds.

Returns:

The interval value