Skip to main content

Crate kevy_store

Crate kevy_store 

Source
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:

TypeBacking structure
StringVec<u8>
Hash / SetHashMap / HashSet (hashbrown Swiss table)
ListVecDeque (ring buffer, O(1) ends)
Sorted setHashMap + 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-shard Store.
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§

AutoclaimResult
Snapshot of XAUTOCLAIM work in progress: cursor for the next call, IDs successfully transferred, and IDs skipped because the stream has since deleted them.
ColdRead
One planned cold-record read in a Store::peek_hash_rows batch. 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).
CompressionStats
The compression accounting over every file the log still holds, dead records included (the same population as crate::VlogStats::bytes).
ConsumerGroup
One consumer group’s state. Sorted PEL plus a map of known consumers (with cached pel_count for O(1) XINFO answers).
ConsumerState
Per-consumer cached counters so XINFO CONSUMERS answers in O(1). Read through ConsumerGroup::consumer / ConsumerGroup::consumers.
DefragStep
What one Store::defrag_step did.
DetachedEntries
A store’s entries, moved out for teardown. It holds memory only — no file — so it can be dropped on any thread, whenever.
LoadedGroup
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.
PendingExtended
Extended form of XPENDING key group [IDLE ms] start end count [consumer]: one row per matching PEL entry.
PendingExtendedRow
One row of the extended XPENDING reply.
PendingSummary
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::iter lists 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_cmp gives a total order so scores can key an ordered container.
ScoreBound
A score-range endpoint for ZRANGEBYSCORE/ZCOUNT (inclusive or exclusive). Use value = ±INFINITY for -inf/+inf.
SealedRows
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.
SmallHashData
Inline packed hash storage. 24 bytes total.
SmallHashIter
Iterator over SmallHashData yielding (&[u8] field, &[u8] value).
SmallListData
Inline packed list storage. 24 bytes total.
SmallListIter
Iterator over SmallListData.
SmallSetData
Inline packed set storage. 24 bytes total — see module docs for layout.
SmallSetIter
Iterator over SmallSetData members as &[u8] slices.
SmallZSetData
Inline packed sorted-set storage. 24 bytes total.
SmallZSetIter
Iterator over SmallZSetData yielding (member, score).
SnapshotView
A frozen, Send view of one store’s live entries at a single instant.
Store
A single-database keyspace.
StreamData
One stream’s storage: every entry in entries plus the per-stream scalar state Redis exposes via XINFO STREAM, plus the consumer groups map (sprint B). An empty groups map costs ~8 bytes and makes the no-group fast path (sprint A XADD/XREAD) zero-overhead.
StreamId
A stream entry’s <ms>-<seq> identifier. The Ord derivation compares ms first then seq, which is exactly the monotonic order the protocol requires; same derivation gives Eq, Hash, and the BTreeMap key bound.
SyncColdRead
The default reader: one ordered pread per record.
TierStats
Tiering gauges — the INFO # Tiering feeders.
XClaimOpts
Knobs for XCLAIM (Store::xclaim): min-idle-ms plus the IDLE/TIME/RETRYCOUNT/FORCE/JUSTID flag tail. The default is XCLAIM’s: no idle floor, no overrides, no FORCE, a counted redelivery.
ZSetData
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, ZRANGE by rank, ZCOUNT, score-bound seeks) are O(log N) descents instead of linear walks.
ZaddFlags
Parsed ZADD condition flags: NX / XX as a SetCondition, GT / LT as a ScoreCompare, and CH. Only Redis’s legal combinations can be built — ZaddFlags::new refuses NX with GT / LT — so the store never has a combination to reject. CH only changes the reply (changed count instead of added count); ZaddReport carries both counts either way.
ZaddReport
Outcome of a flags-aware ZADD.

Enums§

AckMode
Whether entries an XREADGROUP delivers wait in the group’s pending list for XACK.
BitOp
Operator for the BITOP family.
ClaimMode
Whether a claim is a redelivery: a plain XCLAIM / XAUTOCLAIM counts one more delivery and replies with the entries; JUSTID moves ownership only, leaves the delivery count alone and replies with IDs.
EvictionPolicy
Maxmemory eviction policy — the one type for it: kevy-config parses maxmemory-policy into 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.
GroupCreateMode
XGROUP CREATE ID argument: either an explicit ID or $ (= current stream’s last_id, resolved by the caller).
HExpireCond
Condition flags for HEXPIRE (NX/XX/GT/LT; at most one).
InsertPosition
Where LINSERT places the new element relative to its pivot.
KevyError
The error type of the embeddable stack: kevy_embedded::Store and kevy_client::Connection surfaces return Result<_, KevyError>.
KeyspaceEvent
One captured store-origin event kind; KeyspaceEvent::name is the Redis event name the serving layer publishes it under.
ListEnd
One end of a list: LEFT (the head, index 0) or RIGHT (the tail).
MissingStream
What a stream write does when its key does not exist: XADD creates the stream unless NOMKSTREAM; XGROUP CREATE refuses unless MKSTREAM.
ReadGroupId
XREADGROUP’s per-stream ID: either > (= new entries) or an explicit “after this id” for PEL replay.
RenameOutcome
Outcome of Store::rename and Store::rename_nx — three-way result so the dispatch layer can pick the right RESP frame (+OK / -ERR no such key / :0 for RENAMENX-with-existing-dst).
ScoreCompare
Which score change a conditional ZADD accepts for an existing member: GT / LT, or any. New members are not judged by it.
SegRowsError
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 and ZADD’s NX / XX. One value instead of two flags, so asking for both is not expressible.
StoreError
Operation errors surfaced to the command layer.
StreamIdError
Errors parse_*_id may emit. Distinct from StoreError::NotInteger so callers can map to the more specific Redis wire shape (ERR Invalid stream ID specified as stream command argument).
TrimMode
How a trim goes about it: XTRIM’s = and ~.
TrimTo
What a trim keeps: the last n entries, or the entries from an ID on.
Value
A stored value. One variant per Redis type.
XAddIdSpec
XADD’s ID argument: either an explicit <ms>-<seq> (both parts may be * to auto-fill seq only) or fully auto-generate via *.
ZAggregate
AGGREGATE mode for inter/union (Redis 6.2; default Sum).

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 of Value::Str (inline SmallBytes). 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 ColdRef carries so TYPE / SCAN’s TYPE filter / the WRONGTYPE precheck answer with zero IO.
ENTRY_OVERHEAD
A keyspace slot’s amortised cost: the inline 24-byte SmallBytes key cell, the Entry and a control byte, over the table’s load. The tiered store charges each cold stub this in stub_bytes, the estimate of what its cold keys cost in memory.
HEAP_HEAVY_BYTES
Heap-size threshold above which an overwritten Value is sent to the runtime’s bio thread for off-reactor drop instead of being freed inline (lazy-drop).

Traits§

ColdBatchReader
The read-issuance half of a cold batch: fetch every record image, in reads order. SyncColdRead is 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_heap bytes), 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); on wasm32-unknown-unknown, where SystemTime::now() traps, reads the host-fed wall clock (see crate::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 current last_id”, which only Store can resolve).
parse_range_end
Parse an XRANGE end ID. Accepts + (= StreamId::MAX), bare ms (seq=u64::MAX so the entire ms is included), and full ms-seq.
parse_range_start
Parse an XRANGE start ID. Accepts - (= StreamId::MIN), bare ms (seq=0), and full ms-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_weight for the set variant (no separate value, single bucket slot).
zdiff
ZDIFFSTORE combination: 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
ZINTERSTORE combination: members present in EVERY input.
zintercard
ZINTERCARD (with optional LIMIT, 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 for by_score + the member’s heap bytes — twice, because a heap-spilling member (>22 B) is stored in both structures (inline members cost 0 here, matching Value::weight’s ZSet arm).
zunion
ZUNIONSTORE combination: every member of any input, scores aggregated across the inputs it appears in (weighted).

Type Aliases§

BioDropSender
Sender half of the runtime’s bio-drop channel. Wired from kevy-rt’s bio.rs via crate::Store::set_bio_drop_sender; the concrete payload is Vec<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.
DefragHint
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_move does).
EntryBatch
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 SmallBytes interning the store uses internally.
FieldValuePairs
(field, value) pairs collected off any hash encoding. Owned (field, value) pairs, as the hash readers hand them back.
GroupBatch
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.
HExpireCode
Per-field reply codes for HEXPIRE-family calls (Redis 7.4): -2 key or field missing, 0 condition (NX/XX/GT/LT) not met, 1 deadline set, 2 field deleted (deadline already due).
HashData
Backing structure for a Hash value — KevyMap keyed by SmallBytes (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.
KevyResult
Unified result alias over KevyError.
ListData
Backing structure for a List value (a ring-buffer deque — O(1) both ends).
LoadedPelEntry
One PEL row in primitive form: (ms, seq, consumer, delivery_time_ms, delivery_count). The persist crate serializes these verbatim.
LoadedStreamEntry
Snapshot-loader payload: one stream entry decoded into primitive tuples (ms, seq, [(field, value), ...]). The persist crate emits these and Store::load_stream consumes them.
PeekRow
One peeked row: the per-field values of a live hash (Ok(Some(..)), one Option per requested field), a missing key (Ok(None)), or a non-hash (Err(WrongType)).
SetData
Backing structure for a Set value — KevySet of SmallBytes.

Unions§

SmallBytes
A 24-byte owned byte string with inline small-string optimization.