README

Yii Mutex Library - Oracle PDO Driver

This library provides an Oracle mutex implementation for yiisoft/mutex.

Requirements

PHP 7.4 or higher.
PDO PHP extension.

Installation

The package could be installed with Composer:

composer require yiisoft/mutex-pdo-oracle

General usage

The package provides two classes implementing MutexInterface and MutexFactoryInterface from the yiisoft/mutex package:

use Yiisoft\Mutex\Oracle\OracleMutex;
use Yiisoft\Mutex\Oracle\OracleMutexFactory;

/**
 * @var \PDO $connection Configured for Oracle.
 */

$mutex = new OracleMutex(
    'mutex-name',
    $connection,
    OracleMutex::MODE_X, // Optional. Lock mode to be used. Default is `OracleMutex::MODE_X`.
    false, // Optional. Whether to release lock on commit. Default is `false`.
);

$mutexFactory = new OracleMutexFactory(
    $connection,
    OracleMutex::MODE_X, // Optional. Lock mode to be used. Default is `OracleMutex::MODE_X`.
    false, // Optional. Whether to release lock on commit. Default is `false`.
);

Read more about the "lock mode" and "release lock on commit" options in the Oracle documentation.

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:

$synchronizer = new \Yiisoft\Mutex\Synchronizer($mutexFactory);

$newCount = $synchronizer->execute('critical', function () {
    return $counter->increase();
}, 10);

Another way is to manually open and close mutex:

$simpleMutex = \Yiisoft\Mutex\SimpleMutex($mutexFactory);

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:

$mutex = $mutexFactory->createAndAcquire('critical', 10);
$newCount = $counter->increase();
$mutex->release();

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

$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();

The OracleMutex supports the "wait for a lock for a certain time" functionality. Using the withRetryDelay() method, you can override the number of milliseconds between each try until specified timeout times out:

$mutex = $mutex->withRetryDelay(100);

By default, it is 50 milliseconds - it means that we may try to acquire lock up to 20 times per second.

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 Library - Oracle PDO Driver is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

yiisoft / mutex-pdo-oracle

Maintainers

Details