Commit 421e2eb9 by resurtm

Mutex extension docblocks and several minor fixes.

parent dd48e8a7
<?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
namespace yii\mutex;
use Yii;
use yii\base\Component;
/**
* @author resurtm <resurtm@gmail.com>
* @since 2.0
*/
abstract class Mutex extends Component
{
/**
* @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
*/
public $autoRelease = true;
/**
* @var string[] names of the locks acquired in the current PHP process.
*/
private $_locks = array();
/**
* Initializes the mutex component.
*/
public function init()
{
if ($this->autoRelease) {
......@@ -20,7 +38,7 @@ abstract class Mutex extends Component
}
/**
* NEVER CALL THIS METHOD UNDER ANY CIRCUMSTANCES
* Never call this method directly under any circumstances. This method is intended for internal use only.
*/
public function shutdownFunction()
{
......@@ -29,6 +47,12 @@ abstract class Mutex extends Component
}
}
/**
* @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.
* @return boolean lock acquiring result.
*/
public function acquireLock($name, $timeout = 0)
{
if ($this->acquire($name, $timeout)) {
......@@ -39,6 +63,11 @@ abstract class Mutex extends Component
}
}
/**
* Release acquired lock.
* @param string $name of the lock to be released. This lock must be already created.
* @return boolean lock release result.
*/
public function releaseLock($name)
{
if ($this->release($name)) {
......@@ -49,6 +78,12 @@ abstract class Mutex extends Component
}
}
/**
* Checks whether named lock was already opened.
* @param string $name of the lock to be checked. This lock must be already created.
* @return boolean|null whether named lock was already opened. Returns `null` value in case concrete
* mutex implementation does not support this operation.
*/
public function getIsLockAcquired($name)
{
if (in_array($name, $this->_locks)) {
......@@ -58,19 +93,48 @@ abstract class Mutex extends Component
}
}
/**
* Checks whether given lock is local. In other words local lock means that it was opened in the current
* PHP process.
* @param string $name of the lock to be checked. This lock must be already created.
* @return boolean whether named lock was locally acquired.
*/
public function getIsLockLocal($name)
{
return in_array($name, $this->_locks);
}
/**
* This method should be extended by concrete mutex implementations. Acquires lock by given name.
* @param string $name of the lock to be acquired.
* @param integer $timeout to wait for lock to become released.
* @return boolean acquiring result.
*/
abstract protected function acquire($name, $timeout = 0);
/**
* This method should be extended by concrete mutex implementations. Releases lock by given name.
* @param string $name of the lock to be released.
* @return boolean release result.
*/
abstract protected function release($name);
/**
* This method may optionally be extended by concrete mutex implementations. Checks whether lock has been
* already acquired by given name.
* @param string $name of the lock to be released.
* @return null|boolean whether lock has been already acquired. Returns `null` in case this feature
* is not supported by concrete mutex implementation.
*/
protected function getIsAcquired($name)
{
return null;
}
/**
* This method should be extended by concrete mutex implementations. Returns whether current mutex
* implementation can be used in a distributed environment.
* @return boolean whether current mutex implementation can be used in a distributed environment.
*/
abstract public function getIsDistributed();
}
<?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
namespace yii\mutex\db;
......@@ -6,22 +11,39 @@ use Yii;
use yii\db\Connection;
use yii\base\InvalidConfigException;
/**
* @author resurtm <resurtm@gmail.com>
* @since 2.0
*/
abstract class Mutex extends \yii\mutex\Mutex
{
/**
* @var string|Connection
* @var Connection|string the DB connection object or the application component ID of the DB connection.
* After the Mutex object is created, if you want to change this property, you should only assign
* it with a DB connection object.
*/
public $db = 'db';
/**
* Initializes generic database table based mutex implementation.
* @throws InvalidConfigException if [[db]] is invalid.
*/
public function init()
{
parent::init();
if (is_string($this->db)) {
$this->db = Yii::$app->getComponent($this->db);
}
if (!$this->db instanceof Connection) {
throw new InvalidConfigException('');
throw new InvalidConfigException('Mutex::db must be either a DB connection instance or the application component ID of a DB connection.');
}
}
/**
* This method should be extended by concrete mutex implementations. Returns whether current mutex
* implementation can be used in a distributed environment.
* @return boolean whether current mutex implementation can be used in a distributed environment.
*/
public function getIsDistributed()
{
return true;
......
<?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
namespace yii\mutex\db\mssql;
use Yii;
use yii\base\InvalidConfigException;
/**
* @author resurtm <resurtm@gmail.com>
* @since 2.0
*/
class Mutex extends \yii\mutex\db\Mutex
{
/**
* Initializes Microsoft SQL Server specific mutex component implementation.
* @throws InvalidConfigException if [[db]] is not Microsoft SQL Server connection.
*/
public function init()
{
parent::init();
......@@ -16,13 +29,28 @@ class Mutex extends \yii\mutex\db\Mutex
}
}
/**
* This method should be extended by concrete mutex implementations. Acquires lock by given name.
* @param string $name of the lock to be acquired.
* @param integer $timeout to wait for lock to become released.
* @return boolean acquiring result.
* @throws \BadMethodCallException
* @see http://msdn.microsoft.com/en-us/library/ms189823.aspx
*/
protected function acquire($name, $timeout = 0)
{
// http://msdn.microsoft.com/en-us/library/ms189823.aspx
throw new \BadMethodCallException('Not implemented yet.');
}
/**
* This method should be extended by concrete mutex implementations. Releases lock by given name.
* @param string $name of the lock to be released.
* @return boolean release result.
* @throws \BadMethodCallException
* @see http://msdn.microsoft.com/en-us/library/ms178602.aspx
*/
protected function release($name)
{
// http://msdn.microsoft.com/en-us/library/ms178602.aspx
throw new \BadMethodCallException('Not implemented yet.');
}
}
<?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
namespace yii\mutex\db\mysql;
use Yii;
use yii\base\InvalidConfigException;
/**
* @author resurtm <resurtm@gmail.com>
* @since 2.0
*/
class Mutex extends \yii\mutex\db\Mutex
{
/**
* Initializes MySQL specific mutex component implementation.
* @throws InvalidConfigException if [[db]] is not MySQL connection.
*/
public function init()
{
parent::init();
......@@ -15,6 +28,13 @@ class Mutex extends \yii\mutex\db\Mutex
}
}
/**
* This method should be extended by concrete mutex implementations. Acquires lock by given name.
* @param string $name of the lock to be acquired.
* @param integer $timeout to wait for lock to become released.
* @return boolean acquiring result.
* @see http://dev.mysql.com/doc/refman/5.0/en/miscellaneous-functions.html#function_get-lock
*/
protected function acquire($name, $timeout = 0)
{
return (boolean)$this->db
......@@ -22,6 +42,12 @@ class Mutex extends \yii\mutex\db\Mutex
->queryScalar();
}
/**
* This method should be extended by concrete mutex implementations. Releases lock by given name.
* @param string $name of the lock to be released.
* @return boolean release result.
* @see http://dev.mysql.com/doc/refman/5.0/en/miscellaneous-functions.html#function_release-lock
*/
protected function release($name)
{
return (boolean)$this->db
......@@ -29,6 +55,14 @@ class Mutex extends \yii\mutex\db\Mutex
->queryScalar();
}
/**
* This method may optionally be extended by concrete mutex implementations. Checks whether lock has been
* already acquired by given name.
* @param string $name of the lock to be released.
* @return null|boolean whether lock has been already acquired. Returns `null` in case this feature
* is not supported by concrete mutex implementation.
* @see http://dev.mysql.com/doc/refman/5.0/en/miscellaneous-functions.html#function_is-free-lock
*/
protected function getIsAcquired($name)
{
return (boolean)$this->db
......
<?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
namespace yii\mutex\unix;
use Yii;
use yii\base\InvalidConfigException;
/**
* @author resurtm <resurtm@gmail.com>
* @since 2.0
*/
class Mutex extends \yii\mutex\Mutex
{
/**
* @var resource[] stores all opened lock files. Keys are lock names and values are file handles.
*/
private $_files = array();
/**
* Initializes mutex component implementation dedicated for UNIX, GNU/Linux, Mac OS X, and other UNIX-like
* operating systems.
* @throws InvalidConfigException
*/
public function init()
{
if (stripos(php_uname('s'), 'win') === 0) {
......@@ -17,6 +34,12 @@ class Mutex extends \yii\mutex\Mutex
}
}
/**
* This method should be extended by concrete mutex implementations. Acquires lock by given name.
* @param string $name of the lock to be acquired.
* @param integer $timeout to wait for lock to become released.
* @return boolean acquiring result.
*/
protected function acquire($name, $timeout = 0)
{
$file = fopen(Yii::$app->getRuntimePath() . '/mutex.' . md5($name) . '.lock', 'w+');
......@@ -36,6 +59,11 @@ class Mutex extends \yii\mutex\Mutex
return true;
}
/**
* This method should be extended by concrete mutex implementations. Releases lock by given name.
* @param string $name of the lock to be released.
* @return boolean release result.
*/
protected function release($name)
{
if (!isset($this->_files[$name]) || !flock($this->_files[$name], LOCK_UN)) {
......@@ -47,11 +75,23 @@ class Mutex extends \yii\mutex\Mutex
}
}
/**
* This method may optionally be extended by concrete mutex implementations. Checks whether lock has been
* already acquired by given name.
* @param string $name of the lock to be released.
* @return null|boolean whether lock has been already acquired. Returns `null` in case this feature
* is not supported by concrete mutex implementation.
*/
protected function getIsAcquired($name)
{
return false;
}
/**
* This method should be extended by concrete mutex implementations. Returns whether current mutex
* implementation can be used in a distributed environment.
* @return boolean whether current mutex implementation can be used in a distributed environment.
*/
public function getIsDistributed()
{
return false;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment