Any state variable that wants to support TTL must implement this trait, which they can do by extending OneToOneTTLState or OneToManyTTLState.

The only required methods here are ones relating to evicting expired and all state, via clearExpiredStateForAllKeys and clearAllStateForElementKey, respectively. How classes do this is implementation detail, but the general pattern is to use secondary indexes to make sure cleanup scans theta(records to evict), not theta(all records).

There are two broad patterns of implementing stateful variables, and thus there are two broad patterns for implementing TTL. The first is when there is a one-to-one mapping between an element key [1] and a value; the primary and secondary index management for this case is implemented by OneToOneTTLState. When a single element key can have multiple values, all of which can expire at their own, unique times, then OneToManyTTLState should be used.

In either case, implementations need to use some sort of secondary index that orders element keys by expiration time. This base functionality is provided by methods in this trait that read/write/delete to the so-called "TTL index". It is a secondary index with the layout of (expirationMs, elementKey) -> EMPTY_ROW. The expirationMs is big-endian encoded to allow for efficient range scans to find all expired keys.

TTLState (or any abstract sub-classes) should never deal with encoding or decoding UnsafeRows to and from their user-facing types. The stateful variable themselves should be doing this; all other TTLState sub-classes should be concerned only with writing, reading, and deleting UnsafeRows and their associated expirations from the primary and secondary indexes. [2]

[1]. You might ask, why call it "element key" instead of "grouping key"? This is because a single grouping key might have multiple elements, as in the case of a map, which has composite keys of the form (groupingKey, mapKey). In the case of ValueState, though, the element key is the grouping key. To generalize to both cases, this class should always use the term elementKey.)

[2]. You might also ask, why design it this way? We want the TTLState abstract sub-classes to write to both the primary and secondary indexes, since they both need to stay in sync; co-locating the logic is cleanest.