Introduce volatile set

[ranshid]

Note that this continue the work of #3

Overview:

This PR introduces a complete redesign of the 'vset' (stands for volatile set) data structure,
creating an adaptive container for expiring entries. The new design is
memory-efficient, scalable, and dynamically promotes/demotes its internal
representation depending on runtime behavior and volume.

The core concept uses a single tagged pointer (expiry_buckets) that encodes
one of several internal structures:
- NONE (-1): Empty set
- SINGLE (0x1): One entry
- VECTOR (0x2): Sorted vector of entry pointers
- HT (0x4): Hash table for larger buckets with many entries
- RAX (0x6): Radix tree (keyed by aligned expiry timestamps)

This allows the set to grow and shrink seamlessly while optimizing for both
space and performance.

Motivation:

The previous design lacked flexibility in high-churn environments or
workloads with skewed expiry distributions. This redesign enables dynamic
layout adjustment based on the time distribution and volume of the inserted
entries, while maintaining fast expiry checks and minimal memory overhead.

Key Concepts:

• All pointers stored in the structure must be odd-aligned to preserve
  3 bits for tagging. This is safe with SDS strings (which set the LSB).

• Buckets evolve automatically:

  • Start as NONE.
  • On first insert → become SINGLE.
  • If another entry with similar expiry → promote to VECTOR.
  • If VECTOR exceeds 127 entries → convert to RAX.
  • If a RAX bucket's vector fills and cannot split → promote to HT.

• Each vector bucket is kept sorted by entry->getExpiry().

• Binary search is used for efficient insertion and splitting.

Coarse Buckets Expiration System for Hash Fields

This PR introduces coarse-grained expiration buckets to support per-field
expirations in hash types — a feature known as volatile fields.

It enables scalable expiration tracking by grouping fields into time-aligned
buckets instead of individually tracking exact timestamps.

Motivation

Valkey traditionally supports key-level expiration. However, in many applications,
there's a strong need to expire individual fields within a hash (e.g., session keys,
token caches, etc.).

Tracking these at fine granularity is expensive and potentially unscalable, so
this implementation introduces bucketed expirations to batch expirations together.

Bucket Granularity and Timestamp Handling

• Each expiration bucket represents a time slice of fixed width (e.g., 8192 ms).
• Expiring fields are mapped to the end of a time slice (not the floor).
• This design facilitates:
  • Efficient splitting of large buckets when needed
  • Downgrading buckets when fields permit tighter packing
  • Coalescing during lazy cleanup or memory pressure

Example Calculation

Suppose a field has an expiration time of 1690000123456 ms and the max bucket
interval is 8192 ms:

BUCKET_INTERVAL_MAX = 8192;
expiry = 1690000123456;

bucket_ts = (expiry & ~(BUCKET_INTERVAL_MAX - 1LL)) + BUCKET_INTERVAL_MAX;
          = (1690000123456 & ~8191) + 8192
          = 1690000122880 + 8192
          = 1690000131072

The field is stored in a bucket that ends at 1690000131072 ms.

Bucket Alignment Diagram

Time (ms) →
|----------------|----------------|----------------|
 128ms buckets → 1690000122880    1690000131072
                    ^               ^
                    |               |
              expiry floor     assigned bucket end

Bucket Placement Logic

• If a suitable bucket already exists (i.e., its end_ts > expiry), the field is added.
• If no bucket covers the expiry, a new bucket is created at the computed end_ts.

Bucket Downgrade Conditions

Buckets are downgraded to smaller intervals when overpopulated (>127 fields).
This happens when all fields fit into a tighter bucket.

Downgrade rule:

(max_expiry & ~(BUCKET_INTERVAL_MIN - 1LL)) + BUCKET_INTERVAL_MIN < current_bucket_ts

If the above holds, all fields can be moved to a tighter bucket interval.

Downgrade Bucket — Diagram

Before downgrade:

  Current Bucket (8192 ms)
  |----------------------------------------|
  | Field A | Field B | Field C | Field D  |
  | exp=+30 | +200    | +500    | +1500    |
  |----------------------------------------|
                    ↑
       All expiries fall before tighter boundary

After downgrade to 1024 ms:

  New Bucket (1024 ms)
  |------------------|
  | A | B | C | D     |
  |------------------|

Bucket Split Strategy

If downgrade is not possible, the bucket is split:

• Fields are sorted by expiration time.
• A subset that fits in an earlier bucket is moved out.
• Remaining fields stay in the original bucket.

Split Bucket — Diagram

Before split:

  Large Bucket (8192 ms)
  |--------------------------------------------------|
  | A | B | C | D | E | F | G | H | I | J | ... | Z  |
  |---------------- Sorted by expiry ---------------|
            ↑
     Fields A–L can be moved to an earlier bucket

After split:

  Bucket 1 (end=1690000129024)     Bucket 2 (end=1690000131072)
  |------------------------|       |------------------------|
  | A | B | C | ... | L     |       | M | N | O | ... | Z    |
  |------------------------|       |------------------------|

Summary of Bucket Behavior

Scenario	Action Taken
No bucket covers expiry	New bucket is created
Existing bucket fits	Field is added
Bucket overflows (>127 fields)	Downgrade or split attempted

API Changes:

Create/Free:
void vsetInit(vset *set);
void vsetClear(vset *set);

Mutation:
bool vsetAddEntry(vset *set, vsetGetExpiryFunc getExpiry, void *entry);
bool vsetRemoveEntry(vset *set, vsetGetExpiryFunc getExpiry, void *entry);
bool vsetUpdateEntry(vset *set, vsetGetExpiryFunc getExpiry, void *old_entry,
void *new_entry, long long old_expiry,
long long new_expiry);

Expiry Retrieval:
long long vsetEstimatedEarliestExpiry(vset *set, vsetGetExpiryFunc getExpiry);
size_t vsetPopExpired(vset *set, vsetGetExpiryFunc getExpiry, vsetExpiryFunc expiryFunc, mstime_t now, size_t max_count, void *ctx);

Utilities:
bool vsetIsEmpty(vset *set);
size_t vsetMemUsage(vset *set);

Iteration:
void vsetStart(vset *set, vsetIterator *it);
bool vsetNext(vsetIterator *it, void **entryptr);
void vsetStop(vsetIterator *it);

Entry Requirements:

All entries must conform to the following interface via volatileEntryType:

   sds entryGetKey(const void  entry);         // for deduplication
   long long getExpiry(const void  entry);     // used for bucketing
   int expire(void  db, void  o, void  entry); // used for expiration callbacks

Diagrams:

1. Tagged Pointer Representation

   Lower 3 bits of expiry_buckets encode bucket type:

   +------------------------------+
   | pointer | TAG (3b) |
   +------------------------------+
   ↑
   masked via VSET_PTR_MASK

   TAG values:
   0x1 → SINGLE
   0x2 → VECTOR
   0x4 → HT
   0x6 → RAX

2. Evolution of the Bucket

Volatile set top-level structure:

+--------+     +--------+     +--------+     +--------+
| NONE   | --> | SINGLE | --> | VECTOR | --> |   RAX  |
+--------+     +--------+     +--------+     +--------+

If the top-level element is a RAX, it has child buckets of type:

+--------+     +--------+     +-----------+
| SINGLE | --> | VECTOR | --> | HASHTABLE |
+--------+     +--------+     +-----------+

Vectors can split into multiple vectors and shrink into SINGLE buckets. A RAX with only one element is collapsed by replacing the RAX with its single element on the top level (except for HASHTABLE buckets which are not allowed on the top level).

3. RAX Structure with Expiry-Aligned Keys

   Buckets in RAX are indexed by aligned expiry timestamps:

   +------------------------------+
   | RAX key (bucket_ts) → Bucket|
   +------------------------------+
   | 0x00000020 → VECTOR |
   | 0x00000040 → VECTOR |
   | 0x00000060 → HT |
   +------------------------------+

4. Bucket Splitting (Inside RAX)

   If a vector bucket in a RAX fills:

   • Binary search for best split point.
   • Use getExpiry(entry) + get_bucket_ts() to find transition.
   • Create 2 new buckets and update RAX.

   Original:
   [entry1, entry2, ..., entryN] ← bucket_ts = 64ms

   After split:
   [entry1, ..., entryK] → bucket_ts = 32ms
   [entryK+1, ..., entryN] → bucket_ts = 64ms

   If all entries share same bucket_ts → promote to HT.

5. Shrinking Behavior

   On deletion:

   • HT may shrink to VECTOR.
   • VECTOR with 1 item → becomes SINGLE.
   • If RAX has only one key left, it’s promoted up.

Summary:

This redesign provides:
✓ Fine-grained memory control
✓ High scalability for bursty TTL data
✓ Fast expiry checks via windowed organization
✓ Minimal overhead for sparse sets
✓ Flexible binary-search-based sorting and bucketing

It also lays the groundwork for future enhancements, including metrics,
prioritized expiry policies, or segmented cleaning.

[JimB123]

This API is much cleaner now. I have a slight suggestion, and feel free to ignore if you want...

Using a typed pointer (not void) provides some additional safety by the compiler. I'm also a little hesitant to create the typedef including the pointer. We do this in sds (char*), and it creates some weirdness in usage - where the caller needs to understand that it's really a pointer anyway.

I suggest:

In the .h file:

typedef struct vset vset;  // This is a typed (not void) pointer (provides some type checking)

bool vsetAddEntry(vset **set, vsetGetExpiryFunc getExpiry, void *entry);

In the .c file:

// You can flesh out the details of your vset struct in the .c file
// (or you can cast to something else, if needed)
struct vset {
    ...
}

In calling code:

vset *mySet;  // Now this looks "normal" to a client

vsetInit(&mySet); // and this will be a consistent pattern

[ranshid]

This was manually cherry-picked into valkey-io#2089