Skip to content

Commit 256adaa

Browse files
antonkomarevantonkomarev
committed
Leave only *Handler API
1 parent 67e8dff commit 256adaa

File tree

6 files changed

+51
-45
lines changed

6 files changed

+51
-45
lines changed

‎README.md‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -60,12 +60,12 @@ Callback API
6060
$dbConnection = new PDO($dsn, $username, $password);
6161

6262
$locker = new \Cog\DbLocker\Postgres\PostgresAdvisoryLocker();
63-
$lockId = \Cog\DbLocker\Postgres\PostgresLockKey::create('user', '4');
63+
$lockKey = \Cog\DbLocker\Postgres\PostgresLockKey::create('user', '4');
6464

6565
$payment = $locker->withinSessionLevelLock(
66-
$dbConnection,
67-
$lockId,
68-
function (
66+
dbConnection: $dbConnection,
67+
key: $lockKey,
68+
callback: function (
6969
\Cog\DbLocker\Postgres\LockHandle\SessionLevelLockHandle $lock,
7070
): Payment { // Define a type of $payment variable, so it will be resolved by analyzers
7171
if ($lock->wasAcquired) {
@@ -74,24 +74,25 @@ $payment = $locker->withinSessionLevelLock(
7474
// Execute logic if lock acquisition has been failed
7575
}
7676
},
77-
\Cog\DbLocker\Postgres\Enum\PostgresLockWaitModeEnum::NonBlocking,
78-
\Cog\DbLocker\Postgres\Enum\PostgresLockAccessModeEnum::Exclusive,
77+
waitMode: \Cog\DbLocker\Postgres\Enum\PostgresLockWaitModeEnum::NonBlocking,
78+
accessMode: \Cog\DbLocker\Postgres\Enum\PostgresLockAccessModeEnum::Exclusive,
7979
);
8080
```
8181

8282
Low-level API
83+
8384
```php
8485
$dbConnection = new PDO($dsn, $username, $password);
8586

8687
$locker = new \Cog\DbLocker\Postgres\PostgresAdvisoryLocker();
87-
$lockId = \Cog\DbLocker\Postgres\PostgresLockKey::create('user', '4');
88+
$lockKey = \Cog\DbLocker\Postgres\PostgresLockKey::create('user', '4');
8889

8990
try {
9091
$lock = $locker->acquireSessionLevelLock(
91-
$dbConnection,
92-
$lockId,
93-
\Cog\DbLocker\Postgres\Enum\PostgresLockWaitModeEnum::NonBlocking,
94-
\Cog\DbLocker\Postgres\Enum\PostgresLockAccessModeEnum::Exclusive,
92+
dbConnection: $dbConnection,
93+
key: $lockKey,
94+
waitMode: \Cog\DbLocker\Postgres\Enum\PostgresLockWaitModeEnum::NonBlocking,
95+
accessMode: \Cog\DbLocker\Postgres\Enum\PostgresLockAccessModeEnum::Exclusive,
9596
);
9697
if ($lock->wasAcquired) {
9798
// Execute logic if lock was successful

‎src/Postgres/Enum/PostgresLockAccessModeEnum.php‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,10 @@
77
/**
88
* PostgresLockAccessModeEnum defines the access mode of advisory lock acquisition.
99
*
10-
* TODO: Need string values only for tests, should add match to tests instead.
10+
* TODO: Write details about access mode.
1111
*/
12-
enum PostgresLockAccessModeEnum: string
12+
enum PostgresLockAccessModeEnum
1313
{
14-
case Exclusive = 'ExclusiveLock';
15-
case Share = 'ShareLock';
14+
case Exclusive;
15+
case Share;
1616
}

‎src/Postgres/Enum/PostgresLockLevelEnum.php‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,19 @@
77
/**
88
* PostgresLockLevelEnum defines the level of advisory lock acquisition.
99
*
10+
* - Transaction. Transaction-level (recommended) advisory lock (with _XACT_):
11+
* - PG_ADVISORY_XACT_LOCK
12+
* - PG_ADVISORY_XACT_LOCK_SHARED
13+
* - PG_TRY_ADVISORY_XACT_LOCK
14+
* - PG_TRY_ADVISORY_XACT_LOCK_SHARED
1015
* - Session. Session-level advisory lock (without _XACT_):
1116
* - PG_ADVISORY_LOCK
1217
* - PG_ADVISORY_LOCK_SHARED
1318
* - PG_TRY_ADVISORY_LOCK
1419
* - PG_TRY_ADVISORY_LOCK_SHARED
15-
* - Transaction. Transaction-level advisory lock (with _XACT_):
16-
* - PG_ADVISORY_XACT_LOCK
17-
* - PG_ADVISORY_XACT_LOCK_SHARED
18-
* - PG_TRY_ADVISORY_XACT_LOCK
19-
* - PG_TRY_ADVISORY_XACT_LOCK_SHARED
2020
*/
2121
enum PostgresLockLevelEnum
2222
{
23-
case Session;
2423
case Transaction;
24+
case Session;
2525
}

‎src/Postgres/Enum/PostgresLockWaitModeEnum.php‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,16 @@
77
/**
88
* PostgresLockWaitModeEnum defines the type of advisory lock acquisition.
99
*
10-
* - NonBlocking. Attempt to acquire the lock without blocking (with _TRY_):
11-
* - PG_TRY_ADVISORY_LOCK
12-
* - PG_TRY_ADVISORY_LOCK_SHARED
13-
* - PG_TRY_ADVISORY_XACT_LOCK
14-
* - PG_TRY_ADVISORY_XACT_LOCK_SHARED
1510
* - Blocking. Acquire the lock, blocking until it becomes available (without _TRY_):
1611
* - PG_ADVISORY_LOCK
1712
* - PG_ADVISORY_LOCK_SHARED
1813
* - PG_ADVISORY_XACT_LOCK
1914
* - PG_ADVISORY_XACT_LOCK_SHARED
15+
* - NonBlocking. Attempt to acquire the lock without blocking (with _TRY_):
16+
* - PG_TRY_ADVISORY_LOCK
17+
* - PG_TRY_ADVISORY_LOCK_SHARED
18+
* - PG_TRY_ADVISORY_XACT_LOCK
19+
* - PG_TRY_ADVISORY_XACT_LOCK_SHARED
2020
*/
2121
enum PostgresLockWaitModeEnum
2222
{

‎src/Postgres/PostgresAdvisoryLocker.php‎

Lines changed: 19 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -28,14 +28,14 @@ final class PostgresAdvisoryLocker
2828
*/
2929
public function acquireTransactionLevelLock(
3030
PDO $dbConnection,
31-
PostgresLockKey $postgresLockKey,
31+
PostgresLockKey $key,
3232
PostgresLockWaitModeEnum $waitMode = PostgresLockWaitModeEnum::NonBlocking,
3333
PostgresLockAccessModeEnum $accessMode = PostgresLockAccessModeEnum::Exclusive,
3434
): TransactionLevelLockHandle {
3535
return new TransactionLevelLockHandle(
3636
wasAcquired: $this->acquireLock(
3737
$dbConnection,
38-
$postgresLockKey,
38+
$key,
3939
PostgresLockLevelEnum::Transaction,
4040
$waitMode,
4141
$accessMode,
@@ -63,18 +63,18 @@ public function acquireTransactionLevelLock(
6363
*/
6464
public function acquireSessionLevelLock(
6565
PDO $dbConnection,
66-
PostgresLockKey $postgresLockKey,
66+
PostgresLockKey $key,
6767
PostgresLockWaitModeEnum $waitMode = PostgresLockWaitModeEnum::NonBlocking,
6868
PostgresLockAccessModeEnum $accessMode = PostgresLockAccessModeEnum::Exclusive,
6969
): SessionLevelLockHandle {
7070
return new SessionLevelLockHandle(
7171
$dbConnection,
7272
$this,
73-
$postgresLockKey,
73+
$key,
7474
$accessMode,
7575
wasAcquired: $this->acquireLock(
7676
$dbConnection,
77-
$postgresLockKey,
77+
$key,
7878
PostgresLockLevelEnum::Session,
7979
$waitMode,
8080
$accessMode,
@@ -94,10 +94,9 @@ public function acquireSessionLevelLock(
9494
* ⚠️ Transaction-level advisory locks are strongly preferred whenever possible,
9595
* as they are automatically released at the end of a transaction and are less error-prone.
9696
* Use session-level locks only when transactional context is not available.
97-
* @see acquireTransactionLevelLock() for preferred locking strategy.
9897
*
9998
* @param PDO $dbConnection Active database connection.
100-
* @param PostgresLockKey $postgresLockKey Lock key to be acquired.
99+
* @param PostgresLockKey $key Lock key to be acquired.
101100
* @param callable(SessionLevelLockHandle): TReturn $callback A callback that receives the lock handle.
102101
* @param PostgresLockWaitModeEnum $waitMode Whether to wait for the lock or fail immediately. Default is non-blocking.
103102
* @param PostgresLockAccessModeEnum $accessMode Whether to acquire a shared or exclusive lock. Default is exclusive.
@@ -106,17 +105,19 @@ public function acquireSessionLevelLock(
106105
* @template TReturn
107106
*
108107
* TODO: Cover with tests
108+
*@see acquireTransactionLevelLock() for preferred locking strategy.
109+
*
109110
*/
110111
public function withinSessionLevelLock(
111112
PDO $dbConnection,
112-
PostgresLockKey $postgresLockKey,
113+
PostgresLockKey $key,
113114
callable $callback,
114115
PostgresLockWaitModeEnum $waitMode = PostgresLockWaitModeEnum::NonBlocking,
115116
PostgresLockAccessModeEnum $accessMode = PostgresLockAccessModeEnum::Exclusive,
116117
): mixed {
117118
$lockHandle = $this->acquireSessionLevelLock(
118119
$dbConnection,
119-
$postgresLockKey,
120+
$key,
120121
$waitMode,
121122
$accessMode,
122123
);
@@ -134,20 +135,20 @@ public function withinSessionLevelLock(
134135
*/
135136
public function releaseSessionLevelLock(
136137
PDO $dbConnection,
137-
PostgresLockKey $postgresLockKey,
138+
PostgresLockKey $key,
138139
PostgresLockAccessModeEnum $accessMode = PostgresLockAccessModeEnum::Exclusive,
139140
): bool {
140141
$sql = match ($accessMode) {
141142
PostgresLockAccessModeEnum::Exclusive => 'SELECT PG_ADVISORY_UNLOCK(:class_id, :object_id);',
142143
PostgresLockAccessModeEnum::Share => 'SELECT PG_ADVISORY_UNLOCK_SHARED(:class_id, :object_id);',
143144
};
144-
$sql .= " -- $postgresLockKey->humanReadableValue";
145+
$sql .= " -- $key->humanReadableValue";
145146

146147
$statement = $dbConnection->prepare($sql);
147148
$statement->execute(
148149
[
149-
'class_id' => $postgresLockKey->classId,
150-
'object_id' => $postgresLockKey->objectId,
150+
'class_id' => $key->classId,
151+
'object_id' => $key->objectId,
151152
],
152153
);
153154

@@ -170,14 +171,14 @@ public function releaseAllSessionLevelLocks(
170171

171172
private function acquireLock(
172173
PDO $dbConnection,
173-
PostgresLockKey $postgresLockKey,
174+
PostgresLockKey $key,
174175
PostgresLockLevelEnum $level,
175176
PostgresLockWaitModeEnum $waitMode = PostgresLockWaitModeEnum::NonBlocking,
176177
PostgresLockAccessModeEnum $accessMode = PostgresLockAccessModeEnum::Exclusive,
177178
): bool {
178179
if ($level === PostgresLockLevelEnum::Transaction && $dbConnection->inTransaction() === false) {
179180
throw new LogicException(
180-
"Transaction-level advisory lock `$postgresLockKey->humanReadableValue` cannot be acquired outside of transaction",
181+
"Transaction-level advisory lock `$key->humanReadableValue` cannot be acquired outside of transaction",
181182
);
182183
}
183184

@@ -223,13 +224,13 @@ private function acquireLock(
223224
PostgresLockAccessModeEnum::Share,
224225
] => 'SELECT PG_ADVISORY_LOCK_SHARED(:class_id, :object_id);',
225226
};
226-
$sql .= " -- $postgresLockKey->humanReadableValue";
227+
$sql .= " -- $key->humanReadableValue";
227228

228229
$statement = $dbConnection->prepare($sql);
229230
$statement->execute(
230231
[
231-
'class_id' => $postgresLockKey->classId,
232-
'object_id' => $postgresLockKey->objectId,
232+
'class_id' => $key->classId,
233+
'object_id' => $key->objectId,
233234
],
234235
);
235236

‎test/Integration/AbstractIntegrationTestCase.php‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,11 @@ private function findPostgresAdvisoryLockInConnection(
116116
'lock_object_id' => $postgresLockKey->objectId,
117117
'lock_object_subid' => 2, // Using two keyed locks
118118
'connection_pid' => $dbConnection->pgsqlGetPid(),
119-
'mode' => $mode->value,
119+
'mode' => match ($mode) {
120+
PostgresLockAccessModeEnum::Exclusive => 'ExclusiveLock',
121+
PostgresLockAccessModeEnum::Share => 'ShareLock',
122+
default => throw new \LogicException("Unknown mode $mode->name"),
123+
},
120124
],
121125
);
122126

0 commit comments

Comments
 (0)