Lines n/a 0 / 0
Functions and Methods n/a 0 / 0
Classes and Traits n/a 0 / 0
Name Lines Functions and Methods CRAP Classes and Traits
1<?php
2
3declare(strict_types=1);
4
5namespace BlueprintAU\Radiant\Database\Locks;
6
7/**
8 * A cross-process mutual-exclusion gate for arbitrary work.
9 *
10 * Anything a multi-instance host must serialize — the schema `diff → apply`
11 * loop (with `DROP TABLE` in its vocabulary), cache warmups, cron jobs that
12 * must not overlap — needs this gate. The library ships SQL-backed adapters
13 * for each dialect; the host decides when and what to lock, because a lock
14 * nobody asked for is a deadlock nobody can debug.
15 *
16 * The host wraps its critical section:
17 *
18 * ```
19 * $lock = new PostgresLock($connection);   // dialect adapter
20 * $lock->withLock(function (): void {
21 *     // ... work that must be serialized across processes ...
22 * });
23 * ```
24 *
25 * Dialect adapters ship in {@see BlueprintAU\Radiant\Database\Locks}; the
26 * default {@see NoopLock} documents that locking is the host's explicit
27 * decision — the library never silently takes global locks a host did not
28 * ask for.
29 */
30interface Lock
31{
32    /**
33     * Run the callback while holding the named cross-process lock.
34     *
35     * Implementations must block until the lock is acquired (or fail
36     * loudly), hold it for the callback's duration, and always release it —
37     * including on exception. The name is supplied per call, not per
38     * adapter: one name is one mutual-exclusion domain.
39     *
40     * @template TReturn
41     *
42     * @param  callable(): TReturn  $callback
43     * @param  string  $name  A distinct name per distinct critical section.
44     * @return TReturn
45     * @throws \Throwable
46     */
47    public function withLock(callable $callback, string $name): mixed;
48}