Re: [PR] HBASE-30019 Introduce CacheEngine and CacheTopology abstractions [hbase]
taklwu merged PR #8155: URL: https://github.com/apache/hbase/pull/8155 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [PR] HBASE-30019 Introduce CacheEngine and CacheTopology abstractions [hbase]
VladRodionov commented on code in PR #8155:
URL: https://github.com/apache/hbase/pull/8155#discussion_r3156145277
##
hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheEngine.java:
##
@@ -0,0 +1,319 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.hadoop.hbase.io.hfile.cache;
+
+import java.util.Optional;
+import org.apache.hadoop.conf.Configuration;
+import org.apache.hadoop.hbase.io.hfile.BlockCacheKey;
+import org.apache.hadoop.hbase.io.hfile.BlockType;
+import org.apache.hadoop.hbase.io.hfile.CacheStats;
+import org.apache.hadoop.hbase.io.hfile.Cacheable;
+import org.apache.hadoop.hbase.io.hfile.HFileBlock;
+import org.apache.yetus.audience.InterfaceAudience;
+
+/**
+ * Storage abstraction for a concrete HBase block cache backend.
+ *
+ * A {@code CacheEngine} represents the storage layer only. It is
responsible for storing,
+ * retrieving, invalidating, and reporting statistics for cached blocks. It
does not perform
+ * tier orchestration, admission control, placement decisions, or
promotion/demotion across
+ * cache levels.
+ *
+ * This interface is intentionally aligned with the storage-oriented subset
of the current
+ * {@code BlockCache} contract so that existing implementations such as
LruBlockCache and
+ * BucketCache can be migrated incrementally with minimal behavioral risk.
+ *
+ * Responsibilities of a {@code CacheEngine} include:
+ *
+ * block lookup
+ * block insertion
+ * targeted invalidation / eviction
+ * capacity and occupancy reporting
+ * engine-local statistics
+ * optional implementation-specific fit/capability checks
+ *
+ *
+ * Non-responsibilities include:
+ *
+ * L1/L2 topology orchestration
+ * admission policy
+ * tier placement decisions
+ * promotion or demotion across tiers
+ *
+ */
[email protected]
+public interface CacheEngine {
Review Comment:
API will evolve for sure. We will see later if anything is missing.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
Re: [PR] HBASE-30019 Introduce CacheEngine and CacheTopology abstractions [hbase]
VladRodionov commented on code in PR #8155:
URL: https://github.com/apache/hbase/pull/8155#discussion_r3156130060
##
hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheEngine.java:
##
@@ -0,0 +1,302 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.hadoop.hbase.io.hfile.cache;
+
+import java.util.Optional;
+import org.apache.hadoop.conf.Configuration;
+import org.apache.hadoop.hbase.io.hfile.BlockCacheKey;
+import org.apache.hadoop.hbase.io.hfile.BlockType;
+import org.apache.hadoop.hbase.io.hfile.CacheStats;
+import org.apache.hadoop.hbase.io.hfile.Cacheable;
+import org.apache.hadoop.hbase.io.hfile.HFileBlock;
+import org.apache.yetus.audience.InterfaceAudience;
+
+/**
+ * Storage abstraction for a concrete HBase block cache backend.
+ *
+ * A {@code CacheEngine} represents the storage layer only. It is responsible
for storing,
+ * retrieving, invalidating, and reporting statistics for cached blocks. It
does not perform tier
+ * orchestration, admission control, placement decisions, or
promotion/demotion across cache levels.
+ *
+ *
+ * This interface is intentionally aligned with the storage-oriented subset of
the current
+ * {@code BlockCache} contract so that existing implementations such as
LruBlockCache and
+ * BucketCache can be migrated incrementally with minimal behavioral risk.
+ *
+ *
+ * Responsibilities of a {@code CacheEngine} include:
+ *
+ *
+ * block lookup
+ * block insertion
+ * targeted invalidation / eviction
+ * capacity and occupancy reporting
+ * engine-local statistics
+ * optional implementation-specific fit/capability checks
+ *
+ *
+ * Non-responsibilities include:
+ *
+ *
+ * L1/L2 topology orchestration
+ * admission policy
+ * tier placement decisions
+ * promotion or demotion across tiers
+ *
+ */
[email protected]
+public interface CacheEngine {
+
+ /**
+ * Returns a human-readable name for this cache engine instance.
+ *
+ * The name is intended for logging, metrics, diagnostics, and configuration
reporting. It should
+ * be stable for the lifetime of the engine instance.
+ *
+ * @return engine name
+ */
+ String getName();
+
+ /**
+ * Returns the engine type.
+ *
+ * This identifies the concrete backend family, such as LRU, BUCKET, or
CARROT. The type is useful
+ * for metrics, diagnostics, and topology assembly.
+ *
+ * @return engine type
+ */
+ CacheEngineType getType();
+
+ /**
+ * Adds a block to the cache.
+ * @param cacheKey block cache key
+ * @param buf block contents
+ * @param inMemory whether the block should be treated as in-memory
+ */
+ void cacheBlock(BlockCacheKey cacheKey, Cacheable buf, boolean inMemory);
+
+ /**
+ * Adds a block to the cache, optionally waiting for asynchronous cache
backends.
+ *
+ * This is primarily useful for implementations such as BucketCache that may
buffer writes
+ * asynchronously.
+ *
+ * @param cacheKey block cache key
+ * @param buf block contents
+ * @param inMemory whether the block should be treated as in-memory
+ * @param waitWhenCache whether to wait for the cache operation to be
accepted/flushed
+ */
+ default void cacheBlock(BlockCacheKey cacheKey, Cacheable buf, boolean
inMemory,
+boolean waitWhenCache) {
+cacheBlock(cacheKey, buf, inMemory);
+ }
+
+ /**
+ * Adds a block to the cache, defaulting to non in-memory treatment.
+ * @param cacheKey block cache key
+ * @param buf block contents
+ */
+ void cacheBlock(BlockCacheKey cacheKey, Cacheable buf);
+
+ /**
+ * Fetches a block from the cache.
+ * @param cacheKey block to fetch
+ * @param cachingwhether caching is enabled for the request;
used for metrics
+ * @param repeat whether this is a repeated lookup for the same
block; used to avoid
+ * double-counting misses
+ * @param updateCacheMetrics whether cache metrics should be updated
+ * @return cached block, or {@code null} if not present
+ */
+ Cacheable getBlock(BlockCacheKey cacheKey, boolean caching, boolean repeat,
+boolean updateCacheMetrics);
+
+ /**
+
Re: [PR] HBASE-30019 Introduce CacheEngine and CacheTopology abstractions [hbase]
VladRodionov commented on code in PR #8155: URL: https://github.com/apache/hbase/pull/8155#discussion_r3156103477 ## hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheEngineType.java: ## @@ -0,0 +1,41 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.hadoop.hbase.io.hfile.cache; + +import org.apache.yetus.audience.InterfaceAudience; + +/** + * Identifies the concrete cache engine family. + */ [email protected] +public enum CacheEngineType { + /** + * Heap-based LRU cache engine. + */ + LRU, + + /** + * Bucket-based off-heap / file-backed cache engine. + */ + BUCKET, + + /** + * CarrotCache-based engine. + */ + CARROT Review Comment: Good point. CarrotCache should not need to be a hard dependency of hbase-server for this foundational API. I think using a fixed enum for engine types is too restrictive for a pluggable architecture anyway. It works for built-ins like LRU/Bucket, but does not scale well for optional or third-party engines. I’ll remove CacheEngineType and rely on getName() / configuration identity instead. That keeps the core API independent of optional engines and avoids baking specific external implementations into HBase. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [PR] HBASE-30019 Introduce CacheEngine and CacheTopology abstractions [hbase]
taklwu commented on code in PR #8155: URL: https://github.com/apache/hbase/pull/8155#discussion_r3155685368 ## hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheEngineType.java: ## @@ -0,0 +1,41 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.hadoop.hbase.io.hfile.cache; + +import org.apache.yetus.audience.InterfaceAudience; + +/** + * Identifies the concrete cache engine family. + */ [email protected] +public enum CacheEngineType { + /** + * Heap-based LRU cache engine. + */ + LRU, + + /** + * Bucket-based off-heap / file-backed cache engine. + */ + BUCKET, + + /** + * CarrotCache-based engine. + */ + CARROT Review Comment: nit: will carrot be the dependencies of hbase? if not, maybe this could be removed? or should we use interface factory with getName instead of enum? ## hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheEngine.java: ## @@ -0,0 +1,302 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.hadoop.hbase.io.hfile.cache; + +import java.util.Optional; +import org.apache.hadoop.conf.Configuration; +import org.apache.hadoop.hbase.io.hfile.BlockCacheKey; +import org.apache.hadoop.hbase.io.hfile.BlockType; +import org.apache.hadoop.hbase.io.hfile.CacheStats; +import org.apache.hadoop.hbase.io.hfile.Cacheable; +import org.apache.hadoop.hbase.io.hfile.HFileBlock; +import org.apache.yetus.audience.InterfaceAudience; + +/** + * Storage abstraction for a concrete HBase block cache backend. + * + * A {@code CacheEngine} represents the storage layer only. It is responsible for storing, + * retrieving, invalidating, and reporting statistics for cached blocks. It does not perform tier + * orchestration, admission control, placement decisions, or promotion/demotion across cache levels. + * + * + * This interface is intentionally aligned with the storage-oriented subset of the current + * {@code BlockCache} contract so that existing implementations such as LruBlockCache and + * BucketCache can be migrated incrementally with minimal behavioral risk. + * + * + * Responsibilities of a {@code CacheEngine} include: + * + * + * block lookup + * block insertion + * targeted invalidation / eviction + * capacity and occupancy reporting + * engine-local statistics + * optional implementation-specific fit/capability checks + * + * + * Non-responsibilities include: + * + * + * L1/L2 topology orchestration + * admission policy + * tier placement decisions + * promotion or demotion across tiers + * + */ [email protected] +public interface CacheEngine { + + /** + * Returns a human-readable name for this cache engine instance. + * + * The name is intended for logging, metrics, diagnostics, and configuration reporting. It should + * be stable for the lifetime of the engine instance. + * + * @return engine name + */ + String getName(); + + /** + * Returns the engine type. + * + * This identifies the concrete backend family, such as LRU, BUCKET, or CARROT. The type is useful + * for metrics, diagnostics, and topology assembly. + * + * @return engine type + */ + CacheEngineType getType(); + + /** + * Adds a block to the cache. + * @param cacheKey block cache key + * @param buf block contents + * @param inMemory whether the block should be treated as in-memory + */ + voi
Re: [PR] HBASE-30019 Introduce CacheEngine and CacheTopology abstractions [hbase]
VladRodionov commented on code in PR #8155:
URL: https://github.com/apache/hbase/pull/8155#discussion_r3151189185
##
hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheTopologyView.java:
##
@@ -0,0 +1,87 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.hadoop.hbase.io.hfile.cache;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.stream.Collectors;
+import org.apache.yetus.audience.InterfaceAudience;
+
+/**
+ * Default immutable-style read-only view over a {@link CacheTopology}.
+ *
+ * This view delegates to the topology and exposes only read-only engine
views.
+ */
[email protected]
+final class CacheTopologyView {
+
+ private final CacheTopology topology;
+
+ /**
+ * Constructs a CacheTopologyView for the given CacheTopology.
+ */
+ CacheTopologyView(CacheTopology topology) {
+this.topology = topology;
+ }
+
+ /**
+ * Delegating getters for topology properties and read-only engine views.
+ */
+
+ public String getName() {
+return topology.getName();
+ }
+ /**
+ * Returns the cache topology type, which can be SINGLE, L1_L2, or CUSTOM.
+ * @return the cache topology type
+ */
+ public CacheTopologyType getType() {
+return topology.getType();
Review Comment:
Done.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
Re: [PR] HBASE-30019 Introduce CacheEngine and CacheTopology abstractions [hbase]
VladRodionov commented on code in PR #8155:
URL: https://github.com/apache/hbase/pull/8155#discussion_r3151165153
##
hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheTopologyView.java:
##
@@ -0,0 +1,87 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.hadoop.hbase.io.hfile.cache;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.stream.Collectors;
+import org.apache.yetus.audience.InterfaceAudience;
+
+/**
+ * Default immutable-style read-only view over a {@link CacheTopology}.
+ *
+ * This view delegates to the topology and exposes only read-only engine
views.
+ */
[email protected]
+final class CacheTopologyView {
+
+ private final CacheTopology topology;
+
+ /**
+ * Constructs a CacheTopologyView for the given CacheTopology.
+ */
+ CacheTopologyView(CacheTopology topology) {
+this.topology = topology;
+ }
+
+ /**
+ * Delegating getters for topology properties and read-only engine views.
+ */
+
+ public String getName() {
+return topology.getName();
+ }
+ /**
+ * Returns the cache topology type, which can be SINGLE, L1_L2, or CUSTOM.
+ * @return the cache topology type
+ */
+ public CacheTopologyType getType() {
+return topology.getType();
+ }
+
+ /**
+ * Returns the list of cache tiers in this topology. For a single-tier
topology, it returns a list
+ * containing only CacheTier.SINGLE. For a multi-tier topology, it returns a
list containing
+ * CacheTier.L1 and CacheTier.L2.
+ * @return the list of cache tiers in this topology
+ */
+ public List getTiers() {
+return topology.getEngines().size() == 1
+ ? List.of(CacheTier.SINGLE)
+ : List.of(CacheTier.L1, CacheTier.L2);
Review Comment:
Good point. I removed CUSTOM topology, but I agree the current
implementation is still too implicit.
Inferring tiers from getEngines().size() is brittle. I will add an explicit
getTiers() method to CacheTopology and have CacheTopologyView delegate to it
instead of deriving tiers from engine count.
That keeps tier ownership in the topology implementation and avoids
assumptions in the view layer.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
Re: [PR] HBASE-30019 Introduce CacheEngine and CacheTopology abstractions [hbase]
VladRodionov commented on code in PR #8155:
URL: https://github.com/apache/hbase/pull/8155#discussion_r3151150539
##
hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheTopology.java:
##
@@ -0,0 +1,177 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.hadoop.hbase.io.hfile.cache;
+
+import java.util.List;
+import java.util.Optional;
+import org.apache.hadoop.hbase.io.hfile.BlockCacheKey;
+import org.apache.hadoop.hbase.io.hfile.CacheStats;
+import org.apache.hadoop.hbase.io.hfile.Cacheable;
+import org.apache.yetus.audience.InterfaceAudience;
+
+/**
+ * Describes orchestration of one or more cache engines.
+ *
+ * {@code CacheTopology} is responsible for the structural relationship
between cache engines,
+ * for example a single-engine cache, a tiered exclusive L1/L2 cache, or a
tiered inclusive L1/L2
+ * cache.
+ *
+ * This abstraction does not own storage. Storage belongs to {@link
CacheEngine}. This
+ * abstraction also does not decide admission or write placement. Admission,
placement,
+ * representation, and promotion decisions belong to the policy layer.
+ *
+ * Responsibilities of a cache topology include:
+ *
+ * exposing participating cache engines
+ * mapping engines to logical tiers such as L1 and L2
+ * providing aggregate cache statistics
+ * performing topology-specific promotion when requested by policy
+ * optionally performing topology-specific demotion
+ * coordinating shutdown of participating engines
+ *
+ *
+ * Non-responsibilities include:
+ *
+ * block storage
+ * local eviction algorithms
+ * cache admission control
+ * write routing / target tier selection
+ * HFile read/write path integration
+ *
+ */
[email protected]
+public interface CacheTopology {
+
+ /**
+ * Returns a human-readable topology name.
+ *
+ * The name is intended for logging, metrics, diagnostics, and
configuration reporting. It
+ * should be stable for the lifetime of this topology instance.
+ *
+ * @return topology name
+ */
+ String getName();
+
+ /**
+ * Returns the topology type.
+ *
+ * The type identifies the topology family, such as single-engine, tiered
exclusive, or tiered
+ * inclusive.
+ *
+ * @return topology type
+ */
+ CacheTopologyType getType();
+
+ /**
+ * Returns the cache engines participating in this topology.
+ *
+ * The returned list is primarily intended for diagnostics, metrics, and
topology inspection.
+ * Callers should not use it to bypass topology and policy logic for normal
cache operations.
+ *
+ * @return participating cache engines
+ */
+ List getEngines();
+
+ /**
+ * Returns the cache engine associated with the given logical tier, if one
exists.
+ *
+ * For example, a tiered topology may expose an L1 and L2 engine. A
single-engine topology may
+ * return an engine for {@link CacheTier#SINGLE} and an empty result for
L1/L2.
+ *
+ * @param tier logical cache tier
+ * @return cache engine for the tier, or empty if this topology does not
define that tier
+ */
+ Optional getEngine(CacheTier tier);
+
+ /**
+ * Returns aggregate topology-level cache statistics.
+ *
+ * For a single-engine topology, this may simply return the underlying
engine statistics. For a
+ * multi-engine topology, this should represent an aggregate view suitable
for compatibility with
+ * existing HBase block cache metrics.
+ *
+ * @return aggregate cache statistics
+ */
+ CacheStats getStats();
+
+ /**
+ * Promotes a cached block from one engine to another.
+ *
+ * This method performs the topology-specific mechanics of promotion. The
decision whether a
+ * block should be promoted belongs to the placement/admission policy layer.
For example, a policy
+ * may decide that an index block found in L2 should be promoted to L1, and
then call this method
+ * to perform the promotion.
+ *
+ * Implementations may either copy or move the block depending on
topology semantics. For
+ * example:
+ *
+ * inclusive topology may copy the block into the target tier while
retaining it in source
+ * exclusive topology may move the block into th
Re: [PR] HBASE-30019 Introduce CacheEngine and CacheTopology abstractions [hbase]
VladRodionov commented on code in PR #8155:
URL: https://github.com/apache/hbase/pull/8155#discussion_r3151112264
##
hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheEngine.java:
##
@@ -0,0 +1,319 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.hadoop.hbase.io.hfile.cache;
+
+import java.util.Optional;
+import org.apache.hadoop.conf.Configuration;
+import org.apache.hadoop.hbase.io.hfile.BlockCacheKey;
+import org.apache.hadoop.hbase.io.hfile.BlockType;
+import org.apache.hadoop.hbase.io.hfile.CacheStats;
+import org.apache.hadoop.hbase.io.hfile.Cacheable;
+import org.apache.hadoop.hbase.io.hfile.HFileBlock;
+import org.apache.yetus.audience.InterfaceAudience;
+
+/**
+ * Storage abstraction for a concrete HBase block cache backend.
+ *
+ * A {@code CacheEngine} represents the storage layer only. It is
responsible for storing,
+ * retrieving, invalidating, and reporting statistics for cached blocks. It
does not perform
+ * tier orchestration, admission control, placement decisions, or
promotion/demotion across
+ * cache levels.
+ *
+ * This interface is intentionally aligned with the storage-oriented subset
of the current
+ * {@code BlockCache} contract so that existing implementations such as
LruBlockCache and
+ * BucketCache can be migrated incrementally with minimal behavioral risk.
+ *
+ * Responsibilities of a {@code CacheEngine} include:
+ *
+ * block lookup
+ * block insertion
+ * targeted invalidation / eviction
+ * capacity and occupancy reporting
+ * engine-local statistics
+ * optional implementation-specific fit/capability checks
+ *
+ *
+ * Non-responsibilities include:
+ *
+ * L1/L2 topology orchestration
+ * admission policy
+ * tier placement decisions
+ * promotion or demotion across tiers
+ *
+ */
[email protected]
+public interface CacheEngine {
+
+ /**
+ * Returns a human-readable name for this cache engine instance.
+ *
+ * The name is intended for logging, metrics, diagnostics, and
configuration reporting.
+ * It should be stable for the lifetime of the engine instance.
+ *
+ * @return engine name
+ */
+ String getName();
+
+ /**
+ * Returns the engine type.
+ *
+ * This identifies the concrete backend family, such as LRU, BUCKET, or
CARROT. The type
+ * is useful for metrics, diagnostics, and topology assembly.
+ *
+ * @return engine type
+ */
+ CacheEngineType getType();
+
+ /**
+ * Adds a block to the cache.
+ *
+ * @param cacheKey block cache key
+ * @param buf block contents
+ * @param inMemory whether the block should be treated as in-memory
+ */
+ void cacheBlock(BlockCacheKey cacheKey, Cacheable buf, boolean inMemory);
+
+ /**
+ * Adds a block to the cache, optionally waiting for asynchronous cache
backends.
+ *
+ * This is primarily useful for implementations such as BucketCache that
may buffer writes
+ * asynchronously.
+ *
+ * @param cacheKey block cache key
+ * @param buf block contents
+ * @param inMemory whether the block should be treated as in-memory
+ * @param waitWhenCache whether to wait for the cache operation to be
accepted/flushed
+ */
+ default void cacheBlock(BlockCacheKey cacheKey, Cacheable buf, boolean
inMemory,
+ boolean waitWhenCache) {
+cacheBlock(cacheKey, buf, inMemory);
+ }
+
+ /**
+ * Adds a block to the cache, defaulting to non in-memory treatment.
+ *
+ * @param cacheKey block cache key
+ * @param buf block contents
+ */
+ void cacheBlock(BlockCacheKey cacheKey, Cacheable buf);
+
+ /**
+ * Fetches a block from the cache.
+ *
+ * @param cacheKey block to fetch
+ * @param caching whether caching is enabled for the request; used for
metrics
+ * @param repeat whether this is a repeated lookup for the same block; used
to avoid
+ * double-counting misses
+ * @param updateCacheMetrics whether cache metrics should be updated
+ * @return cached block, or {@code null} if not present
+ */
+ Cacheable getBlock(BlockCacheKey cacheKey, boolean caching, boolean repeat,
+ boolean updateCacheMetrics);
+
+ /**
+ * Fetches a block from the cache with an optional block t
Re: [PR] HBASE-30019 Introduce CacheEngine and CacheTopology abstractions [hbase]
Copilot commented on code in PR #8155:
URL: https://github.com/apache/hbase/pull/8155#discussion_r3150543540
##
hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheTopology.java:
##
@@ -0,0 +1,177 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.hadoop.hbase.io.hfile.cache;
+
+import java.util.List;
+import java.util.Optional;
+import org.apache.hadoop.hbase.io.hfile.BlockCacheKey;
+import org.apache.hadoop.hbase.io.hfile.CacheStats;
+import org.apache.hadoop.hbase.io.hfile.Cacheable;
+import org.apache.yetus.audience.InterfaceAudience;
+
+/**
+ * Describes orchestration of one or more cache engines.
+ *
+ * {@code CacheTopology} is responsible for the structural relationship
between cache engines,
+ * for example a single-engine cache, a tiered exclusive L1/L2 cache, or a
tiered inclusive L1/L2
+ * cache.
Review Comment:
The class-level Javadoc contains lines that look to exceed the 100-character
Checkstyle limit (LineLength max=100), e.g. the wrapped sentence about tiered
exclusive/inclusive caches here. Please reflow/wrap these lines to avoid
Checkstyle failures.
```suggestion
* {@code CacheTopology} is responsible for the structural relationship
between
* cache engines, for example a single-engine cache, a tiered exclusive L1/L2
* cache, or a tiered inclusive L1/L2 cache.
```
##
hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/SingleEngineTopology.java:
##
@@ -0,0 +1,87 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.hadoop.hbase.io.hfile.cache;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Optional;
+import org.apache.hadoop.hbase.io.hfile.BlockCacheKey;
+import org.apache.hadoop.hbase.io.hfile.CacheStats;
+import org.apache.hadoop.hbase.io.hfile.Cacheable;
+import org.apache.yetus.audience.InterfaceAudience;
+
+/**
+ * Single-engine cache topology.
+ *
+ * This topology wraps a single {@link CacheEngine}. It is primarily useful
as a baseline
+ * topology and as a simple bridge for cache configurations that do not use
L1/L2 tiering.
Review Comment:
The class Javadoc here looks to exceed the 100-character Checkstyle
LineLength limit (max=100), especially the sentence on the second line of this
paragraph. Please wrap/reflow to avoid Checkstyle failures.
```suggestion
* This topology wraps a single {@link CacheEngine}. It is primarily
useful as a
* baseline topology and as a simple bridge for cache configurations that do
not use
* L1/L2 tiering.
```
##
hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheTopologyView.java:
##
@@ -0,0 +1,87 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See
Re: [PR] HBASE-30019 Introduce CacheEngine and CacheTopology abstractions [hbase]
VladRodionov commented on code in PR #8155: URL: https://github.com/apache/hbase/pull/8155#discussion_r3150380290 ## hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheEngineType.java: ## @@ -0,0 +1,46 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.hadoop.hbase.io.hfile.cache; + +import org.apache.yetus.audience.InterfaceAudience; + +/** + * Identifies the concrete cache engine family. + */ [email protected] +public enum CacheEngineType { + /** + * Heap-based LRU cache engine. + */ + LRU, + + /** + * Bucket-based off-heap / file-backed cache engine. + */ + BUCKET, + + /** + * CarrotCache-based engine. + */ + CARROT, + + /** + * Other or custom engine type. + */ + CUSTOM Review Comment: Its just a stub, any engine should has its own type. I will remove it. Its confusing. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
Re: [PR] HBASE-30019 Introduce CacheEngine and CacheTopology abstractions [hbase]
VladRodionov commented on code in PR #8155:
URL: https://github.com/apache/hbase/pull/8155#discussion_r3150372779
##
hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheEngine.java:
##
@@ -0,0 +1,319 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.hadoop.hbase.io.hfile.cache;
+
+import java.util.Optional;
+import org.apache.hadoop.conf.Configuration;
+import org.apache.hadoop.hbase.io.hfile.BlockCacheKey;
+import org.apache.hadoop.hbase.io.hfile.BlockType;
+import org.apache.hadoop.hbase.io.hfile.CacheStats;
+import org.apache.hadoop.hbase.io.hfile.Cacheable;
+import org.apache.hadoop.hbase.io.hfile.HFileBlock;
+import org.apache.yetus.audience.InterfaceAudience;
+
+/**
+ * Storage abstraction for a concrete HBase block cache backend.
+ *
+ * A {@code CacheEngine} represents the storage layer only. It is
responsible for storing,
+ * retrieving, invalidating, and reporting statistics for cached blocks. It
does not perform
+ * tier orchestration, admission control, placement decisions, or
promotion/demotion across
+ * cache levels.
+ *
+ * This interface is intentionally aligned with the storage-oriented subset
of the current
+ * {@code BlockCache} contract so that existing implementations such as
LruBlockCache and
+ * BucketCache can be migrated incrementally with minimal behavioral risk.
+ *
+ * Responsibilities of a {@code CacheEngine} include:
+ *
+ * block lookup
+ * block insertion
+ * targeted invalidation / eviction
+ * capacity and occupancy reporting
+ * engine-local statistics
+ * optional implementation-specific fit/capability checks
+ *
+ *
+ * Non-responsibilities include:
+ *
+ * L1/L2 topology orchestration
+ * admission policy
+ * tier placement decisions
+ * promotion or demotion across tiers
+ *
+ */
[email protected]
+public interface CacheEngine {
Review Comment:
Partially yes, but overall CacheAccessService will be an access point to a
caching system. Future ticket.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
Re: [PR] HBASE-30019 Introduce CacheEngine and CacheTopology abstractions [hbase]
wchevreuil commented on code in PR #8155: URL: https://github.com/apache/hbase/pull/8155#discussion_r3149998680 ## hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheEngineType.java: ## @@ -0,0 +1,46 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.hadoop.hbase.io.hfile.cache; + +import org.apache.yetus.audience.InterfaceAudience; + +/** + * Identifies the concrete cache engine family. + */ [email protected] +public enum CacheEngineType { + /** + * Heap-based LRU cache engine. + */ + LRU, + + /** + * Bucket-based off-heap / file-backed cache engine. + */ + BUCKET, + + /** + * CarrotCache-based engine. + */ + CARROT, + + /** + * Other or custom engine type. + */ + CUSTOM Review Comment: So different custom implementations would all fall under this CUSTOM enum type? ## hbase-server/src/main/java/org/apache/hadoop/hbase/io/hfile/cache/CacheEngine.java: ## @@ -0,0 +1,319 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.hadoop.hbase.io.hfile.cache; + +import java.util.Optional; +import org.apache.hadoop.conf.Configuration; +import org.apache.hadoop.hbase.io.hfile.BlockCacheKey; +import org.apache.hadoop.hbase.io.hfile.BlockType; +import org.apache.hadoop.hbase.io.hfile.CacheStats; +import org.apache.hadoop.hbase.io.hfile.Cacheable; +import org.apache.hadoop.hbase.io.hfile.HFileBlock; +import org.apache.yetus.audience.InterfaceAudience; + +/** + * Storage abstraction for a concrete HBase block cache backend. + * + * A {@code CacheEngine} represents the storage layer only. It is responsible for storing, + * retrieving, invalidating, and reporting statistics for cached blocks. It does not perform + * tier orchestration, admission control, placement decisions, or promotion/demotion across + * cache levels. + * + * This interface is intentionally aligned with the storage-oriented subset of the current + * {@code BlockCache} contract so that existing implementations such as LruBlockCache and + * BucketCache can be migrated incrementally with minimal behavioral risk. + * + * Responsibilities of a {@code CacheEngine} include: + * + * block lookup + * block insertion + * targeted invalidation / eviction + * capacity and occupancy reporting + * engine-local statistics + * optional implementation-specific fit/capability checks + * + * + * Non-responsibilities include: + * + * L1/L2 topology orchestration + * admission policy + * tier placement decisions + * promotion or demotion across tiers + * + */ [email protected] +public interface CacheEngine { + + /** + * Returns a human-readable name for this cache engine instance. + * + * The name is intended for logging, metrics, diagnostics, and configuration reporting. + * It should be stable for the lifetime of the engine instance. + * + * @return engine name + */ + String getName(); + + /** + * Returns the engine type. + * + * This identifies the concrete backend family, such as LRU, BUCKET, or CARROT. The type + * is useful for metrics, diagnostics, and topology assembly. + * + * @return engine type + */ + CacheEngineType getType(); + + /** + * Adds a block to the cache. + * + * @param cacheKey block cache key + * @param buf block contents + * @param inMemory whether the block should be treated as in-memory + */ + void cacheBlock(
Re: [PR] HBASE-30019 Introduce CacheEngine and CacheTopology abstractions [hbase]
VladRodionov closed pull request #8154: HBASE-30019 Introduce CacheEngine and CacheTopology abstractions URL: https://github.com/apache/hbase/pull/8154 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
