Class: Apartment::PoolManager

Inherits:
Object
  • Object
show all
Defined in:
lib/apartment/pool_manager.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ PoolManager

Returns a new instance of PoolManager.



11
12
13
14
15
16
 
# File 'lib/apartment/pool_manager.rb', line 11

def initialize
  @pools = Concurrent::Map.new
  @timestamps = Concurrent::Map.new
  @create_mutex = Mutex.new
  @admission_controller = nil
end

Instance Attribute Details

#admission_controller ⇒ Object

Set by Apartment.configure to the PoolReaper when max_total_connections is configured. nil (no cap) keeps the lock-free compute_if_absent fast path.



9
10
11
 
# File 'lib/apartment/pool_manager.rb', line 9

def admission_controller
  @admission_controller
end

Instance Method Details

#clear ⇒ Object

Disconnect all pools before clearing to prevent connection leaks. Each pool's disconnect! is individually rescued so one broken pool doesn't prevent cleanup of others.



129
130
131
132
133
134
135
136
137
 
# File 'lib/apartment/pool_manager.rb', line 129

def clear
  @pools.each_pair do |key, pool|
    pool.disconnect! if pool.respond_to?(:disconnect!)
  rescue StandardError => e
    warn "[Apartment::PoolManager] Failed to disconnect pool '#{key}': #{e.class}: #{e.message}"
  end
  @pools.clear
  @timestamps.clear
end

#each_pair ⇒ Object

Yields each tracked pool as [tenant_key, pool]. Snapshot semantics follow Concurrent::Map#each_pair: keys observed during iteration are those present at the time the iterator visits them. Read-only; do not mutate the manager from inside the block.



122
123
124
 
# File 'lib/apartment/pool_manager.rb', line 122

def each_pair(&)
  @pools.each_pair(&)
end

#evict_by_role(role) ⇒ Object 



72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/apartment/pool_manager.rb', line 72

def evict_by_role(role)
  suffix = ":#{role}"
  removed = []
  @pools.each_key do |key|
    next unless key.end_with?(suffix)

    pool = remove(key)
    removed << [key, pool] if pool
  end
  removed
end

#fetch_or_create(tenant_key) ⇒ Object

Fetch an existing pool or create one via the block. Timestamp is updated after pool creation to avoid orphaned timestamps if the block raises. When an admission controller is wired (a cap is configured), cold creates go through the bounded path so the pool count cannot exceed max_total.



22
23
24
25
26
 
# File 'lib/apartment/pool_manager.rb', line 22

def fetch_or_create(tenant_key, &)
  return fetch_or_admit(tenant_key, &) if @admission_controller

  touch_and_return(tenant_key, @pools.compute_if_absent(tenant_key, &))
end

#get(tenant_key) ⇒ Object 



28
29
30
31
32
 
# File 'lib/apartment/pool_manager.rb', line 28

def get(tenant_key)
  pool = @pools[tenant_key]
  touch(tenant_key) if pool
  pool
end

#idle_tenants(timeout:) ⇒ Object 



97
98
99
100
 
# File 'lib/apartment/pool_manager.rb', line 97

def idle_tenants(timeout:)
  cutoff = monotonic_now - timeout
  @timestamps.each_pair.filter_map { |key, ts| key if ts < cutoff }
end

#lru_tenants(count:) ⇒ Object 



102
103
104
105
106
107
 
# File 'lib/apartment/pool_manager.rb', line 102

def lru_tenants(count:)
  @timestamps.each_pair
    .sort_by { |_, ts| ts }
    .first(count)
    .map(&:first)
end

#peek(tenant_key) ⇒ Object

Read a pool without updating its idle timestamp. PoolReaper uses this to inspect an eviction candidate; get would reset the very idleness the reaper is measuring.



37
38
39
 
# File 'lib/apartment/pool_manager.rb', line 37

def peek(tenant_key)
  @pools[tenant_key]
end

#remove(tenant_key) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Delete pool first, then timestamp. This ordering prevents a concurrent #get from orphaning a timestamp (get checks @pools, skips touch if absent).

Forgetting a pool here is only HALF of discarding it — the pool stays registered in AR's ConnectionHandler, leaking the registration and a live backend if the tenant is never re-accessed. Callers outside the gem want Apartment.deregister_shard (one pool) or Apartment.reset_tenant_pools! (all). These mutators also bypass PoolReaper's in-use guard: they will drop a pool with a checked-out connection or an open transaction. See docs/designs/out-of-band-tenant-ddl.md.



52
53
54
55
56
 
# File 'lib/apartment/pool_manager.rb', line 52

def remove(tenant_key)
  pool = @pools.delete(tenant_key)
  @timestamps.delete(tenant_key)
  pool
end

#remove_tenant(tenant) ⇒ Object 



59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/apartment/pool_manager.rb', line 59

def remove_tenant(tenant)
  prefix = "#{tenant}:"
  removed = []
  @pools.each_key do |key|
    next unless key.start_with?(prefix)

    pool = remove(key)
    removed << [key, pool] if pool
  end
  removed
end

#stats ⇒ Object

Basic stats. Full observability (per-tenant breakdown, connection counts, eviction counters) deferred to Phase 3.



111
112
113
114
115
116
 
# File 'lib/apartment/pool_manager.rb', line 111

def stats
  {
    total_pools: @pools.size,
    tenants: @pools.keys,
  }
end

#stats_for(tenant_key) ⇒ Object

Returns stats for a tenant pool. Follows ActiveRecord's convention of exposing computed durations (seconds_idle) rather than raw monotonic timestamps, which are meaningless outside the process.



91
92
93
94
95
 
# File 'lib/apartment/pool_manager.rb', line 91

def stats_for(tenant_key)
  return nil unless tracked?(tenant_key)

  { seconds_idle: monotonic_now - @timestamps[tenant_key] }
end

#tracked?(tenant_key) ⇒ Boolean

Returns:

  • (Boolean) 


84
85
86
 
# File 'lib/apartment/pool_manager.rb', line 84

def tracked?(tenant_key)
  @pools.key?(tenant_key)
end