remi-san / lock
A locking lib
Installs: 6 366
Dependents: 0
Suggesters: 0
Security: 0
Stars: 4
Watchers: 2
Forks: 1
Open Issues: 0
Requires
- php: >=5.5
- ext-redis: *
- psr/log: ^1.0
- symfony/stopwatch: ^2.6|^3.1
Requires (Dev)
- mockery/mockery: ^0.9
- phpunit/phpunit: ^4.5
- squizlabs/php_codesniffer: ^2.0
This package is auto-updated.
Last update: 2024-10-21 22:20:46 UTC
README
Description
Lock
is a library aimed at providing a simple and reliable way to lock resources.
Main classes
-
RemiSan\Lock\Locker
which provides an interface containing the following methods:lock
to lock a resource for a given time (ttl
- not mandatory), allowing to retry a certain amount of times until success.isLocked
to check if a resource is still locked.unlock
to unlock a resource.
-
RemiSan\Lock\Lock
which provides a structure to store information about the lock:resource
the resource that has been lockedtoken
a token generated by theLocker
(using aRemiSan\Lock\TokenGenerator
implementation) to ensure the requested unlocking resource is the same that the one who's been locked.validityEndTime
the time (in milliseconds since EPOCH) at which the lock will be automatically released (if a ttl has been defined).
Token Generators
As the Locker
will need to generate a unique token to lock the resource
, a TokenGenerator
interface has been defined, and 2 implementations are available:
RandomTokenGenerator
which will provide a random token.FixedTokenGenerator
which will always provide the token passed in the constructor.
Examples:
use RemiSan\Lock\TokenGenerator\RandomTokenGenerator; $tokenGenerator = new RandomTokenGenerator(); echo $tokenGenerator->generateToken(); // 'QcWY1WFoRTC68vTNIkTs5cuLmw9YuY9rwS6IsY0xjzA='
use RemiSan\Lock\TokenGenerator\FixedTokenGenerator; $tokenGenerator = new FixedTokenGenerator('my_token'); echo $tokenGenerator->generateToken(); // 'my_token'
Quorum
Quorum
is used to determinate if enough LockStores
have written the lock to consider it really locked.
Two implementations are provided:
MajorityQuorum
which will state quorum is met if more than half of the stores have written the lock.UnanimousQuorum
which will state quorum is met if all stores have written the lock.
Quorum is only used when dealing with multiple stores.
Usage
Create
You can chose between the Single-Store implementation:
use RemiSan\Lock\LockStore\RedisLockStore; use RemiSan\Lock\Locker\SingleStoreLocker; use RemiSan\Lock\TokenGenerator\RandomTokenGenerator; use Symfony\Component\Stopwatch\Stopwatch; $connection = new \Redis(); $server->connect('127.0.0.1', 6379, 0.1); $tokenGenerator = new RandomTokenGenerator(); $stopwatch = new Stopwatch(); $redLock = new SingleStoreLocker( new RedisLockStore($connection), $tokenGenerator, $stopwatch );
Or the Multiple-Store implementation:
use RemiSan\Lock\LockStore\RedisLockStore; use RemiSan\Lock\Locker\MultipleStoreLocker; use RemiSan\Lock\Quorum\MajorityQuorum; use RemiSan\Lock\TokenGenerator\RandomTokenGenerator; use Symfony\Component\Stopwatch\Stopwatch; $connection1 = new \Redis(); $server->connect('127.0.0.1', 6379, 0.1); $connection2 = new \Redis(); $server->connect('127.0.0.1', 6380, 0.1); $tokenGenerator = new RandomTokenGenerator(); $quorum = new MajorityQuorum(); $stopwatch = new Stopwatch(); $redLock = new MultipleStoreLocker( [ new RedisLockStore($connection1), new RedisLockStore($connection2) ], $tokenGenerator, $quorum, $stopwatch );
Acquire a lock
You can acquire a lock on a resource by providing its name, the ttl
, the retry count and the time (in milliseconds) to wait before retrying.
$lock = $locker->lock('my_resource_name', 1000, 3, 100);
This example will try to lock the resource my_resource_name
for 1 second (1000ms) and will retry to acquire it 3 times if it fails the first time (4 in total if all fail), waiting 100ms between each try.
If the lock is acquired, it will return a Lock
object describing it.
If it failed being acquired, it will throw a RemiSan\Lock\Exceptions\LockingException
.
For the Multiple-Store: The lock will be acquired only if the number of instances that have been able to acquire the lock meet the quorum (the calculation of the quorum
is made according to the implementation of Quorum
passed to the MultipleInstanceLocker
).
Assert if a lock exists
You can ask the Locker
if a resource is still locked.
$isLocked = $locker->isLocked('my_resource_name');
If the resource is still locked (lock has been acquired and ttl hasn't expired), it will return true
, it will return false
otherwise.
For the Multiple-Store: If at least one connected instance has the lock, it will consider having the lock.
Release a lock
To release a lock you have to provide it to the Locker
.
$locker->unlock($lock);
If the lock is still active, it will release it. If it fails but the lock wasn't active anymore, it won't cause any error.
If it fails releasing the lock and the lock is still active, it will throw a RemiSan\Lock\Exceptions\UnlockingException
.
For the Multiple-Store: If at least one connected instance fails releasing the lock while still detaining it, the exception will be thrown.
Redis LockStore
Based on Redlock-rb by Salvatore Sanfilippo and ronnylt/redlock-php.
This library implements the Redis-based distributed lock manager algorithm described in this Redis article.
This lib provides a RedisLockStore
implementing the RedLock
mechanism.
DISCLAIMER: As stated in the original antirez
version, this code implements an algorithm which is currently a proposal, it was not formally analyzed. Make sure to understand how it works before using it in your production environments.
Other LockStores
That will come at some point, but it's not there yet.