:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
use std::sync::Arc;
use dashmap::DashMap;
use metrics::counter;
use super::codec::PropertiesCodec;
use super::persons::{CachedPerson, CachedVersion, PersonCache, PersonCacheKey};
/// Result of a cache lookup that distinguishes partition ownership from person existence.
pub enum CacheLookup {
Found(CachedPerson),
PersonNotFound,
PartitionNotOwned,
}
/// Per-partition cache manager. Each partition gets its own independent
/// Foyer cache so that releasing a partition drops all its entries cleanly.
pub struct PartitionedCache {
partitions: DashMap<u32, PersonCache>,
/// Partitions mid-warm: built here record by record — evicting under
/// the same per-partition byte budget as a serving cache — and moved
/// to `partitions` in a single insert when the warm's range
/// completes. Entirely invisible to readers: `get`/`has_partition`
/// consult `partitions` only, so a partition under construction
/// answers `PartitionNotOwned` on every path.
warming: DashMap<u32, PersonCache>,
per_partition_capacity: usize,
codec: Arc<PropertiesCodec>,
}
impl PartitionedCache {
pub fn new(per_partition_capacity: usize) -> Self {
Self {
partitions: DashMap::new(),
warming: DashMap::new(),
per_partition_capacity,
codec: Arc::new(PropertiesCodec::disabled()),
}
}
/// Call before any partition exists.
pub fn with_properties_compression(mut self, enabled: bool) -> Self {
if enabled {
self.codec = Arc::new(PropertiesCodec::enabled());
}
self
}
/// Create a new cache for the given partition. Called during warm-up.
pub fn create_partition(&self, partition: u32) {
self.partitions.insert(
partition,
PersonCache::new(self.per_partition_capacity, Arc::clone(&self.codec)),
);
}
/// Atomically install a fully-populated partition cache. The records
/// are inserted into a fresh `PersonCache` *before* the partition is
/// added to the shared `DashMap`, so any thread that observes
/// `has_partition(partition) == true` will also see every record —
/// no observer can land in the window where the partition exists
/// but its keys haven't been put yet. Used by warming so reads that
/// arrive immediately after a handoff Complete don't fall through
/// to PG and return stale values for records that the writer hasn't
/// yet persisted.
pub fn install_warmed_partition(
&self,
partition: u32,
records: impl IntoIterator<Item = (PersonCacheKey, CachedPerson)>,
) {
self.begin_warm_partition(partition);
for (key, person) in records {
self.warm_put(partition, key, person);
}
self.publish_warmed_partition(partition);
}
/// Start building a partition's cache without publishing it. The
/// warm inserts record by record with `warm_put` — bounded by the
/// per-partition budget, evicting as it goes — and publishes the
/// finished cache with `publish_warmed_partition`. Re-entrant: a
/// retried warm begins fresh, replacing any half-built predecessor.
pub fn begin_warm_partition(&self, partition: u32) {
// A build over a published partition would let the prune settle
// marks the build depends on; release drops the cache first.
assert!(
!self.partitions.contains_key(&partition),
"warm began for published partition {partition}"
);
self.warming.insert(
partition,
PersonCache::new(self.per_partition_capacity, Arc::clone(&self.codec)),
);
}
/// Insert one record into a partition cache under construction.
pub fn warm_put(&self, partition: u32, key: PersonCacheKey, person: CachedPerson) {
self.warming
.get(&partition)
.expect("warm_put before begin_warm_partition")
.put(key, person);
}
/// Whether the partition is published (serving reads). The prune
/// only settles published partitions' marks.
pub fn is_published(&self, partition: u32) -> bool {
self.partitions.contains_key(&partition)
}
/// Publish a fully-built partition cache: one `DashMap` insert flips
/// the partition from invisible to fully observable, preserving the
/// no-partial-window property `install_warmed_partition` documents.
pub fn publish_warmed_partition(&self, partition: u32) {
let (_, cache) = self
.warming
.remove(&partition)
.expect("publish_warmed_partition before begin_warm_partition");
self.partitions.insert(partition, cache);
}
/// Discard a partition cache under construction (a warm that failed
/// mid-range). Nothing was ever observable.
pub fn abort_warm_partition(&self, partition: u32) {
self.warming.remove(&partition);
}
/// Resident weight of a build in flight — what the warm retained of
/// its range under the budget.
pub fn warm_usage_bytes(&self, partition: u32) -> usize {
self.warming
.get(&partition)
.map(|c| c.usage_bytes())
.unwrap_or(0)
}
/// Drop the cache for the given partition, evicting all entries —
/// including a build in flight, so a release racing a warm leaves
/// nothing behind.
pub fn drop_partition(&self, partition: u32) {
self.partitions.remove(&partition);
self.warming.remove(&partition);
}
/// Total resident weight in bytes across all owned partitions,
/// builds in flight included — the gauge tells the truth during
/// warms rather than hiding the construction cost.
pub fn usage_bytes(&self) -> usize {
self.partitions
.iter()
.map(|c| c.usage_bytes())
.sum::<usize>()
+ self.warming.iter().map(|c| c.usage_bytes()).sum::<usize>()
}
/// Check if a partition cache exists (i.e., the partition is owned).
pub fn has_partition(&self, partition: u32) -> bool {
self.partitions.contains_key(&partition)
}
/// Look up a person in the partition's cache with a single DashMap lock acquisition.
pub fn get(&self, partition: u32, key: &PersonCacheKey) -> CacheLookup {
match self.partitions.get(&partition) {
Some(cache) => match cache.get(key) {
Some(person) => CacheLookup::Found(person),
None => CacheLookup::PersonNotFound,
},
None => {
counter!("personhog_leader_unowned_partition_total").increment(1);
CacheLookup::PartitionNotOwned
}
}
}
/// Insert or update a person in the partition's cache.
pub fn put(&self, partition: u32, key: PersonCacheKey, person: CachedPerson) {
if let Some(cache) = self.partitions.get(&partition) {
cache.put(key, person);
}
}
/// Counter-free read for bookkeeping passes; see [`PersonCache::peek`].
pub fn peek(&self, partition: u32, key: &PersonCacheKey) -> Option<CachedVersion> {
self.partitions
.get(&partition)
.and_then(|cache| cache.peek(key))
}
/// Remove one person. Called by the death-document settle and by
/// tests; safe regardless — the miss path recovers from the
/// changelog or PG.
pub fn remove(&self, partition: u32, key: &PersonCacheKey) {
if let Some(cache) = self.partitions.get(&partition) {
cache.remove(key);
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn test_key() -> PersonCacheKey {
PersonCacheKey {
team_id: 42,
person_id: 1,
}
}
fn test_person() -> CachedPerson {
CachedPerson {
id: 1,
uuid: "abc-123".to_string(),
team_id: 42,
properties: serde_json::to_vec(&json!({"email": "[email protected]"})).unwrap(),
created_at: 1700000000,
version: 1,
is_identified: false,
is_deleted: false,
last_seen_at: None,
}
}
#[test]
#[should_panic(expected = "warm began for published partition")]
fn a_warm_must_not_begin_over_a_published_partition() {
let cache = PartitionedCache::new(1 << 20);
cache.create_partition(0);
cache.begin_warm_partition(0);
}
#[test]
fn get_returns_partition_not_owned_for_unknown_partition() {
let cache = PartitionedCache::new(1 << 20);
assert!(matches!(
cache.get(0, &test_key()),
CacheLookup::PartitionNotOwned
));
}
#[test]
fn create_and_use_partition() {
let cache = PartitionedCache::new(1 << 20);
cache.create_partition(0);
assert!(cache.has_partition(0));
cache.put(0, test_key(), test_person());
let CacheLookup::Found(person) = cache.get(0, &test_key()) else {
panic!("expected Found");
};
assert_eq!(person.id, 1);
}
#[test]
fn drop_partition_evicts_all_entries() {
let cache = PartitionedCache::new(1 << 20);
cache.create_partition(0);
cache.put(0, test_key(), test_person());
cache.drop_partition(0);
assert!(!cache.has_partition(0));
assert!(matches!(
cache.get(0, &test_key()),
CacheLookup::PartitionNotOwned
));
}
#[test]
fn partitions_are_isolated() {
let cache = PartitionedCache::new(1 << 20);
cache.create_partition(0);
cache.create_partition(1);
cache.put(0, test_key(), test_person());
assert!(matches!(cache.get(0, &test_key()), CacheLookup::Found(_)));
assert!(matches!(
cache.get(1, &test_key()),
CacheLookup::PersonNotFound
));
}
#[test]
fn put_to_unknown_partition_is_noop() {
let cache = PartitionedCache::new(1 << 20);
cache.put(99, test_key(), test_person());
assert!(matches!(
cache.get(99, &test_key()),
CacheLookup::PartitionNotOwned
));
}
}