Metrics and Locking

Metrics and Locking#

Metrics#

Cache facade metrics API:

  • setMetricsCollector(CacheMetricsCollectorInterface $metrics): self

  • exportMetrics(): array

  • setMetricsExportHook(?callable $hook): self

Default collector is InMemoryCacheMetricsCollector. Exported snapshots use readable adapter keys such as file, pdo, redis, valkey, memory, scylladb, and redis_cluster.

Metric counters are tracked per adapter name, for example:

  • hit

  • miss

  • set

  • delete

  • delete_batch

  • remember_hit

  • remember_miss

use Infocyph\CacheLayer\Cache\Metrics\InMemoryCacheMetricsCollector;

$cache->setMetricsCollector(new InMemoryCacheMetricsCollector());

$cache->set('k', 'v');
$cache->get('k');

$metrics = $cache->exportMetrics();
// ['file' => ['set' => 1, 'hit' => 1, ...]]

Locking and Stampede Protection#

Cache::remember() acquires a lock to prevent duplicate recomputation.

Default:

  • FileLockProvider

Optional providers:

  • RedisLockProvider

  • MemcachedLockProvider

  • PdoLockProvider

Facade helpers:

  • setLockProvider(LockProviderInterface $provider): self

  • useRedisLock(?Redis $client = null, string $prefix = 'cachelayer:lock:'): self

  • useValkeyLock(?Redis $client = null, string $prefix = 'cachelayer:lock:'): self

  • useMemcachedLock(?Memcached $client = null, string $prefix = 'cachelayer:lock:'): self

Custom lock providers can implement LockProviderInterface:

interface LockProviderInterface
{
    public function acquire(string $key, float $waitSeconds): ?LockHandle;
    public function release(?LockHandle $handle): void;
}

LockHandle carries key/token/resource metadata used by providers to release locks safely.

Adapter defaults:

  • Redis adapter factory sets RedisLockProvider

  • Valkey adapter factory sets RedisLockProvider

  • Memcached adapter factory sets MemcachedLockProvider

  • PDO/SQLite adapter factories set PdoLockProvider

  • all other adapters use FileLockProvider by default