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 locked
- token a token generated by the Locker (using a RemiSan\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.

remi-san / lock

Maintainers

Details