io.flamingock.internal.core.plan.community

Class CommunityExecutionPlanner

java.lang.Object

io.flamingock.internal.core.plan.ExecutionPlanner

io.flamingock.internal.core.plan.community.CommunityExecutionPlanner

public class CommunityExecutionPlanner
extends ExecutionPlanner

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CommunityExecutionPlanner.Builder

Constructor Summary

Constructors

Constructor and Description
CommunityExecutionPlanner(io.flamingock.internal.util.id.RunnerId instanceId, CommunityLockService lockService, CommunityAuditReader auditReader, CoreConfigurable coreConfiguration)

Method Summary

Modifier and Type	Method and Description
static CommunityExecutionPlanner.Builder	builder()
ExecutionPlan	getNextExecution(PipelineRun pipelineRun) Gets the next execution plan using a two-phase audit read to prevent race conditions in concurrent executions.

Methods inherited from class java.lang.Object

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

Constructor Detail

CommunityExecutionPlanner

public CommunityExecutionPlanner(io.flamingock.internal.util.id.RunnerId instanceId,
                                 CommunityLockService lockService,
                                 CommunityAuditReader auditReader,
                                 CoreConfigurable coreConfiguration)

Parameters:

instanceId - the runner instance identifier

lockService - lockService to persist the lock

auditReader - audit reader to get current audit state

coreConfiguration - core configuration settings

Method Detail

builder

public static CommunityExecutionPlanner.Builder builder()

getNextExecution

public ExecutionPlan getNextExecution(PipelineRun pipelineRun)
                               throws LockException

Gets the next execution plan using a two-phase audit read to prevent race conditions in concurrent executions.

How it works:

1. Initial Audit Read (Optimistic) - Reads the audit log without holding the lock to determine if any changes need execution. This avoids acquiring the lock when all changes are already executed.
2. Early Exit Check - If no changes require execution based on the initial read, returns immediately without acquiring the lock.
3. Lock Acquisition - Acquires the lock to ensure only one instance executes changes. If another instance holds the lock, this call blocks until the lock becomes available.
4. Validated Audit Read (With Lock) - Re-reads the audit log while holding the lock to get the authoritative state. This detects if another instance executed changes while we waited for the lock.
5. Plan Validation - Rebuilds the execution plan with the validated audit data and checks if execution is still needed. If another instance already executed the changes, releases the lock and returns without executing.
6. Concurrent Execution Detection - Logs any differences between the initial and validated plans to track when concurrent instances attempted to execute the same changes.
7. Lock Refresh Daemon - If enabled, starts a background daemon to periodically refresh the lock during long-running executions to prevent lock expiration.
8. Execution - Returns an execution plan containing the next stage to execute while holding the lock. The lock will be released after execution completes.

Concurrent Execution Handling:

 Instance A: Read audit → Get lock → Re-read → Execute → Release
 Instance B: Read audit → Wait for lock → Get lock → Re-read → Detect already executed → Release
 

Error Handling: If any exception occurs after acquiring the lock, the lock is released in the catch block to prevent lock leaks.

Specified by:

getNextExecution in class ExecutionPlanner

Parameters:

pipelineRun - the in-flight run aggregate; this implementation reads the loaded stages from it (pipelineRun.getLoadedStages()) and does not yet consult per-stage state (deferred to a later phase)

Returns:

ExecutionPlan containing either stages to execute (with lock held) or CONTINUE (no lock)

Throws:

LockException - if unable to acquire the distributed lock within the configured timeout