Expand description
kevy-store — the keyspace.
A single-threaded, multi-type keyspace with lazy expiration. Each Redis data
type is backed by a modern std structure — behaviour-compatible, but not
Redis’s legacy encodings:
| Type | Backing structure |
|---|---|
| String | Vec<u8> |
| Hash / Set | HashMap / HashSet (hashbrown Swiss table) |
| List | VecDeque (ring buffer, O(1) ends) |
| Sorted set | HashMap + BTreeSet<(score, member)> (a B-tree, not a skiplist) |
Wrong-type access returns StoreError::WrongType. The API is &mut self
and lock-free, so a thread-per-core runtime (kevy-rt) can own one shard per
core with no locking. Part of the kevy key–value server.
maxmemory enforcement + 8 eviction policies live in evict; toggle via
Store::set_max_memory. With maxmemory == 0 (the default) the hot-path
cost collapses to a single predicted-not-taken branch, matching the
“unlimited” mode in Redis byte-for-byte.
§Example
use kevy_store::Store;
use std::borrow::Cow;
let mut s = Store::new();
s.set(b"greeting", b"hello".to_vec(), None, kevy_store::SetCondition::Always);
assert_eq!(s.get(b"greeting").unwrap(), Some(Cow::Borrowed(&b"hello"[..])));
s.hset(b"user:1", &[(b"name".as_slice(), b"alice".as_slice())]).unwrap();
assert_eq!(s.hget(b"user:1", b"name").unwrap(), Some(&b"alice"[..]));
// A string command on a hash key is a type error, as in Redis.
assert_eq!(s.get(b"user:1"), Err(kevy_store::StoreError::WrongType));Every public item here is documented, and the lint keeps it that
way: kevy-store is the keyspace, and [workspace.lints.rust] warnings = "deny"
turns a new gap into a compile error rather than a number that
drifts. Closed from 65 sites (store) and 7 (vlog) in v6.
Re-exports§
pub use expire::ExpireStats;
Modules§
- evict
- Maxmemory enforcement and the 8 eviction policies.
- expire
- Active TTL reaper — Redis’s
activeExpireCycle, adapted to the thread-per-core / single-shardStore. - list_
seg - Segmented list — element-granularity COW for giant lists.
- packed_
row PackedRow— a declared table’s row as one allocation.- seg_map
- Bucket-sharded map — element-granularity COW for giant hashes/sets.
- zset_
seg - Segmented sorted set — element-granularity COW for giant zsets.
Structs§
- Autoclaim
Result - Snapshot of
XAUTOCLAIMwork in progress: cursor for the next call, IDs successfully transferred, and IDs skipped because the stream has since deleted them. - Cold
Read - One planned cold-record read in a
Store::peek_hash_rowsbatch. The pinned file keeps the record readable even if a compaction retires the file mid-batch. - ColdRef
- The in-map stub a demoted (cold) value leaves behind: its vlog
record’s address + enough metadata to answer stage-1 questions
(existence, TYPE, weight) with zero IO. Byte math: offset u64 (8) +
file_id/len/weight u32 (12) + type_tag/touched u8 (2) = 22, padded
to 24 by u64 alignment — fits
Value’s 24 B payload (≤32 B assert). - Compression
Stats - The compression accounting over every file the log still holds, dead
records included (the same population as
crate::VlogStats::bytes). - Consumer
Group - One consumer group’s state. Sorted PEL plus a map of known consumers (with cached pel_count for O(1) XINFO answers).
- Consumer
State - Per-consumer cached counters so
XINFO CONSUMERSanswers in O(1). Read throughConsumerGroup::consumer/ConsumerGroup::consumers. - Defrag
Step - What one
Store::defrag_stepdid. - Detached
Entries - A store’s entries, moved out for teardown. It holds memory only — no file — so it can be dropped on any thread, whenever.
- Loaded
Group - One consumer group decoded into primitive tuples — the dump/load wire form shared by snapshot v4, AOF-rewrite filtering, and reshard’s in-memory redistribution.
- PelEntry
- One pending entry: who got it, when, and how many times.
- Pending
Extended - Extended form of
XPENDING key group [IDLE ms] start end count [consumer]: one row per matching PEL entry. - Pending
Extended Row - One row of the extended XPENDING reply.
- Pending
Summary - Summary form of
XPENDING key group(only 3 args): total pending, min/max IDs across the PEL, and per-consumer aggregate counts. - RowChange
- One written row, as
RowChanges::iterlists it: its key, and the watched fields as they were before the write. - RowChanges
- The rows written since the last
crate::Store::take_row_changes, each with its watched fields as they were before the first of those writes. Hand a taken value back to the next take so its buffers are reused. - RowWatch
- Which rows a store watches, and which of their fields: one rule per key prefix.
- Score
- A total-ordered f64 score (Redis scores are never NaN).
total_cmpgives a total order so scores can key an ordered container. - Score
Bound - A score-range endpoint for
ZRANGEBYSCORE/ZCOUNT(inclusive or exclusive). Usevalue = ±INFINITYfor-inf/+inf. - Sealed
Rows - One sealed eviction batch: the segment’s identity and EXACTLY the keys it holds (the commit’s phase-change list). Only the store makes one, so a commit always names a batch that was really sealed.
- Small
Hash Data - Inline packed hash storage. 24 bytes total.
- Small
Hash Iter - Iterator over
SmallHashDatayielding(&[u8] field, &[u8] value). - Small
List Data - Inline packed list storage. 24 bytes total.
- Small
List Iter - Iterator over
SmallListData. - Small
SetData - Inline packed set storage. 24 bytes total — see module docs for layout.
- Small
SetIter - Iterator over
SmallSetDatamembers as&[u8]slices. - SmallZ
SetData - Inline packed sorted-set storage. 24 bytes total.
- SmallZ
SetIter - Iterator over
SmallZSetDatayielding(member, score). - Snapshot
View - A frozen,
Sendview of one store’s live entries at a single instant. - Store
- A single-database keyspace.
- Stream
Data - One stream’s storage: every entry in
entriesplus the per-stream scalar state Redis exposes viaXINFO STREAM, plus the consumer groups map (sprint B). An emptygroupsmap costs ~8 bytes and makes the no-group fast path (sprint A XADD/XREAD) zero-overhead. - Stream
Id - A stream entry’s
<ms>-<seq>identifier. TheOrdderivation comparesmsfirst thenseq, which is exactly the monotonic order the protocol requires; same derivation givesEq,Hash, and theBTreeMapkey bound. - Sync
Cold Read - The default reader: one ordered
preadper record. - Tier
Stats - Tiering gauges — the
INFO # Tieringfeeders. - XClaim
Opts - Knobs for
XCLAIM(Store::xclaim):min-idle-msplus theIDLE/TIME/RETRYCOUNT/FORCE/JUSTIDflag tail. The default isXCLAIM’s: no idle floor, no overrides, noFORCE, a counted redelivery. - ZSet
Data - Sorted set: a member→score map plus an order-statistic B-tree keyed by
(score, member)(kevy_ranktree::RankTree— every node carries its subtree count), so rank queries (ZRANK,ZRANGEby rank,ZCOUNT, score-bound seeks) are O(log N) descents instead of linear walks. - Zadd
Flags - Parsed
ZADDcondition flags:NX/XXas aSetCondition,GT/LTas aScoreCompare, andCH. Only Redis’s legal combinations can be built —ZaddFlags::newrefusesNXwithGT/LT— so the store never has a combination to reject.CHonly changes the reply (changed count instead of added count);ZaddReportcarries both counts either way. - Zadd
Report - Outcome of a flags-aware
ZADD.
Enums§
- AckMode
- Whether entries an
XREADGROUPdelivers wait in the group’s pending list forXACK. - BitOp
- Operator for the BITOP family.
- Claim
Mode - Whether a claim is a redelivery: a plain
XCLAIM/XAUTOCLAIMcounts one more delivery and replies with the entries;JUSTIDmoves ownership only, leaves the delivery count alone and replies with IDs. - Eviction
Policy - Maxmemory eviction policy — the one type for it:
kevy-configparsesmaxmemory-policyinto it and the store enforces it. - GetReply
- L1 return shape for
Store::get_for_reply— lets the reactor’s reply path choose between memcpy (Bytes) and writev zero-copy (ArcBulk) off one keyspace lookup. - GetShared
- Owned GET result for the FFI zero-copy shared lane
(
Store::get_shared_owned). Bulk values ride out as an Arc clone (no byte copy); small values as a plain Vec (one alloc — cheaper than a fresh Arc). The FFI’s shared free reconstructs whichever the tag says. - Group
Create Mode XGROUP CREATEID argument: either an explicit ID or$(= current stream’slast_id, resolved by the caller).- HExpire
Cond - Condition flags for
HEXPIRE(NX/XX/GT/LT; at most one). - Insert
Position - Where
LINSERTplaces the new element relative to its pivot. - Kevy
Error - The error type of the embeddable stack:
kevy_embedded::Storeandkevy_client::Connectionsurfaces returnResult<_, KevyError>. - Keyspace
Event - One captured store-origin event kind;
KeyspaceEvent::nameis the Redis event name the serving layer publishes it under. - ListEnd
- One end of a list:
LEFT(the head, index 0) orRIGHT(the tail). - Missing
Stream - What a stream write does when its key does not exist:
XADDcreates the stream unlessNOMKSTREAM;XGROUP CREATErefuses unlessMKSTREAM. - Read
Group Id - XREADGROUP’s per-stream ID: either
>(= new entries) or an explicit “after this id” for PEL replay. - Rename
Outcome - Outcome of
Store::renameandStore::rename_nx— three-way result so the dispatch layer can pick the right RESP frame (+OK/-ERR no such key/:0forRENAMENX-with-existing-dst). - Score
Compare - Which score change a conditional
ZADDaccepts for an existing member:GT/LT, or any. New members are not judged by it. - SegRows
Error - Why enabling, sealing into, or stitching from row segments failed.
- SetCondition
- When a write may happen, judged by whether its target already exists:
SET’s andZADD’sNX/XX. One value instead of two flags, so asking for both is not expressible. - Store
Error - Operation errors surfaced to the command layer.
- Stream
IdError - Errors
parse_*_idmay emit. Distinct fromStoreError::NotIntegerso callers can map to the more specific Redis wire shape (ERR Invalid stream ID specified as stream command argument). - Trim
Mode - How a trim goes about it:
XTRIM’s=and~. - TrimTo
- What a trim keeps: the last
nentries, or the entries from an ID on. - Value
- A stored value. One variant per Redis type.
- XAdd
IdSpec - XADD’s ID argument: either an explicit
<ms>-<seq>(both parts may be*to auto-fillseqonly) or fully auto-generate via*. - ZAggregate
AGGREGATEmode for inter/union (Redis 6.2; defaultSum).
Constants§
- APPROX_
TRIM_ LIMIT - How many entries an approximate trim removes at most when the command
names no
LIMIT: 100 nodes’ worth. - BULK_
THRESHOLD - Threshold (bytes) above which a SET stores its value as
Value::ArcBulk(writev-eligible on GET) instead ofValue::Str(inlineSmallBytes). 64 B ≈ one cache line — below that the inline-SmallBytes storage wins on L1 locality; above it the writev-borrow win dominates. - COLD_
TAG_ HASH - Hash tag — see
COLD_TAG_STRING. - COLD_
TAG_ STRING - Type tag a
ColdRefcarries soTYPE/ SCAN’sTYPEfilter / the WRONGTYPE precheck answer with zero IO. - ENTRY_
OVERHEAD - A keyspace slot’s amortised cost: the inline 24-byte
SmallByteskey cell, theEntryand a control byte, over the table’s load. The tiered store charges each cold stub this instub_bytes, the estimate of what its cold keys cost in memory. - HEAP_
HEAVY_ BYTES - Heap-size threshold above which an overwritten
Valueis sent to the runtime’s bio thread for off-reactor drop instead of being freed inline (lazy-drop).
Traits§
- Cold
Batch Reader - The read-issuance half of a cold batch: fetch every record
image, in
readsorder.SyncColdReadis the ordered positional-read loop (poller reactors + embedded); the server’s io_uring backend submits the batch to a secondary ring instead.
Functions§
- glob_
match - Redis-style glob match (
*,?,[...]classes with ranges/^,\escape). - hash_
field_ weight - What a new hash field adds to its hash’s weight besides the table: the
allocator’s footprint of the field name’s heap and of the value’s heap
(
value_heapbytes), each 0 when it is short enough to sit inline in the slot. The slot itself is part of the table, which is charged as the table grows rather than per field. - list_
item_ weight - Per-item delta a new list element charges (Vec header slot + heap cap).
- now_
unix_ ms - Wall-clock millis. Shared with dispatchers so every XADD on a shard uses
the same clock source. On native targets reads
SystemTime::now()(falls back to 0 on a pre-UNIX-EPOCH clock — impossible on supported platforms); onwasm32-unknown-unknown, whereSystemTime::now()traps, reads the host-fed wall clock (seecrate::set_wall_clock_ms, wasm-only). - parse_
explicit_ id - Parse a fully-explicit ID for XREAD’s per-stream “last-seen” arg
(
0,0-0,5-2).$is handled by the caller (it means “the stream’s currentlast_id”, which only Store can resolve). - parse_
range_ end - Parse an XRANGE
endID. Accepts+(=StreamId::MAX), barems(seq=u64::MAX so the entire ms is included), and fullms-seq. - parse_
range_ start - Parse an XRANGE
startID. Accepts-(=StreamId::MIN), barems(seq=0), and fullms-seq. - parse_
xadd_ id - Parse an XADD ID argument (
*,ms,ms-*,ms-seq). - set_
member_ weight - Per-member delta a new set member charges. Mirrors
hash_field_weightfor the set variant (no separate value, single bucket slot). - zdiff
ZDIFFSTOREcombination: members of the first input absent from every other input; scores from the first input (no weights / aggregate — Redis 6.2 defines none for ZDIFF).- zinter
ZINTERSTOREcombination: members present in EVERY input.- zintercard
ZINTERCARD(with optionalLIMIT, 0 = unlimited): cardinality of the intersection, short-circuiting at the limit.- zset_
member_ weight - Per-member delta a new zset member charges: hash slot for
by_member+ rank-tree slot forby_score+ the member’s heap bytes — twice, because a heap-spilling member (>22 B) is stored in both structures (inline members cost 0 here, matchingValue::weight’s ZSet arm). - zunion
ZUNIONSTOREcombination: every member of any input, scores aggregated across the inputs it appears in (weighted).
Type Aliases§
- BioDrop
Sender - Sender half of the runtime’s bio-drop channel. Wired from
kevy-rt’sbio.rsviacrate::Store::set_bio_drop_sender; the concrete payload isVec<Value>— a batch of values produced by one shard since its last flush. The bio thread (kevy-rt::bio::spawn) iterates the batch and drops each item. One mpsc message per shard-flush amortises the channel cost (atomic + cross-thread cacheline traffic) across however many values landed in the batch. - Defrag
Hint - Whether the allocation at
ptr, made with(size, align), would move to a denser span if copied. The store only asks about allocations its values own, with the layout they were made with; a hint must still answer safely for any address (kevy_alloc::global::should_movedoes). - Entry
Batch - Cloned-out view of stream entries, the cross-module wire form. Keeps
the same shape Redis sends and lets the callers stay decoupled from
the
SmallBytesinterning the store uses internally. - Field
Value Pairs (field, value)pairs collected off any hash encoding. Owned(field, value)pairs, as the hash readers hand them back.- Group
Batch - What a group read hands back: each entry with its fields, or with none when a read of a consumer’s history names an entry the stream no longer holds.
- HExpire
Code - Per-field reply codes for
HEXPIRE-family calls (Redis 7.4):-2key or field missing,0condition (NX/XX/GT/LT) not met,1deadline set,2field deleted (deadline already due). - Hash
Data - Backing structure for a Hash value —
KevyMapkeyed bySmallBytes(22 B inline / heap-else). Field names ≤22B (the vast majority —name,email, etc.) live entirely inside the bucket, saving the 24 B Vec metadata + heap allocation per field on a 22-byte budget. - Kevy
Result - Unified result alias over
KevyError. - List
Data - Backing structure for a List value (a ring-buffer deque — O(1) both ends).
- Loaded
PelEntry - One PEL row in primitive form:
(ms, seq, consumer, delivery_time_ms, delivery_count). The persist crate serializes these verbatim. - Loaded
Stream Entry - Snapshot-loader payload: one stream entry decoded into primitive
tuples
(ms, seq, [(field, value), ...]). The persist crate emits these andStore::load_streamconsumes them. - PeekRow
- One peeked row: the per-field values of a live hash
(
Ok(Some(..)), oneOptionper requested field), a missing key (Ok(None)), or a non-hash (Err(WrongType)). - SetData
- Backing structure for a Set value —
KevySetofSmallBytes.
Unions§
- Small
Bytes - A 24-byte owned byte string with inline small-string optimization.