Package com.helix.core.executor

Class VirtualThreadRuleExecutor

java.lang.Object

com.helix.core.executor.VirtualThreadRuleExecutor

All Implemented Interfaces:

RuleExecutor, AutoCloseable

public class VirtualThreadRuleExecutor
extends Object
implements RuleExecutor, AutoCloseable

High-throughput rule executor backed by Java 21 Project Loom virtual threads and structured concurrency.

Provides lightweight concurrency without OS carrier thread starvation and implements fail-fast coordinated fan-out using StructuredTaskScope.ShutdownOnFailure^PREVIEW.

Field Summary

Fields

Modifier and Type	Field	Description
static final Duration	DEFAULT_DEADLINE

Constructor Summary

Constructors

Constructor	Description
VirtualThreadRuleExecutor()
VirtualThreadRuleExecutor(Duration defaultTimeout)
VirtualThreadRuleExecutor(Duration defaultTimeout, VirtualThreadExecutorMetrics metrics)
VirtualThreadRuleExecutor(ExecutorService virtualThreadExecutor, Duration defaultTimeout, VirtualThreadExecutorMetrics metrics)

Method Summary

Modifier and Type	Method	Description
void	close()
ExecutionResult	execute(CompiledRule compiledRule, ExecutionContext context)	Executes a compiled rule synchronously using the provided context.
ExecutionResult	execute(CompiledRule compiledRule, ExecutionContext context, Duration timeout)	Executes a compiled rule with an explicit deadline timeout.
List<ExecutionResult>	executeAll(CompiledRule compiledRule, List<ExecutionContext> contexts)	Fan-out evaluation: executes a single rule across multiple contexts concurrently using StructuredTaskScope.ShutdownOnFailurePREVIEW with default timeout.
List<ExecutionResult>	executeAll(CompiledRule compiledRule, List<ExecutionContext> contexts, Duration timeout)	Fan-out evaluation: executes a single rule across multiple contexts concurrently using StructuredTaskScope.ShutdownOnFailurePREVIEW with specified deadline timeout.
List<ExecutionResult>	executeAllRules(List<CompiledRule> rules, ExecutionContext context, Duration timeout)	Parallel rule evaluation: executes multiple rules concurrently against the same context using StructuredTaskScope.ShutdownOnFailurePREVIEW.
CompletableFuture<ExecutionResult>	executeAsync(CompiledRule compiledRule, ExecutionContext context)	Executes a rule asynchronously on a virtual thread using default deadline.
CompletableFuture<ExecutionResult>	executeAsync(CompiledRule compiledRule, ExecutionContext context, Duration timeout)	Executes a rule asynchronously on a virtual thread with an explicit timeout.
Duration	getDefaultTimeout()
ExecutorService	getExecutorService()
VirtualThreadExecutorMetrics	getMetrics()	Retrieves execution metrics for this executor instance.

Methods inherited from class java.lang.Object

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

Field Details

DEFAULT_DEADLINE

public static final Duration DEFAULT_DEADLINE

Constructor Details

VirtualThreadRuleExecutor

public VirtualThreadRuleExecutor()

VirtualThreadRuleExecutor

public VirtualThreadRuleExecutor(Duration defaultTimeout)

VirtualThreadRuleExecutor

public VirtualThreadRuleExecutor(Duration defaultTimeout,
 VirtualThreadExecutorMetrics metrics)

VirtualThreadRuleExecutor

public VirtualThreadRuleExecutor(ExecutorService virtualThreadExecutor,
 Duration defaultTimeout,
 VirtualThreadExecutorMetrics metrics)

Method Details

execute

public ExecutionResult execute(CompiledRule compiledRule,
 ExecutionContext context)
                        throws RuleExecutionException

Description copied from interface: RuleExecutor

Executes a compiled rule synchronously using the provided context.

Specified by:

execute in interface RuleExecutor

Parameters:

compiledRule - rule instance to execute

context - execution context containing variable bindings

Returns:

ExecutionResult containing output value or error details

Throws:

RuleExecutionException - if execution fails unexpectedly

execute

public ExecutionResult execute(CompiledRule compiledRule,
 ExecutionContext context,
 Duration timeout)
                        throws RuleExecutionException

Executes a compiled rule with an explicit deadline timeout.

Parameters:

compiledRule - rule instance to evaluate

context - context containing bindings

timeout - deadline duration (null or zero means no timeout)

Returns:

ExecutionResult containing output or error

Throws:

RuleExecutionException - if execution fails, times out, or is interrupted

executeAsync

public CompletableFuture<ExecutionResult> executeAsync(CompiledRule compiledRule,
 ExecutionContext context)

Executes a rule asynchronously on a virtual thread using default deadline.

Parameters:

compiledRule - rule instance

context - execution context

Returns:

CompletableFuture holding ExecutionResult

executeAsync

public CompletableFuture<ExecutionResult> executeAsync(CompiledRule compiledRule,
 ExecutionContext context,
 Duration timeout)

Executes a rule asynchronously on a virtual thread with an explicit timeout.

Parameters:

compiledRule - rule instance

context - execution context

timeout - deadline duration

Returns:

CompletableFuture holding ExecutionResult

executeAll

public List<ExecutionResult> executeAll(CompiledRule compiledRule,
 List<ExecutionContext> contexts)
                                 throws RuleExecutionException

Fan-out evaluation: executes a single rule across multiple contexts concurrently using StructuredTaskScope.ShutdownOnFailure^PREVIEW with default timeout.

Parameters:

compiledRule - rule instance

contexts - list of execution contexts

Returns:

list of ExecutionResults preserving input order

Throws:

RuleExecutionException - if any subtask fails or execution times out

executeAll

public List<ExecutionResult> executeAll(CompiledRule compiledRule,
 List<ExecutionContext> contexts,
 Duration timeout)
                                 throws RuleExecutionException

Fan-out evaluation: executes a single rule across multiple contexts concurrently using StructuredTaskScope.ShutdownOnFailure^PREVIEW with specified deadline timeout.

Parameters:

compiledRule - rule instance

contexts - list of execution contexts

timeout - deadline duration

Returns:

list of ExecutionResults preserving input order

Throws:

RuleExecutionException - if any subtask fails or execution times out

executeAllRules

public List<ExecutionResult> executeAllRules(List<CompiledRule> rules,
 ExecutionContext context,
 Duration timeout)
                                      throws RuleExecutionException

Parallel rule evaluation: executes multiple rules concurrently against the same context using StructuredTaskScope.ShutdownOnFailure^PREVIEW.

Parameters:

rules - list of rules to evaluate

context - context containing bindings

timeout - deadline duration

Returns:

list of ExecutionResults preserving rule order

Throws:

RuleExecutionException - if any subtask fails or execution times out

getMetrics

public VirtualThreadExecutorMetrics getMetrics()

Description copied from interface: RuleExecutor

Retrieves execution metrics for this executor instance.

Specified by:

getMetrics in interface RuleExecutor

Returns:

ExecutorMetrics tracking counters and execution timing

getExecutorService

public ExecutorService getExecutorService()

getDefaultTimeout

public Duration getDefaultTimeout()

close

public void close()

Specified by:

close in interface AutoCloseable