28916241081

Committed 08 Jul 2026 03:53AM UTC coverage: 89.468% (-0.7%) from 90.12%

Build # 28916241081

Build Type

push

github

Committed by

Hyshmily

Commit Message

refactor(core): extract central dispatcher and broadcast buffer

Introduce CentralDispatcher for centralized event routing and BroadcastBuffer for cache synchronization. Refactor HotKeyCache, SlidingWindowDetector, and related components to use the new dispatching mechanism, improving separation of concerns and reducing coupling.

Signed-off-by: Hyshmily <cxm8607@outlook.com>

Coverage Stats

1328 of 1564 branches covered (84.91%)

Branch coverage included in aggregate %.

102 of 134 new or added lines in 17 files covered. (76.12%)

3 existing lines in 2 files now uncovered.

3769 of 4133 relevant lines covered (91.19%)

4.21 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

50.0

/common/src/main/java/io/github/hyshmily/hotkey/hotkeydetector/heavykeeper/TopK.java

/*
 * Copyright 2026 Hyshmily. All Rights Reserved.
 *
 * Licensed 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 io.github.hyshmily.hotkey.hotkeydetector.heavykeeper;

import java.util.List;
import java.util.Map;
import java.util.concurrent.BlockingQueue;

/**
 * Top‑K hot key detection interface.
 *
 * <p>Implementations track the most frequently accessed keys using a
 * sketch-based algorithm (e.g. HeavyKeeper) and provide access to the
 * current ranking (sorted by estimated frequency descending), expelled
 * items (keys evicted when the TopK set is full), and the total tracked
 * request count.
 *
 * <p>The interface supports both single-key and batch access recording,
 * periodic frequency decay ({@link #fading}), and read-only introspection
 * ({@link #list}, {@link #contains}, {@link #total}).
 *
 * <p>Implementations are expected to be thread-safe.
 */
public interface TopK {
  /**
   * Record one or more accesses for the given key.
   *
   * @param key       the accessed key
   * @param increment the number of accesses to record
   * @return the  result indicating whether the key became hot and whether another key was evicted
   */
  AddResult addDirect(String key, int increment);

  /**
   * Record accesses for multiple keys in batch.
   *
   * <p>Always updates both the sketch counters and the TopK heap. More
   * efficient than repeated {@link #addDirect(String, int)} calls because
   * the heap is updated once for the entire batch rather than per-key,
   * reducing locking overhead. Returns results only for keys that actually
   * entered the TopK set (possibly displacing existing members).
   *
   * @param keyCounts map of keys to their access counts
   * @return list of {@link AddResult} for keys that entered the TopK set
   */
  List<AddResult> addDirect(Map<String, Long> keyCounts);

  /**
   * Return the current TopK list sorted by frequency (descending).
   *
   * @return list of {@link Item} entries, never {@code null}
   */
  List<Item> list();

  /**
   * Return the top N hot keys.
   *
   * @param n maximum number of keys to return
   * @return list of at most {@code n} {@link Item} entries
   */
  List<Item> listTopN(int n);

  /**
   * Return the queue of items that have been evicted from the TopK set.
   * Consumers should drain this queue periodically for asynchronous processing.
   *
   * @return a blocking queue of evicted items
   */
  BlockingQueue<Item> expelled();

  /**
   * Directly inject key-count pairs into the TopK set, bypassing the
   * sketch admission path. Used for warming up from a persisted snapshot
   * where the keys are already known to be hot.
   * <p>
   * Implementations must respect the capacity limit ({@code k}) and may
   * evict the weakest members when full. The default implementation
   * delegates to {@link #addDirect(Map)} for backward compatibility.
   *
   * @param keyCounts map of keys to their estimated counts
   */
  default void warm(Map<String, Long> keyCounts) {
    addDirect(keyCounts);
  }

  /**
   * Decay all frequency counts to age out historical data and prevent
   * stale frequency accumulation.
   *
   * <p>Typically invoked periodically by a scheduler (e.g. every 30
   * seconds). The implementation halves all sketch counters and heap
   * entry counts, discarding entries whose count drops to zero. This
   * ensures that the TopK set reflects recent access patterns rather
   * than cumulative historical popularity.
   */
  void fading();

  /**
   * Return the approximate number of distinct keys currently tracked (0 to k).
   *
   * @return estimated number of keys in the top-K set
   */
  default int estimatedSize() {
    return list().size();
  }

  /**
   * Return the total number of data streams (accesses) tracked since startup.
   *
   * @return total access count
   */
  long total();

  /**
   * Check whether the given key is currently in the TopK set.
   *
   * @param key the key to check
   * @return {@code true} if the key is present in the current TopK ranking
   */
  default boolean contains(String key) {
    return list()
      .stream()
      .anyMatch(item -> item.key().equals(key));
  }
}

1	/*
2	* Copyright 2026 Hyshmily. All Rights Reserved.
3	*
4	* Licensed under the Apache License, Version 2.0 (the "License");
5	* you may not use this file except in compliance with the License.
6	* You may obtain a copy of the License at
7	*
8	* http://www.apache.org/licenses/LICENSE-2.0
9	*
10	* Unless required by applicable law or agreed to in writing, software
11	* distributed under the License is distributed on an "AS IS" BASIS,
12	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13	* See the License for the specific language governing permissions and
14	* limitations under the License.
15	*/
16	package io.github.hyshmily.hotkey.hotkeydetector.heavykeeper;
17
18	import java.util.List;
19	import java.util.Map;
20	import java.util.concurrent.BlockingQueue;
21
22	/**
23	* Top‑K hot key detection interface.
24	*
25	* <p>Implementations track the most frequently accessed keys using a
26	* sketch-based algorithm (e.g. HeavyKeeper) and provide access to the
27	* current ranking (sorted by estimated frequency descending), expelled
28	* items (keys evicted when the TopK set is full), and the total tracked
29	* request count.
30	*
31	* <p>The interface supports both single-key and batch access recording,
32	* periodic frequency decay ({@link #fading}), and read-only introspection
33	* ({@link #list}, {@link #contains}, {@link #total}).
34	*
35	* <p>Implementations are expected to be thread-safe.
36	*/
37	public interface TopK {
38	/**
39	* Record one or more accesses for the given key.
40	*
41	* @param key the accessed key
42	* @param increment the number of accesses to record
43	* @return the result indicating whether the key became hot and whether another key was evicted
44	*/
45	AddResult addDirect(String key, int increment);
46
47	/**
48	* Record accesses for multiple keys in batch.
49	*
50	* <p>Always updates both the sketch counters and the TopK heap. More
51	* efficient than repeated {@link #addDirect(String, int)} calls because
52	* the heap is updated once for the entire batch rather than per-key,
53	* reducing locking overhead. Returns results only for keys that actually
54	* entered the TopK set (possibly displacing existing members).
55	*
56	* @param keyCounts map of keys to their access counts
57	* @return list of {@link AddResult} for keys that entered the TopK set
58	*/
59	List<AddResult> addDirect(Map<String, Long> keyCounts);
60
61	/**
62	* Return the current TopK list sorted by frequency (descending).
63	*
64	* @return list of {@link Item} entries, never {@code null}
65	*/
66	List<Item> list();
67
68	/**
69	* Return the top N hot keys.
70	*
71	* @param n maximum number of keys to return
72	* @return list of at most {@code n} {@link Item} entries
73	*/
74	List<Item> listTopN(int n);
75
76	/**
77	* Return the queue of items that have been evicted from the TopK set.
78	* Consumers should drain this queue periodically for asynchronous processing.
79	*
80	* @return a blocking queue of evicted items
81	*/
82	BlockingQueue<Item> expelled();
83
84	/**
85	* Directly inject key-count pairs into the TopK set, bypassing the
86	* sketch admission path. Used for warming up from a persisted snapshot
87	* where the keys are already known to be hot.
88	* <p>
89	* Implementations must respect the capacity limit ({@code k}) and may
90	* evict the weakest members when full. The default implementation
91	* delegates to {@link #addDirect(Map)} for backward compatibility.
92	*
93	* @param keyCounts map of keys to their estimated counts
94	*/
95	default void warm(Map<String, Long> keyCounts) {
NEW 96	addDirect(keyCounts);	×
NEW 97	}	×
98
99	/**
100	* Decay all frequency counts to age out historical data and prevent
101	* stale frequency accumulation.
102	*
103	* <p>Typically invoked periodically by a scheduler (e.g. every 30
104	* seconds). The implementation halves all sketch counters and heap
105	* entry counts, discarding entries whose count drops to zero. This
106	* ensures that the TopK set reflects recent access patterns rather
107	* than cumulative historical popularity.
108	*/
109	void fading();
110
111	/**
112	* Return the approximate number of distinct keys currently tracked (0 to k).
113	*
114	* @return estimated number of keys in the top-K set
115	*/
116	default int estimatedSize() {
117	return list().size();	×
118	}
119
120	/**
121	* Return the total number of data streams (accesses) tracked since startup.
122	*
123	* @return total access count
124	*/
125	long total();
126
127	/**
128	* Check whether the given key is currently in the TopK set.
129	*
130	* @param key the key to check
131	* @return {@code true} if the key is present in the current TopK ranking
132	*/
133	default boolean contains(String key) {
134	return list()	3✔
135	.stream()	3✔
136	.anyMatch(item -> item.key().equals(key));	6✔
137	}
138	}

Hyshmily / hotkey / 28916241081

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous