Implementation:Apache Kafka CoordinatorRuntime ScheduleUnloadOperation

Knowledge Sources	Apache Kafka
Domains	Distributed_Systems, Coordinator_Framework
Last Updated	2026-02-09 12:00 GMT

Overview

Concrete tool for scheduling coordinator partition unloading provided by the CoordinatorRuntime framework.

Description

The scheduleUnloadOperation method schedules an internal event that transitions the coordinator to CLOSED state and removes it from the runtime. It handles the epoch check (only unloads if the request epoch is higher or the topic was deleted), transitions the state, and always removes the context from the coordinators map in a finally block.

Usage

Called by the Kafka server when a broker loses leadership for a coordinator partition or when the coordinator topic is deleted.

Code Reference

Source Location

Repository: Apache Kafka
File: coordinator-common/src/main/java/org/apache/kafka/coordinator/common/runtime/CoordinatorRuntime.java
Lines: L2321-2359

Signature

public void scheduleUnloadOperation(
    TopicPartition tp,
    OptionalInt partitionEpoch
)

Import

import org.apache.kafka.coordinator.common.runtime.CoordinatorRuntime;
import org.apache.kafka.common.TopicPartition;
import java.util.OptionalInt;

I/O Contract

Inputs

Name	Type	Required	Description
tp	TopicPartition	Yes	The coordinator's topic-partition to unload
partitionEpoch	OptionalInt	Yes	Partition epoch (empty means topic deleted)

Outputs

Name	Type	Description
void		Coordinator transitioned to CLOSED, context removed from map

Usage Examples

// Called when broker loses leadership
coordinatorRuntime.scheduleUnloadOperation(
    new TopicPartition("__consumer_offsets", 0),
    OptionalInt.of(43)  // new epoch
);

// Called when topic is deleted
coordinatorRuntime.scheduleUnloadOperation(
    new TopicPartition("__consumer_offsets", 0),
    OptionalInt.empty()  // empty = topic deleted
);

Related Pages

Implements Principle

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment