Common utilities

src/Common/ is the project's standard library. It accumulates everything the engine needs that is not in the C++ standard library. The directory has 14 sub-folders and hundreds of files.

Highlights

Containers and allocators

• Arena.h, ArenaWithFreeLists.h — bump-pointer arenas used by aggregate states.
• Allocator.h, AllocatorWithMemoryTracking.h — typed allocators that integrate with MemoryTracker.
• PODArray.h — aligned, padded, SIMD-friendly array (the workhorse buffer).
• HashTable/ — many specialised hash tables (HashTable, HashSet, HashMap, StringHashTable, TwoLevelHashTable, ClearableHashSet, LRUHashMap).
• LRUCache.h, CacheBase.h, LRUFileCachePriority.cpp — generic caches.
• IntervalTree.h, RadixSort.h, BitHelpers.h — algorithm helpers.

Memory tracking and profiling

• MemoryTracker.cpp — hierarchical memory accounting with parent links (per-query → user → server).
• ProfileEvents.cpp, CurrentMetrics.cpp — counters and gauges that flow into system.events / system.metrics.
• Stopwatch.h, ProfileEventTimeIncrement.h — timing.
• QueryProfiler.cpp, TraceCollector.cpp — sampling profilers feeding system.trace_log.
• Throttler.cpp — token-bucket rate limiters.

Concurrency

• ThreadPool.h — the project's shared global thread pool plus typed pools.
• BackgroundSchedulePool.cpp — long-lived task scheduler used by replication, fetches, dictionary reload, cluster discovery.
• ConcurrentBoundedQueue.h, Semaphore.h, SharedMutex.h, SharedMutexHelper.h.
• ThreadStatus.cpp, ThreadStatusExt.cpp — per-thread context (memory tracker, query id, opentel span).
• CancelToken.h — cooperative query cancellation.

ZooKeeper / Keeper client

• ZooKeeper/ZooKeeper.cpp — high-level client (used by every replicated subsystem).
• ZooKeeper/ZooKeeperImpl.cpp — wire protocol implementation.
• ZooKeeper/ZooKeeperWithFaultInjection.h — wrapper used by tests.
• Retry logic, multi-connection failover, watches.

Logging and exceptions

• Logger.h, Exception.h, StackTrace.cpp, ErrorCodes.cpp.
• LoggerHooks.cpp — bridges to text/structured logs.
• formatReadable.h, formatIPv6.h — pretty printers.

Strings, hashing, regex

• StringUtils.h, UTF8Helpers.cpp, OptimizedRegularExpression.cpp (with vectorscan / re2 backends).
• SipHash.h, FarmHash.cpp, MurmurHash.cpp, XxHash.cpp, intHash.h.

Filesystem and OS glue

• filesystemHelpers.cpp, MemoryTrackerBlockerInThread.h.
• Crypto/, OpenSSLHelpers.cpp.
• Daemon/, EnvironmentChecks.cpp, getHashOfLoadedBinary.cpp — startup-time host inspection (used by programs/main.cpp).
• Crypto/OpenSSLInitializer.cpp — early OpenSSL setup.

Networking

• DNSResolver.cpp — DNS cache.
• IPv6.cpp, parseRemoteDescription.cpp, DNSPTRResolverProvider.cpp.
• HTTP/, Poco overrides, URI.h.

Configuration

• Config/ConfigProcessor.cpp, Config/ConfigReloader.cpp.
• getRandomASCIIString.cpp, randomSeed.cpp.

Telemetry / OpenTelemetry

• OpenTelemetryTraceContext.cpp.

AsyncLoader

• AsyncLoader.h, AsyncLoader.cpp — graph-based loader used to bring up databases and dictionaries on startup with parallelism and priority. There's a debug visualizer at utils/async_loader_graph.

Process supervision and Daemon

(src/Daemon/) BaseDaemon.cpp — the base class behind Server, Keeper, LocalServer. Handles signal handlers, log file rotation, working-directory management, write-pid files.

Misc

• Crypto/, EnvironmentChecks.cpp, Coverage.cpp.
• RemoteHostFilter.cpp — server-side host allowlists for url(...) / s3(...) table functions.
• ZooKeeper/ZooKeeperLog.cpp — populates system.zookeeper_log.
• tests/gtest_*.cpp — unit tests for the above.

Style

src/Common/ enforces the project's style at the lowest level: Allman braces, no using namespace at file scope, Logger-based logging, Exception-based errors. It's also where AGENTS.md-mandated rules show up first — e.g. Stopwatch for timing rather than gettimeofday, MemoryTracker accounting on every hot allocation.

Related pages

• Coordination — the Keeper client lives here.
• Interpreters — BackgroundSchedulePool and MemoryTracker are used everywhere.
• Patterns and conventions