Class FrequencyGatedBidirectionalObjectToIdMap<V>
- Type Parameters:
V- value type (must have correctequals/hashCodefor map keys)
- All Implemented Interfaces:
BidirectionalObjectToIdMap<V>
BidirectionalObjectToIdMap that only assigns stable ids to values after they have
been seen often enough on the write path.
Motivation
A plain BidirectionalObjectToIdMapDefault caches every distinct value on first
sight. For high-cardinality fields (log messages, MDC values, exception text) that creates a
large cache of one-off entries and little compression benefit: the stream still pays for a
NEW_ENTRY header plus a full payload, and the map fills with values that never recur.
This implementation gates registration by frequency. A value is not entered into
the id map until it has been written more than MIN_HITS times. Until then, writers
emit a full payload under a sentinel id (KryoCoreConstants.UNREGISTERED_ID); only
on later occurrences is a real id assigned so subsequent writes can emit a compact
CACHED_ENTRY reference.
Write-path protocol
Used by SerializerBase.write(Kryo, Output, V) as follows:
getIdByValue(Object)— if a real id exists, emitCACHED_ENTRY+ id (no payload).- Otherwise
insertNewEntryOnWrite(Object):- Increments the per-value access count.
- If
count <= MIN_HITS: returnsKryoCoreConstants.UNREGISTERED_ID(-1) and does not store the value in the id map. - If
count > MIN_HITS: assigns the next id, stores the mapping, returns that id.
- In both unregistered and newly registered cases,
SerializerBasestill writesNEW_ENTRY+ the returned id + the full payload viawriteNewEntry.
Thus the first sighting of a value always carries a full payload with id -1. The
second sighting (with default MIN_HITS = 1) carries a full payload again, but with a
real id that is stored for later CACHED_ENTRY hits.
Read-path protocol
SerializerBase.read(Kryo, Input, Class) reads the entry flag and id, then:
- For
NEW_ENTRY: deserializes the payload; if the id is notKryoCoreConstants.UNREGISTERED_ID, registers it viainsertNewEntryOnRead(int, Object); unregistered ids are not stored. - For
CACHED_ENTRY: looks up the value withgetValueById(int)(must already have been registered by a priorNEW_ENTRYwith a real id).
Read-side registration is not frequency-gated: the stream is authoritative. Gating applies only when assigning ids on write.
State
- Id map — a
BidirectionalObjectToIdMapDefaultof capacitycapacity, access-order LRU eviction when full. - Access counts — a separate access-order
LinkedHashMapused only on the write path to decide when a value graduates to a real id. Initial capacityACCESS_COUNT_CACHE_SIZE. - Ids — assigned by the underlying map when a value passes the frequency gate; evicted ids are reused.
Thread safety
recordAccess(Object) is synchronized. Other methods are not; a given map instance
is intended for single-threaded use by one serializer (typical Kryo usage).
- See Also:
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionWrite-side access counts used for frequency gating.Underlying value↔id map (real ids only).getIdByValue(V value) Returns the stable id forvalueif it has already passed the frequency gate and is still in the id map; otherwisenull.getValueById(int id) Looks up a value by id on the read path forCACHED_ENTRYrecords.insertNewEntryOnRead(int id, V value) Registers a mapping on the read path when aNEW_ENTRYcarries a real id.insertNewEntryOnWrite(V value) Called on the write path whengetIdByValue(Object)returnednull.intrecordAccess(V val) Records one write-path access forvaland returns the new count.
-
Constructor Details
-
FrequencyGatedBidirectionalObjectToIdMap
- Parameters:
capacity- maximum number of value↔id mappings retained in the underlying id map (access-order LRU eviction viaBidirectionalObjectToIdMapDefault)
-
-
Method Details
-
recordAccess
Records one write-path access forvaland returns the new count.- Parameters:
val- value being written (may be used as a map key)- Returns:
- access count for
valafter this call (at least 1)
-
getIdByValue
Returns the stable id forvalueif it has already passed the frequency gate and is still in the id map; otherwisenull.- Specified by:
getIdByValuein interfaceBidirectionalObjectToIdMap<V>
-
insertNewEntryOnWrite
Called on the write path whengetIdByValue(Object)returnednull.Increments the access count for
value. If the count is still<= MIN_HITS, returnsKryoCoreConstants.UNREGISTERED_IDwithout storing a mapping. Once the count exceedsMIN_HITS, assigns the next id, stores the mapping, and returns that id.In both cases the caller is expected to write a full payload (the id alone is not enough for the reader until a real id has been seen).
- Specified by:
insertNewEntryOnWritein interfaceBidirectionalObjectToIdMap<V>- Parameters:
value- value being serialized- Returns:
- a newly assigned positive id, or
KryoCoreConstants.UNREGISTERED_IDif the value has not yet graduated
-
insertNewEntryOnRead
Registers a mapping on the read path when aNEW_ENTRYcarries a real id. Not frequency-gated; delegates to the underlying id map.- Specified by:
insertNewEntryOnReadin interfaceBidirectionalObjectToIdMap<V>- Parameters:
id- id from the stream (must not beKryoCoreConstants.UNREGISTERED_IDwhen called fromSerializerBase.read(Kryo, Input, Class))value- deserialized value- Returns:
- previous value for
id, ornullif none
-
getValueById
Looks up a value by id on the read path forCACHED_ENTRYrecords.- Specified by:
getValueByIdin interfaceBidirectionalObjectToIdMap<V>- Returns:
- the value, or
nullif the id is unknown or was LRU-evicted
-
getBidirectionalObjectToIdMap
Underlying value↔id map (real ids only). -
getAccessCountMap
Write-side access counts used for frequency gating. Not used for id assignment after a value has graduated.
-