Overview

Relevant source files

• redis.conf
• src/aof.c
• src/config.c
• src/db.c
• src/debug.c
• src/module.c
• src/networking.c
• src/object.c
• src/rdb.c
• src/redismodule.h
• src/replication.c
• src/server.c
• src/server.h
• tests/unit/introspection.tcl

What is Redis/Valkey?

Redis (also known as Valkey in the community fork) is an in-memory data structure store that functions as a database, cache, message broker, and streaming engine. The entire dataset resides in RAM, enabling sub-millisecond latency for most operations. This architecture makes Redis suitable for:

• Caching: Fast data retrieval with LRU/LFU/LRM eviction policies
• Session storage: Shared state across distributed applications
• Real-time analytics: Counters, leaderboards, time-series data
• Message queuing: Pub/Sub channels and Stream-based consumer groups
• Primary database: Durable storage via RDB snapshots and AOF logs

The codebase supports four deployment modes:

• Standalone: Single redisServer instance
• Master-Replica: Asynchronous replication with PSYNC protocol
• Sentinel: Automatic failover via sentinel.c state machine
• Cluster: Hash slot partitioning (16,384 slots) across nodes

Sources: src/server.h1-100 src/server.c79-83 redis.conf1-100

Architecture Philosophy

Redis is built on three core principles:

1. Single-threaded command execution: All commands execute sequentially in call() within the main thread, eliminating lock contention and ensuring atomic operations without transactions for most use cases.

2. Event-driven I/O: The aeEventLoop in src/ae.h multiplexes all socket operations, allowing a single thread to handle thousands of concurrent connections.

3. In-memory first: All active data resides in server.db[] hash tables. Persistence (rdb.c, aof.c) and replication (replication.c) are secondary concerns that don't block command processing.

Sources: src/server.c79-83 src/ae.c src/networking.c1-300

---

Core Architecture

System Entry Points and Execution Flow

Diagram: Server Initialization and Event Loop

The main() function at src/server.c6500-6800 initializes the global struct redisServer server and enters the event loop. Key initialization steps:

1. initServer() at src/server.c2800-3200:

   • Allocates server.db[] array (default 16 databases)
   • Creates server.clients list
   • Initializes server.commands dict with command table
   • Calls aeCreateEventLoop() to set up epoll/kqueue/select
   • Binds TCP/Unix sockets via listenToPort()

2. aeMain() at src/ae.c:

   • Infinite loop: while (!server.stop)
   • Calls beforeSleep() to flush client output buffers
   • Processes file events (socket reads/writes)
   • Processes time events (serverCron fires every 100ms)

3. serverCron() at src/server.c1300-1800:

   • Checks client timeouts
   • Triggers database rehashing and active expiration
   • Handles replication ping/ack
   • Initiates background AOF/RDB saves

Sources: src/server.c2800-3200 src/server.c6500-6800 src/ae.c

---

Request Processing Pipeline

Diagram: Command Execution Path with Code Entities

Commands flow through these functions:

1. readQueryFromClient() at src/networking.c2000-2200: Reads bytes from c->conn into c->querybuf (an sds string).

2. processInputBuffer() at src/networking.c2100-2300: Parses RESP protocol, populates c->argc and c->argv[] array.

3. processCommand() at src/server.c3800-4200:

   • Calls lookupCommand() to search server.commands dict
   • Validates ACL permissions via ACLCheckAllPerm()
   • In cluster mode, calls getNodeByQuery() to check slot ownership
   • Checks OOM conditions if CMD_DENYOOM flag set

4. call() at src/server.c3500-3700:

   • Invokes cmd->proc function pointer (e.g., setCommand, getCommand)
   • Calls propagateNow() to append to AOF and replicate to slaves
   • Fires keyspace notifications

5. Command implementation (e.g., setCommand at src/t_string.c):

   • Calls lookupKeyWrite() or lookupKeyRead() to access db->keys kvstore
   • Modifies data structures
   • Calls addReply() to build response

6. addReply*() functions at src/networking.c400-800: Write RESP-encoded data to c->buf (static buffer) or c->reply (linked list of clientReplyBlock).

Sources: src/networking.c2000-2300 src/server.c3500-4200 src/db.c274-333

---

Global Server State

The entire server state resides in a single global variable:

Diagram: struct redisServer Key Fields

The redisServer struct at src/server.h1800-2500 contains:

Field	Type	Purpose
db[]	redisDb array	16 numbered databases (default), each with independent keyspace
commands	dict*	Command table mapping name (sds) to redisCommand*
clients	list*	All connected client* structures
el	aeEventLoop*	Event loop for socket multiplexing
aof_state	int	AOF enabled status (AOF_OFF/ON/WAIT_REWRITE)
masterhost	sds	Master hostname if this is a replica (NULL otherwise)
cluster_enabled	int	Whether cluster mode is active
maxmemory	long long	Memory limit for eviction
maxmemory_policy	int	Eviction algorithm (LRU/LFU/LRM/RANDOM/TTL)

Each redisDb struct at src/server.h700-750 contains:

Field	Type	Purpose
keys	kvstore*	Main keyspace (slot-sharded hash tables)
expires	kvstore*	Expiration times for keys with TTL
id	int	Database number (0-15)

Sources: src/server.h1800-2500 src/server.h700-750 src/server.c84

---

Data Storage Architecture

Storage Hierarchy

Diagram: From redisDb to Data Type Encodings

Key-Value Object Structure

The kvobj structure at src/server.h70-93 unifies keys and values:

For keys stored in db->keys:

• iskvobj=1: The key (sds string) is embedded after the struct
• metabits: Bitmask indicating presence of expiry timestamp and other metadata
• ptr: Points to the value's data structure (quicklist, dict, skiplist, etc)

The kvobjCreate() function at src/object.c62-105 allocates a kvobj with embedded key and metadata space.

Sources: src/server.h70-93 src/object.c62-105 src/db.c274-333

---

Hash Table Implementation

The dict structure at src/dict.h implements generic hash tables:

Key operations:

• dictFind() at src/dict.c400-450: Hash key, probe chain, return entry
• dictAdd() at src/dict.c500-550: Insert new key-value pair
• dictRehash() at src/dict.c600-700: Incremental rehashing (moves N buckets)

The kvstore wrapper at src/kvstore.c manages multiple dicts for slot-based sharding in cluster mode. In standalone mode, it contains a single dict. In cluster mode, it contains up to 16,384 dicts (one per hash slot).

Sources: src/dict.h src/dict.c400-700 src/kvstore.c

---

Data Types and Encodings

Type	Constant	Small Encoding	Large Encoding	Implementation File
String	OBJ_STRING	OBJ_ENCODING_EMBSTR (≤44 bytes)	OBJ_ENCODING_RAW (sds)	src/t_string.c
List	OBJ_LIST	—	OBJ_ENCODING_QUICKLIST	src/t_list.c
Set	OBJ_SET	OBJ_ENCODING_INTSET	OBJ_ENCODING_HT (dict)	src/t_set.c
Sorted Set	OBJ_ZSET	OBJ_ENCODING_LISTPACK	OBJ_ENCODING_SKIPLIST	src/t_zset.c
Hash	OBJ_HASH	OBJ_ENCODING_LISTPACK	OBJ_ENCODING_HT (dict)	src/t_hash.c
Stream	OBJ_STREAM	—	OBJ_ENCODING_STREAM (rax)	src/t_stream.c

Encoding transitions are triggered by configuration thresholds:

• hash-max-listpack-entries / hash-max-listpack-value
• set-max-intset-entries
• zset-max-listpack-entries / zset-max-listpack-value

Each data type's commands are implemented in t_<type>.c files and registered in the command table at src/commands.c

Sources: src/server.h600-800 src/t_string.c src/t_list.c src/t_set.c src/t_zset.c src/t_hash.c src/t_stream.c src/commands.c

---

Persistence Mechanisms

Redis offers two persistence strategies that can operate independently or together:

RDB Snapshots

Diagram: RDB Save Process

The RDB format at src/rdb.c1-300 is a binary snapshot of the entire dataset:

• Triggering: SAVE (blocking), BGSAVE (background), or save config intervals
• Process: fork() creates child, iterates all databases, serializes each key-value pair
• Format: Type byte + encoded length + encoded data
• Loading: rdbLoad() at src/rdb.c2800-3200 reads dump.rdb on startup

Advantages: Compact, fast loading
Disadvantages: Data loss window between snapshots

Sources: src/rdb.c1-300 src/rdb.c2800-3200 src/rdb.h

AOF (Append-Only File)

Diagram: Multi-Part AOF System

The AOF system at src/aof.c logs write commands:

• Fsync policy: appendfsync always|everysec|no in redis.conf
• Multi-part: Base file (RDB format) + incremental files (RESP format)
• Manifest: aofManifest struct tracks all files at src/aof.c143-172
• Rewriting: rewriteAppendOnlyFile() at src/aof.c2000-2500 forks and generates minimal command sequence

Loading process:

1. Read appendonly.aof.manifest to get file list
2. Load base file (RDB format)
3. Replay incremental files in order

Sources: src/aof.c1-300 src/aof.c1100-1300 src/aof.c2000-2500

---

High Availability and Scaling

Replication

Diagram: PSYNC Protocol State Machine

Replication at src/replication.c implements master-replica synchronization:

Master side:

• replicationFeedSlaves() at src/replication.c400-600: Sends commands to all replicas
• server.repl_backlog: Circular buffer (default 1MB) for partial resync
• server.slaves: List of client* with CLIENT_SLAVE flag

Replica side:

• State machine in replicationCron() at src/replication.c3000-3300
• PSYNC <runid> <offset>: Request partial sync if possible
• readSyncBulkPayload(): Receive RDB during full sync

PSYNC2 features:

• Partial resync after master restart (uses server.replid2)
• RDB channel mode: Parallel RDB transfer + command streaming

Sources: src/replication.c1-300 src/replication.c3000-3300 src/server.h1800-2000

Deployment Modes

Mode	File	Purpose	Key Structures
Standalone	server.c	Single instance	redisServer
Master-Replica	replication.c	Async replication for read scaling	server.master, server.slaves
Sentinel	sentinel.c	Monitor masters and auto-failover	sentinelState
Cluster	cluster.c	Sharded keyspace (16384 slots)	clusterState, clusterNode

For cluster and sentinel details, see sections 6.1 and 6.2.

Sources: src/server.c src/replication.c src/sentinel.c src/cluster.c

---

Extensibility

Scripting

Lua and Functions system at src/script_lua.c src/functions.c:

• EVAL/EVALSHA: Execute Lua 5.1 scripts with redis.call() / redis.pcall()
• FUNCTION LOAD: Define persistent Lua functions (stored in server.functions)
• FCALL: Invoke loaded functions
• Sandboxing: Restricted Lua API, no file I/O, limited libraries

Script execution at src/eval.c:

1. evalGenericCommand() compiles Lua code
2. Runs in scriptRunCtx with time limit (lua-time-limit)
3. Commands invoked via luaRedisCallCommand() go through normal call() path

Sources: src/script_lua.c src/eval.c src/functions.c

Module API

Diagram: Module System Architecture

Modules are .so files loaded at runtime via src/module.c1000-1200:

• Entry point: RedisModule_OnLoad(RedisModuleCtx *ctx, RedisModuleString **argv, int argc)
• Register commands: RedisModule_CreateCommand(ctx, "mycommand", myCommandFunc, "write", ...)
• Define types: RedisModule_CreateDataType() with RDB save/load callbacks
• Access data: RedisModule_OpenKey(), RedisModule_Call() to execute commands

The module API (120+ functions) at src/redismodule.h includes:

• Memory management: RedisModule_Alloc(), RedisModule_Free()
• Keyspace access: RedisModule_OpenKey(), RedisModule_CloseKey()
• Replication: RedisModule_Replicate(), RedisModule_ReplicateVerbatim()
• Blocking: RedisModule_BlockClient(), RedisModule_UnblockClient()
• Events: RedisModule_SubscribeToKeyspaceEvents()

Sources: src/module.c1-500 src/module.c1000-1200 src/redismodule.h1-200

---

Configuration

Redis configuration at src/config.c is managed through:

Configuration Loading:

1. loadServerConfigFromString() at src/config.c450-800: Parse redis.conf
2. standardConfig table at src/config.c2800-4000: Defines all settings
3. configs dict: Maps config name (sds) to standardConfig*

Runtime Changes:

• CONFIG GET <pattern>: Returns matching configs
• CONFIG SET <name> <value>: Modifies running config
• CONFIG REWRITE: Writes current values back to redis.conf

Key Config Categories:

Category	Example Directives	Implementation
Memory	maxmemory, maxmemory-policy	src/config.c3000-3100
Persistence	save, appendonly, aof-fsync	src/config.c3200-3400
Networking	bind, port, tcp-backlog	src/config.c2900-3000
Security	requirepass, aclfile	src/config.c3500-3600
Replication	replicaof, repl-diskless-sync	src/config.c3700-3900
Cluster	cluster-enabled, cluster-config-file	src/config.c4000-4100

Each standardConfig defines:

• name: Config directive string
• set(): Function to validate and apply value
• get(): Function to read current value
• rewrite(): Function to format for redis.conf

Sources: src/config.c450-1000 src/config.c2800-4200 redis.conf1-500

---

Client Tools

The distribution includes command-line utilities:

Tool	File	Purpose
redis-server	server.c	Main daemon (also Sentinel with --sentinel)
redis-cli	redis-cli.c	Interactive REPL client
redis-benchmark	redis-benchmark.c	Performance testing and latency measurement
redis-check-rdb	redis-check-rdb.c	Validate/repair RDB files
redis-check-aof	redis-check-aof.c	Validate/repair AOF files

redis-cli features at src/redis-cli.c:

• Interactive mode with command completion and help
• Cluster mode: redis-cli -c follows redirections
• Pipe mode: echo "SET key val" | redis-cli --pipe
• RESP3 protocol support: redis-cli --resp3
• Introspection: --bigkeys, --memkeys, --latency

redis-benchmark features at src/redis-benchmark.c:

• Measure throughput: redis-benchmark -t SET,GET -n 100000
• Pipeline testing: redis-benchmark -P 16
• Cluster mode: redis-benchmark --cluster
• Latency histograms: Percentiles (p50, p95, p99)

Sources: src/redis-cli.c1-500 src/redis-benchmark.c1-500

---

System Organization

Major Subsystems

Based on code importance metrics (edit frequency × impact), the codebase subsystems are:

Subsystem	Primary Files	Importance	Description
Core Server	server.c, server.h	927.74	Global state, event loop, cron tasks
Networking	networking.c	682.68	Client I/O, RESP parsing, reply buffers
Module API	module.c	718.53	Dynamic module loading and API
Configuration	config.c	439.59	Runtime config management
Database	db.c	436.90	Key lookup, expiration, notifications
Replication	replication.c	421.22	PSYNC protocol, backlog, replica management
RDB	rdb.c	391.22	Binary snapshots, save/load
AOF	aof.c	286.66	Append-only file, manifest, rewrite
Data Types	t_string.c, t_list.c, t_set.c, t_zset.c, t_hash.c, t_stream.c	Various	Type-specific commands
Cluster	cluster.c, cluster_asm.c	Various	Sharding, slot migration
Sentinel	sentinel.c	Medium	Failover and monitoring

File Organization

src/
├── server.c/h          # Main server and global state
├── networking.c        # Client connection handling
├── ae.c/h             # Event loop (epoll/kqueue/select)
├── db.c               # Database operations
├── object.c           # Object allocation (robj/kvobj)
├── dict.c/h           # Hash table implementation
├── kvstore.c/h        # Slot-based dict wrapper
├── sds.c/h            # Dynamic string library
├── t_*.c              # Data type implementations
├── commands.c         # Command table definition
├── config.c           # Configuration system
├── rdb.c              # RDB persistence
├── aof.c              # AOF persistence
├── replication.c      # Master-replica sync
├── cluster.c          # Cluster mode
├── sentinel.c         # Sentinel mode
├── module.c           # Module API
├── script_lua.c       # Lua scripting
├── functions.c        # Function library
├── acl.c              # Access control lists
├── evict.c            # Eviction policies
├── expire.c           # Key expiration
├── lazyfree.c         # Background deletion
└── bio.c              # Background I/O threads

Sources: src/server.c1-100 src/networking.c1-100 src/module.c1-100

---

Memory Management

Allocator Abstraction

The zmalloc layer at src/zmalloc.c wraps the underlying allocator:

Supported allocators (configure with USE_JEMALLOC, USE_TCMALLOC):

• jemalloc (default): Low fragmentation, good for Redis workloads
• tcmalloc: Google's thread-caching allocator
• libc malloc: System allocator (fallback)

All allocations update server.stat_alloced_bytes for INFO memory reporting.

Eviction

When used_memory exceeds maxmemory, eviction at src/evict.c removes keys based on policy:

Policy	Constant	Behavior
volatile-lru	MAXMEMORY_VOLATILE_LRU	LRU among keys with TTL
volatile-lfu	MAXMEMORY_VOLATILE_LFU	LFU among keys with TTL
volatile-ttl	MAXMEMORY_VOLATILE_TTL	Soonest expiring keys
allkeys-lru	MAXMEMORY_ALLKEYS_LRU	LRU among all keys
allkeys-lfu	MAXMEMORY_ALLKEYS_LFU	LFU among all keys
allkeys-lrm	MAXMEMORY_ALLKEYS_LRM	LRM (Least Recently Modified) among all keys
noeviction	MAXMEMORY_NO_EVICTION	Return errors on OOM

Eviction function evictData() at src/evict.c600-800 uses a sampling pool to avoid full dataset scan.

Background Operations

Bio (Background I/O) threads at src/bio.c1-200:

• BIO_CLOSE_FILE: Close file descriptors asynchronously
• BIO_AOF_FSYNC: Fsync AOF in background
• BIO_LAZY_FREE: Delete large objects (lists, sets, hashes) without blocking

Lazy free at src/lazyfree.c:

• dbAsyncDelete(): Queue key deletion to bio thread
• freeObjAsync(): Schedule large object freeing
• Triggered when object has many elements (>64 for lists, >64 for sets, etc.)

Sources: src/zmalloc.c1-200 src/evict.c600-900 src/bio.c1-200 src/lazyfree.c1-200

---

Thread Model

Redis is single-threaded for command execution to ensure:

• No data structure locks required
• Atomic command execution without explicit transactions
• Predictable latency (no lock contention)

Optional threading:

Thread Type	Config	Purpose
I/O threads	io-threads <N>	Parallelize socket read/write (networking.c)
BIO threads	Always on (3 threads)	Background file close, AOF fsync, lazy free
Module threads	Created by modules	Blocking operations, background work

I/O threading at src/networking.c3500-3800:

• Enabled with io-threads > 1
• Threads read from sockets into c->querybuf
• Threads write from c->buf to sockets
• Main thread still handles all command execution

Sources: src/networking.c3500-3800 src/bio.c1-100 src/server.h2300-2400

---

Related Pages

For deeper dives into specific subsystems:

• Server Architecture and Lifecycle - Initialization, event loop, shutdown
• Command Processing Pipeline - RESP parsing, ACL, command dispatch
• Data Storage and Management - kvstore, dict, data type encodings
• Memory Management - Eviction, expiration, allocators
• Scripting and Extensions - Lua, modules, custom commands
• High Availability and Distribution - Cluster, Sentinel, replication
• Persistence and Replication - RDB, AOF, PSYNC protocol
• Security - ACL, TLS, protected mode
• Client Tools - redis-cli, redis-benchmark
• Development and Testing - Build system, test framework

---

Summary

Redis is a high-performance in-memory data store with:

• Rich data types: Strings, Lists, Sets, Sorted Sets, Hashes, Streams
• Flexible persistence: RDB snapshots and AOF logs
• Scalability: Master-replica replication, Sentinel failover, Cluster sharding
• Extensibility: Lua scripting and C module API
• Simple architecture: Single-threaded event loop with optional I/O threading

The codebase centers around the struct redisServer server global state, an event-driven networking layer, and a command processing pipeline that routes requests to data type implementations.

Sources: src/server.h1800-2500 src/server.c1-300 redis.conf1-100