Implementation:Apache Beam ExecutionDriver

Knowledge Sources	Apache_Beam Beam Programming Guide
Domains	Data_Processing, Runner_Infrastructure
Last Updated	2026-02-09 00:00 GMT

Overview

Concrete interface for driving pipeline execution by repeatedly scheduling work until a terminal state is reached in the Apache Beam local runner.

Description

The ExecutionDriver interface defines a single drive() method that advances pipeline execution by one step. The caller invokes drive() in a loop; each call returns a DriverState enum indicating whether execution should continue (CONTINUE), has failed (FAILED), or has shut down cleanly (SHUTDOWN). The DriverState enum distinguishes terminal from non-terminal states via its isTerminal() method. This design decouples the execution loop from the scheduling strategy, allowing different implementations to control how work is dispatched.

Usage

Use this interface when implementing or customizing the local runner's execution loop. The ExecutorServiceParallelExecutor implements this interface to provide parallel, watermark-driven execution. Not typically imported by end users; it is a runner-internal API.

Code Reference

Source Location

• Repository: Apache_Beam
• File: runners/local-java/src/main/java/org/apache/beam/runners/local/ExecutionDriver.java
• Lines: 18-40

Signature

public interface ExecutionDriver {

    /** Drives one step of pipeline execution. */
    DriverState drive();

    /** The state of the driver. Terminal states mean no further progress. */
    enum DriverState {
        CONTINUE(false),
        FAILED(true),
        SHUTDOWN(true);

        private final boolean terminal;

        DriverState(boolean terminal) {
            this.terminal = terminal;
        }

        public boolean isTerminal() {
            return terminal;
        }
    }
}

Import

import org.apache.beam.runners.local.ExecutionDriver;
import org.apache.beam.runners.local.ExecutionDriver.DriverState;

I/O Contract

Inputs

Name	Type	Required	Description
(none)	—	—	The drive() method takes no parameters; state is managed internally

Outputs

Name	Type	Description
drive() returns	DriverState	CONTINUE if more work remains; FAILED on error; SHUTDOWN on clean completion
DriverState.isTerminal()	boolean	True if no further progress can be made (FAILED or SHUTDOWN)

Usage Examples

Execution Loop Pattern

import org.apache.beam.runners.local.ExecutionDriver;
import org.apache.beam.runners.local.ExecutionDriver.DriverState;

// Typical execution loop used by the local runner
ExecutionDriver driver = createDriver(pipeline);
DriverState state;

do {
    state = driver.drive();
} while (!state.isTerminal());

if (state == DriverState.FAILED) {
    throw new RuntimeException("Pipeline execution failed");
}
// state == DriverState.SHUTDOWN means clean completion

Related Pages

• Environment:Apache_Beam_Java_Build_Environment