Class CrossGroupQueryExecutor

java.lang.Object

com.loomcache.server.sharding.CrossGroupQueryExecutor

public class CrossGroupQueryExecutor
extends Object

Handles queries that span multiple Raft groups using scatter-gather.

Pattern: For cross-group operations, the executor sends the query to all relevant groups in parallel (scatter), waits for results with a configurable timeout, and merges the responses (gather).

Execution model: Uses virtual threads for parallel execution across groups. Each group query runs in its own virtual thread, enabling high concurrency without platform thread exhaustion.

Failure handling: cross-group reads fail closed. If any required group fails, times out, or is interrupted, the whole query throws instead of returning partial data that callers could mistake for a complete result.

Since:

2.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	CrossGroupQueryExecutor.GroupQueryFence
static final record	CrossGroupQueryExecutor.ScanPage
static interface	CrossGroupQueryExecutor.VisibilityBarrier

Constructor Summary

Constructors

Constructor	Description
CrossGroupQueryExecutor(ShardedDataStructureRegistry shardedRegistry, PartitionRouter router)	Creates an executor with the default timeout (10 seconds).
CrossGroupQueryExecutor(ShardedDataStructureRegistry shardedRegistry, PartitionRouter router, Duration timeout)	Creates an executor with a custom timeout.
CrossGroupQueryExecutor(ShardedDataStructureRegistry shardedRegistry, PartitionRouter router, Duration timeout, CrossGroupQueryExecutor.GroupQueryFence groupQueryFence)
CrossGroupQueryExecutor(ShardedDataStructureRegistry shardedRegistry, PartitionRouter router, Duration timeout, CrossGroupQueryExecutor.GroupQueryFence groupQueryFence, CrossGroupQueryExecutor.VisibilityBarrier visibilityBarrier)

Method Summary

Modifier and Type	Method	Description
void	crossGroupClear(String mapName)
Map<String,String>	crossGroupGetAll(String mapName, Set<String> keys)	Retrieves values for a set of keys, routing each key to its correct group.
CrossGroupQueryExecutor.ScanPage	crossGroupScan(String mapName, long cursor, @Nullable String pattern, int count)
long	crossGroupSize(String mapName)	Computes the total size of a distributed map across all Raft groups.
<V> List<V>	partitionQuery(Object partitionKey, Function<DataStructureRegistry, List<V>> query, int limit)	Executes a partition-constrained query against the single owning group.
<V> List<V>	scatterQuery(Function<DataStructureRegistry, List<V>> query, int limit)

Methods inherited from class Object

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

Constructor Details

CrossGroupQueryExecutor

public CrossGroupQueryExecutor(ShardedDataStructureRegistry shardedRegistry,
 PartitionRouter router)

Creates an executor with the default timeout (10 seconds).

Parameters:

shardedRegistry - the sharded registry for group access (must not be null)

router - the partition router for key routing (must not be null)

CrossGroupQueryExecutor

public CrossGroupQueryExecutor(ShardedDataStructureRegistry shardedRegistry,
 PartitionRouter router,
 Duration timeout)

Creates an executor with a custom timeout.

Parameters:

shardedRegistry - the sharded registry for group access (must not be null)

router - the partition router for key routing (must not be null)

timeout - the maximum duration for cross-group operations (must not be null)

CrossGroupQueryExecutor

public CrossGroupQueryExecutor(ShardedDataStructureRegistry shardedRegistry,
 PartitionRouter router,
 Duration timeout,
 CrossGroupQueryExecutor.GroupQueryFence groupQueryFence)

CrossGroupQueryExecutor

public CrossGroupQueryExecutor(ShardedDataStructureRegistry shardedRegistry,
 PartitionRouter router,
 Duration timeout,
 CrossGroupQueryExecutor.GroupQueryFence groupQueryFence,
 CrossGroupQueryExecutor.VisibilityBarrier visibilityBarrier)

Method Details

partitionQuery

public <V> List<V> partitionQuery(Object partitionKey,
 Function<DataStructureRegistry, List<V>> query,
 int limit)

Executes a partition-constrained query against the single owning group.

Type Parameters:

V - the element type of query results

Parameters:

partitionKey - the key used to pick the owning group (must not be null)

query - the query to execute on the owner's registry (must not be null)

limit - the maximum number of results to return (must be > 0)

Returns:

the owner's query results, limited to limit (never null)

scatterQuery

public <V> List<V> scatterQuery(Function<DataStructureRegistry, List<V>> query,
 int limit)

crossGroupGetAll

public Map<String,String> crossGroupGetAll(String mapName,
 Set<String> keys)

Retrieves values for a set of keys, routing each key to its correct group.

Keys are first grouped by their owning Raft group, then each group is queried in parallel for its subset of keys. Results are merged into a single map.

Parameters:

mapName - the distributed map name (must not be null)

keys - the keys to retrieve (must not be null)

Returns:

a map of key-to-value for all found keys (never null, may be smaller than input)

crossGroupSize

public long crossGroupSize(String mapName)

Computes the total size of a distributed map across all Raft groups.

Parameters:

mapName - the distributed map name (must not be null)

Returns:

the total number of entries across all groups (always >= 0)

crossGroupScan

public CrossGroupQueryExecutor.ScanPage crossGroupScan(String mapName,
 long cursor,
 @Nullable String pattern,
 int count)

crossGroupClear

public void crossGroupClear(String mapName)