Struct LeaderEpochCheckpoint 

pub struct LeaderEpochCheckpoint { /* private fields */ }

Implementations

impl LeaderEpochCheckpoint

pub fn open(path: PathBuf) -> Result<Self, LogError>

Open or recover the checkpoint at path. A missing file gives an empty checkpoint.

Errors

Returns LogError::UnsupportedFormatVersion when the header line is a version other than LEADER_EPOCH_CHECKPOINT_VERSION, LogError::MissingFormatVersion when it is not a version at all, and an error when log I/O fails or a row is corrupt.

impl LeaderEpochCheckpoint

pub fn end_offset_for_epoch( &self, epoch: LeaderEpoch, log_end_offset: Offset, ) -> Offset

End offset of a recorded epoch. It is the start_offset of the next-larger recorded epoch, or log_end_offset if epoch is the current epoch. The method returns -1, which is UNDEFINED_OFFSET, if epoch is not recorded.

This is an exact-match lookup for the log’s own bookkeeping, not Kafka’s endOffsetFor: a gap epoch or one below the first entry is unknown here. Wire answers use Self::epoch_and_offset_for.

pub fn epoch_for_offset(&self, offset: Offset) -> Option<LeaderEpoch>

Floor lookup: return the epoch of the entry whose start_offset is the greatest value <= offset, that is, the leader epoch that owned offset.

The method returns None when the checkpoint has no entries, and when offset comes before the first entry’s start_offset. In the second case the offset predates every recorded epoch boundary.

Entries are stored in increasing start_offset order by construction, because append always writes the current epoch, whose start_offset is >= that of every prior entry. This lookup is therefore a single linear scan from the back. It is equivalent to a search for the last entry with start_offset <= offset.

pub fn epoch_and_offset_for( &self, requested_epoch: LeaderEpoch, log_end_offset: Offset, ) -> (LeaderEpoch, Offset)

Kafka LeaderEpochFileCache.endOffsetFor. It returns (found_epoch, end_offset): the epoch that the requested offset range really belongs to on this log, and the first offset after that epoch. The broker uses it to detect follower and consumer log divergence (KIP-101/320). The Creusot contract of epoch_and_offset_for_entries pins Kafka’s whole case table:

• requested == UNDEFINED_EPOCH → (UNDEFINED_EPOCH, UNDEFINED_OFFSET)
• requested == latest recorded epoch → (requested, log_end_offset)
• no recorded epoch above requested → (UNDEFINED_EPOCH, UNDEFINED_OFFSET) (this covers an empty checkpoint and a future epoch)
• requested below every recorded epoch → (requested, first_recorded_start)
• otherwise (gap or exact older match) → (floor_epoch, next_epoch_start)

where floor_epoch is the largest recorded epoch <= requested and next_epoch_start is the start of the least recorded epoch > requested. (-1, -1) means “cannot place this epoch”: an OffsetForLeaderEpoch row carries it as is, and a Fetch answers it with OFFSET_OUT_OF_RANGE (Partition.readRecords).

impl LeaderEpochCheckpoint

pub fn append( &mut self, epoch: LeaderEpoch, start_offset: Offset, ) -> Result<(), LogError>

Append (epoch, start_offset). This method is idempotent. A second append of an entry with the same epoch does nothing and keeps the earliest recorded start_offset. The method rewrites the file atomically.

Errors

Returns an error when log I/O fails, a record or index is corrupt, or the requested offset violates the segment state.

pub fn assign( &mut self, epoch: LeaderEpoch, start_offset: Offset, ) -> Result<(), LogError>

Kafka’s LeaderEpochFileCache.assign(epoch, startOffset), which UnifiedLog.assignEpochStartOffset calls when Partition.makeLeader records a new leader epoch at the log end before anything is written.

It is a no-op when epoch is already the latest recorded epoch and start_offset is at or after that entry’s start (isUpdateNeeded). Otherwise it first drops every trailing entry whose epoch is >= epoch or whose start is >= start_offset (maybeTruncateNonMonotonicEntries) and then records the new entry, so the history stays strictly increasing in both columns. The file is rewritten only when the entry list changed, and a failed rewrite leaves the entries as they were.

Errors

Returns LogError::InvalidArgument for a negative epoch or start offset, as Kafka throws IllegalArgumentException, and an I/O error when the checkpoint cannot be persisted.

pub fn truncate_from_end(&mut self, end_offset: Offset) -> Result<(), LogError>

Remove epoch entries that begin at or after end_offset. This mirrors Kafka’s LeaderEpochFileCache.truncateFromEnd. The method persists the file if anything changed.

Errors

Returns an error when log I/O fails, a record or index is corrupt, or the requested offset violates the segment state.

pub fn truncate_from_start( &mut self, start_offset: Offset, ) -> Result<(), LogError>

Kafka’s LeaderEpochFileCache.truncateFromStart(startOffset), which UnifiedLog.maybeIncrementLogStartOffset calls when the log start moves up and LogLoader.load calls with the checkpointed log start.

Every entry that starts at or below start_offset is removed, and the newest of them comes back with its start raised to start_offset, so the epoch that covers the new log start still answers for it and no entry points below the log. The call is exclusive: an entry that starts exactly at start_offset keeps its place. The file is rewritten only when an entry was removed, and a failed rewrite leaves the entries as they were.

Errors

Returns an I/O error when the checkpoint cannot be persisted.

pub fn clear(&mut self) -> Result<(), LogError>

Drop every recorded epoch. This mirrors Kafka’s LeaderEpochFileCache.clearAndFlush, which LocalLog.truncateFullyAndStartAt invokes.

crate::Log::reset_to uses this method. Once the log is empty, no offset has a backing record, so the broker may advertise no epoch. The method persists the now-empty file only when it removed something.

Errors

Returns an error when log I/O fails, a record or index is corrupt, or the requested offset violates the segment state.

impl LeaderEpochCheckpoint

pub fn latest_epoch(&self) -> Option<LeaderEpoch>

pub fn entries(&self) -> &[EpochEntry]

Trait Implementations

impl Debug for LeaderEpochCheckpoint

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.