HBASE-30025 Wire TieredExclusiveTopology as a CombinedBlockCache-compatible CacheAccessService

[VladRodionov]

Summary

This PR adds a construction path for creating a topology-backed CacheAccessService
from existing L1 and L2 BlockCache instances.

The pluggable block cache architecture now has the basic components needed for
topology-backed cache access:

• CacheEngine
• CacheTopology
• CachePlacementAdmissionPolicy
• CacheAccessService
• TieredExclusiveTopology
• TopologyBackedCacheAccessService
• BlockCacheBackedCacheEngine

This PR wires those pieces together for the current CombinedBlockCache-style L1/L2
model. Existing BlockCache instances are adapted to CacheEngine using
BlockCacheBackedCacheEngine, assembled into a TieredExclusiveTopology, and exposed
through TopologyBackedCacheAccessService.

Changes

• Adds TopologyBackedCacheAccessServices, a small helper class for constructing
  topology-backed cache access services.
• Adds fromTieredExclusiveBlockCaches(...) for creating a
  TopologyBackedCacheAccessService from existing L1 and L2 BlockCache instances.
• Adds tests verifying that the constructed service uses:
  • BlockCacheBackedCacheEngine for L1 and L2 adaptation
  • TieredExclusiveTopology
  • the supplied CachePlacementAdmissionPolicy
• Adds behavior tests for CombinedBlockCache-compatible exclusive tier behavior:
  • L1 hit
  • L2 hit
  • miss
  • L2-to-L1 promotion
  • rejected cache insertion
  • cache insertion into policy-selected tiers
  • eviction from both tiers
  • shutdown propagation

Why this is needed

The current production L1/L2 block cache model is represented by CombinedBlockCache,
typically coordinating LruBlockCache as L1 and BucketCache as L2.

The new architecture models this as:

CacheAccessService
  -> CacheTopology
      -> CacheEngine(s)

AI assistance disclosure

This PR was prepared with assistance from ChatGPT. All changes were reviewed, tested,
and submitted by the author.

[Copilot]

Pull request overview

Note

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

This PR wires the new topology-backed cache access components into a CombinedBlockCache-style L1/L2 model by providing a factory that adapts existing BlockCache instances into a TieredExclusiveTopology, and adds tests to validate construction and tiered-exclusive behavior.

Changes:

• Add TopologyBackedCacheAccessServices factory helper to build a TopologyBackedCacheAccessService from existing L1/L2 BlockCaches.
• Add construction-path test coverage ensuring correct topology/engine adaptation and null-argument handling.
• Add behavior tests for CombinedBlockCache-compatible tiering (hits, misses, promotion, admission decisions, eviction, shutdown propagation).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/TopologyBackedCacheAccessServices.java	Adds a factory method to construct a topology-backed service from legacy L1/L2 BlockCache instances.
hbase-server/src/test/java/org/apache/hadoop/hbase/io/hfile/cache/TestTopologyBackedCacheAccessServices.java	Verifies the constructed service/topology/engines are as expected and validates null argument rejection.
hbase-server/src/test/java/org/apache/hadoop/hbase/io/hfile/cache/TestCombinedBlockCacheCompatibleTopologyBackedCacheAccessService.java	Adds behavior tests for tiered-exclusive semantics, promotion, admission, eviction, and shutdown.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[VladRodionov]

Addressed. The test now accepts either cacheBlock overload for promotion while still verifying that the block is cached in L1 exactly once and evicted from L2.

[taklwu]

LGTM, let me rerun the unrelated failure one more time.

[VladRodionov]

Thank you @taklwu