3 * Version of LockManager based on using memcached servers.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
21 * @ingroup LockManager
25 * Manage locks using memcached servers.
27 * Version of LockManager based on using memcached servers.
28 * This is meant for multi-wiki systems that may share files.
29 * All locks are non-blocking, which avoids deadlocks.
31 * All lock requests for a resource, identified by a hash string, will map
32 * to one bucket. Each bucket maps to one or several peer servers, each running memcached.
33 * A majority of peers must agree for a lock to be acquired.
35 * @ingroup LockManager
38 class MemcLockManager
extends QuorumLockManager
{
39 /** @var Array Mapping of lock types to the type actually used */
40 protected $lockTypeMap = array(
41 self
::LOCK_SH
=> self
::LOCK_SH
,
42 self
::LOCK_UW
=> self
::LOCK_SH
,
43 self
::LOCK_EX
=> self
::LOCK_EX
46 /** @var Array Map server names to MemcachedBagOStuff objects */
47 protected $bagOStuffs = array();
49 protected $serversUp = array(); // (server name => bool)
51 protected $lockExpiry; // integer; maximum time locks can be held
52 protected $session = ''; // string; random SHA-1 UUID
55 * Construct a new instance from configuration.
57 * $config paramaters include:
58 * - lockServers : Associative array of server names to "<IP>:<port>" strings.
59 * - srvsByBucket : Array of 1-16 consecutive integer keys, starting from 0,
60 * each having an odd-numbered list of server names (peers) as values.
61 * - memcConfig : Configuration array for ObjectCache::newFromParams. [optional]
62 * If set, this must use one of the memcached classes.
64 * @param array $config
67 public function __construct( array $config ) {
68 parent
::__construct( $config );
70 // Sanitize srvsByBucket config to prevent PHP errors
71 $this->srvsByBucket
= array_filter( $config['srvsByBucket'], 'is_array' );
72 $this->srvsByBucket
= array_values( $this->srvsByBucket
); // consecutive
74 $memcConfig = isset( $config['memcConfig'] )
75 ?
$config['memcConfig']
76 : array( 'class' => 'MemcachedPhpBagOStuff' );
78 foreach ( $config['lockServers'] as $name => $address ) {
79 $params = array( 'servers' => array( $address ) ) +
$memcConfig;
80 $cache = ObjectCache
::newFromParams( $params );
81 if ( $cache instanceof MemcachedBagOStuff
) {
82 $this->bagOStuffs
[$name] = $cache;
84 throw new MWException(
85 'Only MemcachedBagOStuff classes are supported by MemcLockManager.' );
89 $met = ini_get( 'max_execution_time' ); // this is 0 in CLI mode
90 $this->lockExpiry
= $met ?
2*(int)$met : 2*3600;
92 $this->session
= wfRandomString( 32 );
96 * @see QuorumLockManager::getLocksOnServer()
99 protected function getLocksOnServer( $lockSrv, array $paths, $type ) {
100 $status = Status
::newGood();
102 $memc = $this->getCache( $lockSrv );
103 $keys = array_map( array( $this, 'recordKeyForPath' ), $paths ); // lock records
105 // Lock all of the active lock record keys...
106 if ( !$this->acquireMutexes( $memc, $keys ) ) {
107 foreach ( $paths as $path ) {
108 $status->fatal( 'lockmanager-fail-acquirelock', $path );
113 // Fetch all the existing lock records...
114 $lockRecords = $memc->getMulti( $keys );
117 // Check if the requested locks conflict with existing ones...
118 foreach ( $paths as $path ) {
119 $locksKey = $this->recordKeyForPath( $path );
120 $locksHeld = isset( $lockRecords[$locksKey] )
121 ?
$lockRecords[$locksKey]
122 : array( self
::LOCK_SH
=> array(), self
::LOCK_EX
=> array() ); // init
123 foreach ( $locksHeld[self
::LOCK_EX
] as $session => $expiry ) {
124 if ( $expiry < $now ) { // stale?
125 unset( $locksHeld[self
::LOCK_EX
][$session] );
126 } elseif ( $session !== $this->session
) {
127 $status->fatal( 'lockmanager-fail-acquirelock', $path );
130 if ( $type === self
::LOCK_EX
) {
131 foreach ( $locksHeld[self
::LOCK_SH
] as $session => $expiry ) {
132 if ( $expiry < $now ) { // stale?
133 unset( $locksHeld[self
::LOCK_SH
][$session] );
134 } elseif ( $session !== $this->session
) {
135 $status->fatal( 'lockmanager-fail-acquirelock', $path );
139 if ( $status->isOK() ) {
140 // Register the session in the lock record array
141 $locksHeld[$type][$this->session
] = $now +
$this->lockExpiry
;
142 // We will update this record if none of the other locks conflict
143 $lockRecords[$locksKey] = $locksHeld;
147 // If there were no lock conflicts, update all the lock records...
148 if ( $status->isOK() ) {
149 foreach ( $lockRecords as $locksKey => $locksHeld ) {
150 $memc->set( $locksKey, $locksHeld );
151 wfDebug( __METHOD__
. ": acquired lock on key $locksKey.\n" );
155 // Unlock all of the active lock record keys...
156 $this->releaseMutexes( $memc, $keys );
162 * @see QuorumLockManager::freeLocksOnServer()
165 protected function freeLocksOnServer( $lockSrv, array $paths, $type ) {
166 $status = Status
::newGood();
168 $memc = $this->getCache( $lockSrv );
169 $keys = array_map( array( $this, 'recordKeyForPath' ), $paths ); // lock records
171 // Lock all of the active lock record keys...
172 if ( !$this->acquireMutexes( $memc, $keys ) ) {
173 foreach ( $paths as $path ) {
174 $status->fatal( 'lockmanager-fail-releaselock', $path );
179 // Fetch all the existing lock records...
180 $lockRecords = $memc->getMulti( $keys );
182 // Remove the requested locks from all records...
183 foreach ( $paths as $path ) {
184 $locksKey = $this->recordKeyForPath( $path ); // lock record
185 if ( !isset( $lockRecords[$locksKey] ) ) {
186 continue; // nothing to do
188 $locksHeld = $lockRecords[$locksKey];
189 if ( is_array( $locksHeld ) && isset( $locksHeld[$type] ) ) {
190 unset( $locksHeld[$type][$this->session
] );
191 $ok = $memc->set( $locksKey, $locksHeld );
196 $status->fatal( 'lockmanager-fail-releaselock', $path );
198 wfDebug( __METHOD__
. ": released lock on key $locksKey.\n" );
201 // Unlock all of the active lock record keys...
202 $this->releaseMutexes( $memc, $keys );
208 * @see QuorumLockManager::releaseAllLocks()
211 protected function releaseAllLocks() {
212 return Status
::newGood(); // not supported
216 * @see QuorumLockManager::isServerUp()
219 protected function isServerUp( $lockSrv ) {
220 return (bool)$this->getCache( $lockSrv );
224 * Get the MemcachedBagOStuff object for a $lockSrv
226 * @param string $lockSrv Server name
227 * @return MemcachedBagOStuff|null
229 protected function getCache( $lockSrv ) {
231 if ( isset( $this->bagOStuffs
[$lockSrv] ) ) {
232 $memc = $this->bagOStuffs
[$lockSrv];
233 if ( !isset( $this->serversUp
[$lockSrv] ) ) {
234 $this->serversUp
[$lockSrv] = $memc->set( 'MemcLockManager:ping', 1, 1 );
235 if ( !$this->serversUp
[$lockSrv] ) {
236 trigger_error( __METHOD__
. ": Could not contact $lockSrv.", E_USER_WARNING
);
239 if ( !$this->serversUp
[$lockSrv] ) {
240 return null; // server appears to be down
247 * @param $path string
250 protected function recordKeyForPath( $path ) {
251 return implode( ':', array( __CLASS__
, 'locks', $this->sha1Base36Absolute( $path ) ) );
255 * @param $memc MemcachedBagOStuff
256 * @param array $keys List of keys to acquire
259 protected function acquireMutexes( MemcachedBagOStuff
$memc, array $keys ) {
260 $lockedKeys = array();
262 // Acquire the keys in lexicographical order, to avoid deadlock problems.
263 // If P1 is waiting to acquire a key P2 has, P2 can't also be waiting for a key P1 has.
266 // Try to quickly loop to acquire the keys, but back off after a few rounds.
267 // This reduces memcached spam, especially in the rare case where a server acquires
268 // some lock keys and dies without releasing them. Lock keys expire after a few minutes.
270 $start = microtime( true );
272 if ( ( ++
$rounds %
4 ) == 0 ) {
273 usleep( 1000*50 ); // 50 ms
275 foreach ( array_diff( $keys, $lockedKeys ) as $key ) {
276 if ( $memc->add( "$key:mutex", 1, 180 ) ) { // lock record
277 $lockedKeys[] = $key;
279 continue; // acquire in order
282 } while ( count( $lockedKeys ) < count( $keys ) && ( microtime( true ) - $start ) <= 6 );
284 if ( count( $lockedKeys ) != count( $keys ) ) {
285 $this->releaseMutexes( $lockedKeys ); // failed; release what was locked
293 * @param $memc MemcachedBagOStuff
294 * @param array $keys List of acquired keys
297 protected function releaseMutexes( MemcachedBagOStuff
$memc, array $keys ) {
298 foreach ( $keys as $key ) {
299 $memc->delete( "$key:mutex" );
304 * Make sure remaining locks get cleared for sanity
306 function __destruct() {
307 while ( count( $this->locksHeld
) ) {
308 foreach ( $this->locksHeld
as $path => $locks ) {
309 $this->doUnlock( array( $path ), self
::LOCK_EX
);
310 $this->doUnlock( array( $path ), self
::LOCK_SH
);