rtckit/react-redlock

Asynchronous distributed locks with Redis and ReactPHP

1.0.0 2020-11-20 21:46 UTC

This package is auto-updated.

Last update: 2021-03-23 17:10:52 UTC


README

Asynchronous Redlock algorithm implementation for PHP

Build Status Latest Stable Version Test Coverage Maintainability License

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 your process's event loop as well as to a Redis client object instance, e.g.

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

/* Instantiate our lock custodian */
$custodian = new \RTCKit\React\Redlock\Custodian($loop, $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

Static Analysis

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

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

License

MIT, see LICENSE file.

Acknowledgments

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.