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
53 protected $wikiId = ''; // string
56 * Construct a new instance from configuration.
58 * $config paramaters include:
59 * 'lockServers' : Associative array of server names to <IP>:<port> strings.
60 * 'srvsByBucket' : Array of 1-16 consecutive integer keys, starting from 0,
61 * each having an odd-numbered list of server names (peers) as values.
62 * 'memcConfig' : Configuration array for ObjectCache::newFromParams. [optional]
63 * If set, this must use one of the memcached classes.
64 * 'wikiId' : Wiki ID string that all resources are relative to. [optional]
66 * @param Array $config
68 public function __construct( array $config ) {
69 parent
::__construct( $config );
71 // Sanitize srvsByBucket config to prevent PHP errors
72 $this->srvsByBucket
= array_filter( $config['srvsByBucket'], 'is_array' );
73 $this->srvsByBucket
= array_values( $this->srvsByBucket
); // consecutive
75 $memcConfig = isset( $config['memcConfig'] )
76 ?
$config['memcConfig']
77 : array( 'class' => 'MemcachedPhpBagOStuff' );
79 foreach ( $config['lockServers'] as $name => $address ) {
80 $params = array( 'servers' => array( $address ) ) +
$memcConfig;
81 $cache = ObjectCache
::newFromParams( $params );
82 if ( $cache instanceof MemcachedBagOStuff
) {
83 $this->bagOStuffs
[$name] = $cache;
85 throw new MWException(
86 'Only MemcachedBagOStuff classes are supported by MemcLockManager.' );
90 $this->wikiId
= isset( $config['wikiId'] ) ?
$config['wikiId'] : wfWikiID();
92 $met = ini_get( 'max_execution_time' ); // this is 0 in CLI mode
93 $this->lockExpiry
= $met ?
2*(int)$met : 2*3600;
95 $this->session
= wfRandomString( 31 );
99 * @see QuorumLockManager::getLocksOnServer()
102 protected function getLocksOnServer( $lockSrv, array $paths, $type ) {
103 $status = Status
::newGood();
105 $memc = $this->getCache( $lockSrv );
106 $keys = array_map( array( $this, 'recordKeyForPath' ), $paths ); // lock records
108 // Lock all of the active lock record keys...
109 if ( !$this->acquireMutexes( $memc, $keys ) ) {
110 foreach ( $paths as $path ) {
111 $status->fatal( 'lockmanager-fail-acquirelock', $path );
116 // Fetch all the existing lock records...
117 $lockRecords = $memc->getMulti( $keys );
120 // Check if the requested locks conflict with existing ones...
121 foreach ( $paths as $path ) {
122 $locksKey = $this->recordKeyForPath( $path );
123 $locksHeld = isset( $lockRecords[$locksKey] )
124 ?
$lockRecords[$locksKey]
125 : array( self
::LOCK_SH
=> array(), self
::LOCK_EX
=> array() ); // init
126 foreach ( $locksHeld[self
::LOCK_EX
] as $session => $expiry ) {
127 if ( $expiry < $now ) { // stale?
128 unset( $locksHeld[self
::LOCK_EX
][$session] );
129 } elseif ( $session !== $this->session
) {
130 $status->fatal( 'lockmanager-fail-acquirelock', $path );
133 if ( $type === self
::LOCK_EX
) {
134 foreach ( $locksHeld[self
::LOCK_SH
] as $session => $expiry ) {
135 if ( $expiry < $now ) { // stale?
136 unset( $locksHeld[self
::LOCK_SH
][$session] );
137 } elseif ( $session !== $this->session
) {
138 $status->fatal( 'lockmanager-fail-acquirelock', $path );
142 if ( $status->isOK() ) {
143 // Register the session in the lock record array
144 $locksHeld[$type][$this->session
] = $now +
$this->lockExpiry
;
145 // We will update this record if none of the other locks conflict
146 $lockRecords[$locksKey] = $locksHeld;
150 // If there were no lock conflicts, update all the lock records...
151 if ( $status->isOK() ) {
152 foreach ( $lockRecords as $locksKey => $locksHeld ) {
153 $memc->set( $locksKey, $locksHeld );
154 wfDebug( __METHOD__
. ": acquired lock on key $locksKey.\n" );
158 // Unlock all of the active lock record keys...
159 $this->releaseMutexes( $memc, $keys );
165 * @see QuorumLockManager::freeLocksOnServer()
168 protected function freeLocksOnServer( $lockSrv, array $paths, $type ) {
169 $status = Status
::newGood();
171 $memc = $this->getCache( $lockSrv );
172 $keys = array_map( array( $this, 'recordKeyForPath' ), $paths ); // lock records
174 // Lock all of the active lock record keys...
175 if ( !$this->acquireMutexes( $memc, $keys ) ) {
176 foreach ( $paths as $path ) {
177 $status->fatal( 'lockmanager-fail-releaselock', $path );
182 // Fetch all the existing lock records...
183 $lockRecords = $memc->getMulti( $keys );
185 // Remove the requested locks from all records...
186 foreach ( $paths as $path ) {
187 $locksKey = $this->recordKeyForPath( $path ); // lock record
188 if ( !isset( $lockRecords[$locksKey] ) ) {
189 continue; // nothing to do
191 $locksHeld = $lockRecords[$locksKey];
192 if ( is_array( $locksHeld ) && isset( $locksHeld[$type] ) ) {
193 unset( $locksHeld[$type][$this->session
] );
194 $ok = $memc->set( $locksKey, $locksHeld );
199 $status->fatal( 'lockmanager-fail-releaselock', $path );
201 wfDebug( __METHOD__
. ": released lock on key $locksKey.\n" );
204 // Unlock all of the active lock record keys...
205 $this->releaseMutexes( $memc, $keys );
211 * @see QuorumLockManager::releaseAllLocks()
214 protected function releaseAllLocks() {
215 return Status
::newGood(); // not supported
219 * @see QuorumLockManager::isServerUp()
222 protected function isServerUp( $lockSrv ) {
223 return (bool)$this->getCache( $lockSrv );
227 * Get the MemcachedBagOStuff object for a $lockSrv
229 * @param $lockSrv string Server name
230 * @return MemcachedBagOStuff|null
232 protected function getCache( $lockSrv ) {
234 if ( isset( $this->bagOStuffs
[$lockSrv] ) ) {
235 $memc = $this->bagOStuffs
[$lockSrv];
236 if ( !isset( $this->serversUp
[$lockSrv] ) ) {
237 $this->serversUp
[$lockSrv] = $memc->set( 'MemcLockManager:ping', 1, 1 );
238 if ( !$this->serversUp
[$lockSrv] ) {
239 trigger_error( __METHOD__
. ": Could not contact $lockSrv.", E_USER_WARNING
);
242 if ( !$this->serversUp
[$lockSrv] ) {
243 return null; // server appears to be down
250 * @param $path string
253 protected function recordKeyForPath( $path ) {
254 $hash = LockManager
::sha1Base36( $path );
255 list( $db, $prefix ) = wfSplitWikiID( $this->wikiId
);
256 return wfForeignMemcKey( $db, $prefix, __CLASS__
, 'locks', $hash );
260 * @param $memc MemcachedBagOStuff
261 * @param $keys Array List of keys to acquire
264 protected function acquireMutexes( MemcachedBagOStuff
$memc, array $keys ) {
265 $lockedKeys = array();
267 $start = microtime( true );
269 foreach ( array_diff( $keys, $lockedKeys ) as $key ) {
270 if ( $memc->add( "$key:mutex", 1, 180 ) ) { // lock record
271 $lockedKeys[] = $key;
274 } while ( count( $lockedKeys ) < count( $keys ) && ( microtime( true ) - $start ) <= 6 );
276 if ( count( $lockedKeys ) != count( $keys ) ) {
277 $this->releaseMutexes( $lockedKeys ); // failed; release what was locked
285 * @param $memc MemcachedBagOStuff
286 * @param $keys Array List of acquired keys
289 protected function releaseMutexes( MemcachedBagOStuff
$memc, array $keys ) {
290 foreach ( $keys as $key ) {
291 $memc->delete( "$key:mutex" );
296 * Make sure remaining locks get cleared for sanity
298 function __destruct() {
299 while ( count( $this->locksHeld
) ) {
300 foreach ( $this->locksHeld
as $path => $locks ) {
301 $this->doUnlock( array( $path ), self
::LOCK_EX
);
302 $this->doUnlock( array( $path ), self
::LOCK_SH
);