Mutex.php 3.41 KB
Newer Older
resurtm committed
1
<?php
2 3 4 5 6
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */
resurtm committed
7 8 9 10 11 12

namespace yii\mutex;

use Yii;
use yii\base\Component;

13
/**
14 15 16 17 18 19 20
 * Mutex component allows mutual execution of the concurrent processes, preventing "race conditions".
 * This is achieved by using "lock" mechanism. Each possibly concurrent thread cooperates by acquiring
 * the lock before accessing the corresponding data.
 *
 * Usage example:
 *
 * ```
21
 * if ($mutex->acquire($mutexName)) {
22 23 24 25 26 27 28 29
 *     // business logic execution
 * } else {
 *     // execution is blocked!
 * }
 * ```
 *
 * This class is a base one, which should be extended in order to implement actual lock mechanism.
 *
30 31 32
 * @author resurtm <resurtm@gmail.com>
 * @since 2.0
 */
resurtm committed
33 34
abstract class Mutex extends Component
{
35 36 37 38 39 40 41 42 43 44
    /**
     * @var boolean whether all locks acquired in this process (i.e. local locks) must be released automagically
     * before finishing script execution. Defaults to true. Setting this property to true means that all locks
     * acquire in this process must be released in any case (regardless any kind of errors or exceptions).
     */
    public $autoRelease = true;
    /**
     * @var string[] names of the locks acquired in the current PHP process.
     */
    private $_locks = [];
resurtm committed
45

46 47 48 49 50 51 52 53 54 55 56 57 58 59
    /**
     * Initializes the mutex component.
     */
    public function init()
    {
        if ($this->autoRelease) {
            $locks = &$this->_locks;
            register_shutdown_function(function () use (&$locks) {
                foreach ($locks as $lock) {
                    $this->release($lock);
                }
            });
        }
    }
resurtm committed
60

61 62
    /**
     * Acquires lock by given name.
63 64 65
     * @param string $name of the lock to be acquired. Must be unique.
     * @param integer $timeout to wait for lock to be released. Defaults to zero meaning that method will return
     * false immediately in case lock was already acquired.
66 67 68 69 70 71
     * @return boolean lock acquiring result.
     */
    public function acquire($name, $timeout = 0)
    {
        if ($this->acquireLock($name, $timeout)) {
            $this->_locks[] = $name;
resurtm committed
72

73 74 75 76 77
            return true;
        } else {
            return false;
        }
    }
resurtm committed
78

79 80
    /**
     * Release acquired lock. This method will return false in case named lock was not found.
81
     * @param string $name of the lock to be released. This lock must be already created.
82 83 84 85 86 87 88 89 90
     * @return boolean lock release result: false in case named lock was not found..
     */
    public function release($name)
    {
        if ($this->releaseLock($name)) {
            $index = array_search($name, $this->_locks);
            if ($index !== false) {
                unset($this->_locks[$index]);
            }
resurtm committed
91

92 93 94 95 96
            return true;
        } else {
            return false;
        }
    }
resurtm committed
97

98 99
    /**
     * This method should be extended by concrete mutex implementations. Acquires lock by given name.
100 101
     * @param string $name of the lock to be acquired.
     * @param integer $timeout to wait for lock to become released.
102 103 104 105 106 107
     * @return boolean acquiring result.
     */
    abstract protected function acquireLock($name, $timeout = 0);

    /**
     * This method should be extended by concrete mutex implementations. Releases lock by given name.
108
     * @param string $name of the lock to be released.
109 110 111
     * @return boolean release result.
     */
    abstract protected function releaseLock($name);
resurtm committed
112
}