README.md

Distributed locks with Redis and ReactPHP

Asynchronous Redlock algorithm implementation for PHP

Quickstart

Once installed, you can incorporate Redlock in your projects by instantiating its Custodian; this entity is responsible for lock orchestration and it requires access to a Redis client object instance, e.g.

/* Instantiate prerequisites */
$factory = new \Clue\React\Redis\Factory();
$client = $factory->createLazyClient('127.0.0.1');

/* Instantiate our lock custodian */
$custodian = new \RTCKit\React\Redlock\Custodian($client);

Acquiring locks

For use cases where a binary outcome is desirable, the acquire() method works best, e.g.:

/**
 * @param string $resource Redis key name
 * @param float $ttl Lock's time to live (in seconds)
 * @param ?string $token Unique identifier for lock in question
 * @return PromiseInterface
 */
$custodian->acquire('MyResource', 60, 'r4nd0m_token')
    ->then(function (?Lock $lock) {
        if (is_null($lock)) {
            // Ooops, lock could not be acquired for MyResource
        } else {
            // Awesome, MyResource is locked for a minute
            // ...

            // Be nice and release the lock when done
            $custodian->release($lock);
        }
    });

Spinlocks

The spin() method is designed for situations where a process should keep trying acquiring a lock, e.g.

/**
 * @param int $attempts Maximum spin/tries
 * @param float $interval Spin/try interval (in seconds)
 * @param string $resource Redis key name
 * @param float $ttl Lock's time to live (in seconds)
 * @param ?string $token Unique identifier for lock in question
 * @return PromiseInterface
 */
$custodian->spin(100, 0.5, 'HotResource', 10, 'r4nd0m_token')
    ->then(function (?Lock $lock): void {
        if (is_null($lock)) {
            // Wow, after 100 tries (with a gap of 0.5 seconds) I've
            // given up acquiring a lock on HotResource
        } else {
            // Awesome, HotResource is locked for 10 seconds
            // ...

            // Again, be nice and release the lock when done
            $custodian->release($lock);
        }
    })

Lastly, the provided examples are a good starting point.

Requirements

Redlock is compatible with PHP 7.2+ and requires the clue/reactphp-redis library.

Installation

You can add the library as project dependency using Composer:

composer require rtckit/react-redlock

If you only need the library during development, for instance when used in your test suite, then you should add it as a development-only dependency:

composer require --dev rtckit/react-redlock

Tests

To run the test suite, clone this repository and then install dependencies via Composer:

composer install

Then, go to the project root and run:

php -d memory_limit=-1 ./vendor/bin/phpunit -c ./etc/phpunit.xml.dist

Static Analysis

In order to ensure high code quality, Redlock uses PHPStan and Psalm:

php -d memory_limit=-1 ./vendor/bin/phpstan analyse -c ./etc/phpstan.neon -n -vvv --ansi --level=max src
php -d memory_limit=-1 ./vendor/bin/psalm --config=./etc/psalm.xml --show-info=true

License

MIT, see LICENSE file.

Acknowledgments

• antirez - Original blog post
• ReactPHP Project
• clue/reactphp-redis - Async Redis client implementation

Contributing

Bug reports (and small patches) can be submitted via the issue tracker. Forking the repository and submitting a Pull Request is preferred for substantial patches.