Skip to content

Note that cache impls are monotonically increasing counters in Javadoc - #6516

Open
Amemeda wants to merge 3 commits into
apache:2.1from
Amemeda:spi-javadoc
Open

Note that cache impls are monotonically increasing counters in Javadoc#6516
Amemeda wants to merge 3 commits into
apache:2.1from
Amemeda:spi-javadoc

Conversation

@Amemeda

@Amemeda Amemeda commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

Update SPI javadoc to note that cache impls are monotonically increasing counters.

Added to javadoc in BlockCache.Stats.java interface.

This pr closes #4530

@Amemeda
Amemeda changed the base branch from main to 2.1 August 26, 2026 17:40
Comment on lines 45 to 49
@Override
public void registerMetrics(MeterRegistry registry) {
ToDoubleFunction<BlockCache> getHitCount = cache -> cache.getStats().hitCount();
ToDoubleFunction<BlockCache> getRequestCount = cache -> cache.getStats().requestCount();

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was the only area I could find "cache impls" using the counters, if there are more, I may need to pointed in the right direction

@DomGarguilo DomGarguilo left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think BlockCacheMetrics is the wrong spot for this comment since its internal code that nobody implements. The intent should be to notify plugin authors. I think the BlockCache.Stats interface is the correct spot for things.

This BlockCache implementation is a monotonically increasing counter, the counter should not reset or
decrease the counts as the metrics rely on these values being monotonically increasing.

I also think this could be improved in a few ways

  1. the counts are monotonic not the cache. Something like "All counts returned by this interface must be monotonically increasing" seems more correct to me
  2. since the goal is to outline the contract we should say "must never" instead of "should not" so it reads as a requirement instead of a suggestion
  3. I think the why could be improved. "shouldn't reset because the metrics rely on it not resetting" is kinda what its saying now which is circular reasoning. Something that explains that the values are read periodically and what matters is how much things go up between those readings so an implementation must never reset or decrease them.

@dlmarion dlmarion added this to the 2.1.7 milestone Aug 27, 2026
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.

Update SPI javadoc for cache impls to note they are monotonically increasing counters

3 participants