yiisoft / mutex

Mutex lock implementation

Yii Mutex

This package provides mutex implementation and allows mutual execution of concurrent processes in order to prevent "race conditions".

This is achieved by using a "lock" mechanism. Each possibly concurrent processes cooperates by acquiring a lock before accessing the corresponding data.

Requirements

• PHP 7.4 or higher.

Installation

The package could be installed with Composer:

composer require yiisoft/mutex

General usage

There are multiple ways you can use the package. You can execute a callback in a synchronized mode i.e. only a single instance of the callback is executed at the same time:

/** @var \Yiisoft\Mutex\Synchronizer $synchronizer */
$newCount = $synchronizer->execute('critical', function () {
    return $counter->increase();
}, 10);

Another way is to manually open and close mutex:

/** @var \Yiisoft\Mutex\SimpleMutex $simpleMutex */
if (!$simpleMutex->acquire('critical', 10)) {
    throw new \Yiisoft\Mutex\Exception\MutexLockedException('Unable to acquire the "critical" mutex.');
}
$newCount = $counter->increase();
$simpleMutex->release('critical');

It could be done on lower level:

/** @var \Yiisoft\Mutex\MutexFactoryInterface $mutexFactory */
$mutex = $mutexFactory->createAndAcquire('critical', 10);
$newCount = $counter->increase();
$mutex->release();

And if you want even more control, you can acquire mutex manually:

/** @var \Yiisoft\Mutex\MutexFactoryInterface $mutexFactory */
$mutex = $mutexFactory->create('critical');
if (!$mutex->acquire(10)) {
    throw new \Yiisoft\Mutex\Exception\MutexLockedException('Unable to acquire the "critical" mutex.');
}
$newCount = $counter->increase();
$mutex->release();

Mutex drivers

There are some mutex drivers available as separate packages:

• File
• PDO MySQL
• PDO Oracle
• PDO Postgres
• Redis

If you want to provide your own driver, you need to implement MutexFactoryInterface and MutexInterface. There is ready to extend Mutex, MutexFactory and a RetryAcquireTrait that contains retryAcquire() method implementing the "wait for a lock for a certain time" functionality.

When implementing your own drivers, you need to take care of automatic unlocking. For example using a destructor:

public function __destruct()
{
    $this->release();
}

and shutdown function:

public function __construct()
{
    register_shutdown_function(function () {
        $this->release();
    });
}

Note that you should not call the exit() or die() functions in the destructor or shutdown function. Since calling these functions in the destructor and shutdown function will prevent all subsequent completion functions from executing.

Documentation

• Internals

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

License

The Yii Mutex is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Follow updates

mutex's Issues

update irc link

What steps will reproduce the problem?

What is the expected result?

What do you get instead?

Additional info

Q	A
Version	1.0.?
PHP version
Operating system

Release mutex anyway despite autocommit option

Now every mutex driver must release mutex manually if option autocommit set on true.

This decision not only adds difficulties in implementing the new driver, but also does not eliminate problems when managing the mutex.

Imagine that you have some acquired mutex:

$fileMutexFactory = new FileMutexFactory(__DIR__ . '/var/mutexes', false);

$mutex = $this->mutexes->create('some_mutex');

// some actions

$this->doSomething(); // But there will be exception

$mutex->release();

Such mutex will not be released because autocommit turn off.

I think, mutex releaser must be required and do not rely on the user's actions. Every mutex implementation must release mutex anyway in they destructor's.

The following code will guarantees that the mutex will be released anyway on the script shutdown, and it also does not require drivers to implement it themselves.

abstract class Mutex
{
       /**
     * Acquires a lock.
     *
     * @param int $timeout Time (in seconds) to wait for lock to be released. Defaults to zero meaning that method
     * will return false immediately in case lock was already acquired.
     */
    abstract public function acquire(int $timeout = 0): bool;

    /**
     * Releases a lock.
     */
    abstract public function release(): void;

    abstract public function released(): bool;

    final public function __destruct()
    {
       if (!$this->released()) {
           $this->release();
       }
    }
}

After that, we can delete the call to the register_shutdown_function function and the `autocommit' option.

Trim git history

Split specific drivers into their own packages

See https://forum.yiiframework.com/t/additional-packages-for-specific-drivers-storages/125718

• mutex-file
• mutex-db-oracle
• mutex-db-mysql
• mutex-db-pgsql
• mutex-db-redis

Allow microseconds (float?) as timeout

Good day. It not nessesery, but how about add microseconds as timeout - as additional argument or change current type to float? For example (my case) it can be used for some external API with limited requests per second. Thanks

The exception thrown, when the mutex acquire fails, is too generic

When the Yiisoft\Mutex\MutexFactory::createAndAcquire() method fails to acquire lock the \RuntimeException is thrown.
Lets say you have code:

 try {
     $this->synchronizer->execute(
         'myMutex',
         function () {
             // do some synchronized logic
         },
         30
    );
} catch (\RuntimeException $ex) {
    // handle exception
}

The issue with this code is that \RuntimeException is too generic and can easily be thrown from inside the synchronized logic too. You can't easily setup the try-catch block to catch only exception caused by failed attempt to acquire mutex.
The use case when you would need to do that might be when you want to show some output to user when the mutex is not acquired. For example something like "The work is in progress. Please try again later."

It would be much easier to do if the exception thrown is something like this

class MutexException extends RuntimeException

Handling exception while mutex is acquired implicitly

What steps will reproduce the problem?

If exception will be thrown from callback here, mutex will not be released and nobody else will be able to acquire it.

What is the expected result?

Expected exception handling.

$mutex = $this->mutexFactory->createAndAcquire($name, $timeout);

try {
     /** @var mixed */
     return $callback();
} catch (\Throwable $throwable) {
     throw $throwable;
} finally {
   $mutex->release();
}

Additional info

Q	A
Version	1.0.?
PHP version	any
Operating system	doesn't matter