Implementation:Apache Flink SplitFetcherTask

Knowledge Sources	Apache_Flink
Domains	Connectors, Source_Framework
Last Updated	2026-02-09 00:00 GMT

Overview

An interface for tasks executed within a SplitFetcher that supports interruptible execution and graceful wakeup.

Description

SplitFetcherTask is a low-level interface in Flink's source connector framework that defines units of work executed by a SplitFetcher thread. It is conceptually similar to Runnable but provides two key enhancements: (1) the run() method can throw IOException, allowing implementations to propagate I/O errors naturally, and (2) the wakeUp() method provides a mechanism to interrupt or signal a running task to finish early.

The run() method returns a boolean indicating whether the task has completed all its work. A return value of true means the task has finished successfully, while false indicates that more invocations are needed to complete the work. This allows the fetcher to schedule tasks that may require multiple rounds of execution, such as polling a source system that returns partial results. The interface is annotated with @PublicEvolving, indicating it is part of Flink's public API but may evolve across minor versions.

Usage

This interface is primarily used internally by the split fetcher framework. The main implementations include the fetch task (which calls SplitReader.fetch()) and the add-splits task (which handles split assignment). Connector developers generally do not implement this interface directly unless they need to inject custom tasks into the fetcher's task queue for advanced use cases such as custom split management or periodic maintenance operations within the fetcher thread.

Code Reference

Source Location

• Repository: Apache_Flink
• File: flink-connectors/flink-connector-base/src/main/java/org/apache/flink/connector/base/source/reader/fetcher/SplitFetcherTask.java
• Lines: 1-42

Signature

@PublicEvolving
public interface SplitFetcherTask {

    /**
     * Run the logic. Returns whether the runnable has successfully finished running.
     * Throwing IOException is supported for I/O operation failures.
     *
     * @return whether the runnable has successfully finished running.
     * @throws IOException when the performed I/O operation fails.
     */
    boolean run() throws IOException;

    /**
     * Wake up the running thread.
     */
    void wakeUp();
}

Import

import org.apache.flink.connector.base.source.reader.fetcher.SplitFetcherTask;

I/O Contract

Inputs

Name	Type	Required	Description
(none)	-	-	The run() method takes no parameters. Task state and context are provided at construction time.

Outputs

Name	Type	Description
(return value of run)	boolean	true if the task has completed all its work successfully; false if more invocations are needed.
(side effects)	void	The task may produce side effects such as fetching records into a queue, modifying split assignments, or updating internal state.

Usage Examples

// Example: A custom SplitFetcherTask that performs a periodic health check
// on the source connection within the fetcher thread.
public class HealthCheckTask implements SplitFetcherTask {

    private final SourceConnection connection;
    private volatile boolean wokenUp = false;

    public HealthCheckTask(SourceConnection connection) {
        this.connection = connection;
    }

    @Override
    public boolean run() throws IOException {
        if (wokenUp) {
            return true;  // Abort early on wakeup
        }
        // Perform health check
        if (!connection.isHealthy()) {
            connection.reconnect();
        }
        return true;  // Task completes in a single invocation
    }

    @Override
    public void wakeUp() {
        wokenUp = true;
        // Optionally interrupt any blocking operation
        connection.interrupt();
    }
}

Related Pages

• Principle:Apache_Flink_Split_Based_Record_Reading