Skip to content

[improve][broker] Refactor bucket delayed-delivery class structure#26214

Draft
nodece wants to merge 3 commits into
apache:masterfrom
nodece:refactor-bucket-delayed-delivery-clarity
Draft

[improve][broker] Refactor bucket delayed-delivery class structure#26214
nodece wants to merge 3 commits into
apache:masterfrom
nodece:refactor-bucket-delayed-delivery-clarity

Conversation

@nodece

@nodece nodece commented Jul 20, 2026

Copy link
Copy Markdown
Member

Motivation

The bucket delayed-delivery implementation has accumulated unnecessary complexity over time.
The current Bucket base class mixes mutable bucket state, immutable snapshot state, shared dependencies, and persistence helpers, making the lifecycle and ownership of these fields unclear.

In addition, the mutable bucket's delayed index bitmap was serving two different purposes:

  • tracking per-bucket delayed message state
  • acting as a tracker-wide inflight deduplication index

This coupling makes the state management harder to reason about and can lead to unnecessary memory growth.

The existing use of boxed Long keys in delayed indexes also introduces additional memory overhead, which becomes significant for large delayed message workloads.

This change simplifies bucket ownership boundaries, separates mutable and immutable state, and reduces memory overhead for large delayed indexes.

Modifications

  • Removed the Bucket abstract base class.

    • MutableBucket and ImmutableBucket are now independent classes with clearly separated responsibilities.
    • Snapshot-specific state and persistence helpers are no longer shared through inheritance.
  • Added BucketContext record to hold shared dependencies:

    • dispatcherName
    • cursor
    • sequencer
    • bucketSnapshotStorage

    The tracker creates a single context instance and shares it across buckets.

  • Refactored MutableBucket:

    • Removed inheritance from Bucket.
    • Owns its own priorityQueue and mutable ledger range.
    • Removed the unused inherited delayedIndexBitMap field.
  • Refactored ImmutableBucket:

    • Owns all snapshot-related state, including:
      • delayedIndexBitMap
      • snapshotSegments
      • segment pointers
      • bucketId
      • snapshotCreateFuture
    • Moved snapshot persistence helpers from Bucket into ImmutableBucket.
    • Made startLedgerId and endLedgerId final to match their lifecycle.
  • Added tracker-level inflightIndex in BucketDelayedDeliveryTracker:

    • Replaced the previous dual usage of lastMutableBucket.delayedIndexBitMap.
    • containsMessage and removeIndexBit now check inflightIndex first and fall back to immutable bucket indexes.
    • During bucket sealing, afterCreateImmutableBucket removes migrated positions from inflightIndex to avoid stale entries.
  • Replaced boxed Map<Long, LongBitmap> with primitive-keyed fastutil maps:

    • Long2ObjectOpenHashMap
    • Applied to:
      • Tracker.inflightIndex
      • ImmutableBucket.delayedIndexBitMap
      • local maps in MutableBucket.sealBucketAndAsyncPersistent
      • local maps in Tracker.asyncMergeBucketSnapshot

    This avoids Long boxing overhead and saves approximately 24 bytes per entry, which is significant for delayed indexes that can grow beyond 100K entries.

@nodece
nodece force-pushed the refactor-bucket-delayed-delivery-clarity branch from ddae503 to 68f3cad Compare July 20, 2026 10:27
@nodece
nodece requested review from coderzc, dao-jun and merlimat July 20, 2026 10:31
@nodece nodece added this to the 5.0.0-M2 milestone Jul 20, 2026
@nodece
nodece marked this pull request as draft July 21, 2026 03:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant