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 to one
32 * 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 = [
41 self
::LOCK_SH
=> self
::LOCK_SH
,
42 self
::LOCK_UW
=> self
::LOCK_SH
,
43 self
::LOCK_EX
=> self
::LOCK_EX
46 /** @var MemcachedBagOStuff[] Map of (server name => MemcachedBagOStuff) */
47 protected $cacheServers = [];
48 /** @var HashBagOStuff Server status cache */
49 protected $statusCache;
52 * Construct a new instance from configuration.
54 * @param array $config Parameters include:
55 * - lockServers : Associative array of server names to "<IP>:<port>" strings.
56 * - srvsByBucket : Array of 1-16 consecutive integer keys, starting from 0,
57 * each having an odd-numbered list of server names (peers) as values.
58 * - memcConfig : Configuration array for MemcachedBagOStuff::construct() with an
59 * additional 'class' parameter specifying which MemcachedBagOStuff
60 * subclass to use. The server names will be injected. [optional]
63 public function __construct( array $config ) {
64 parent
::__construct( $config );
66 // Sanitize srvsByBucket config to prevent PHP errors
67 $this->srvsByBucket
= array_filter( $config['srvsByBucket'], 'is_array' );
68 $this->srvsByBucket
= array_values( $this->srvsByBucket
); // consecutive
70 $memcConfig = isset( $config['memcConfig'] ) ?
$config['memcConfig'] : [];
71 $memcConfig +
= [ 'class' => 'MemcachedPhpBagOStuff' ]; // default
73 $class = $memcConfig['class'];
74 if ( !is_subclass_of( $class, 'MemcachedBagOStuff' ) ) {
75 throw new InvalidArgumentException( "$class is not of type MemcachedBagOStuff." );
78 foreach ( $config['lockServers'] as $name => $address ) {
79 $params = [ 'servers' => [ $address ] ] +
$memcConfig;
80 $this->cacheServers
[$name] = new $class( $params );
83 $this->statusCache
= new HashBagOStuff();
86 protected function getLocksOnServer( $lockSrv, array $pathsByType ) {
87 $status = StatusValue
::newGood();
89 $memc = $this->getCache( $lockSrv );
90 // List of affected paths
91 $paths = call_user_func_array( 'array_merge', array_values( $pathsByType ) );
92 $paths = array_unique( $paths );
93 // List of affected lock record keys
94 $keys = array_map( [ $this, 'recordKeyForPath' ], $paths );
96 // Lock all of the active lock record keys...
97 if ( !$this->acquireMutexes( $memc, $keys ) ) {
98 foreach ( $paths as $path ) {
99 $status->fatal( 'lockmanager-fail-acquirelock', $path );
105 // Fetch all the existing lock records...
106 $lockRecords = $memc->getMulti( $keys );
109 // Check if the requested locks conflict with existing ones...
110 foreach ( $pathsByType as $type => $paths ) {
111 foreach ( $paths as $path ) {
112 $locksKey = $this->recordKeyForPath( $path );
113 $locksHeld = isset( $lockRecords[$locksKey] )
114 ? self
::sanitizeLockArray( $lockRecords[$locksKey] )
115 : self
::newLockArray(); // init
116 foreach ( $locksHeld[self
::LOCK_EX
] as $session => $expiry ) {
117 if ( $expiry < $now ) { // stale?
118 unset( $locksHeld[self
::LOCK_EX
][$session] );
119 } elseif ( $session !== $this->session
) {
120 $status->fatal( 'lockmanager-fail-acquirelock', $path );
123 if ( $type === self
::LOCK_EX
) {
124 foreach ( $locksHeld[self
::LOCK_SH
] as $session => $expiry ) {
125 if ( $expiry < $now ) { // stale?
126 unset( $locksHeld[self
::LOCK_SH
][$session] );
127 } elseif ( $session !== $this->session
) {
128 $status->fatal( 'lockmanager-fail-acquirelock', $path );
132 if ( $status->isOK() ) {
133 // Register the session in the lock record array
134 $locksHeld[$type][$this->session
] = $now +
$this->lockTTL
;
135 // We will update this record if none of the other locks conflict
136 $lockRecords[$locksKey] = $locksHeld;
141 // If there were no lock conflicts, update all the lock records...
142 if ( $status->isOK() ) {
143 foreach ( $paths as $path ) {
144 $locksKey = $this->recordKeyForPath( $path );
145 $locksHeld = $lockRecords[$locksKey];
146 $ok = $memc->set( $locksKey, $locksHeld, self
::MAX_LOCK_TTL
);
148 $status->fatal( 'lockmanager-fail-acquirelock', $path );
150 $this->logger
->debug( __METHOD__
. ": acquired lock on key $locksKey.\n" );
155 // Unlock all of the active lock record keys...
156 $this->releaseMutexes( $memc, $keys );
161 protected function freeLocksOnServer( $lockSrv, array $pathsByType ) {
162 $status = StatusValue
::newGood();
164 $memc = $this->getCache( $lockSrv );
165 // List of affected paths
166 $paths = call_user_func_array( 'array_merge', array_values( $pathsByType ) );
167 $paths = array_unique( $paths );
168 // List of affected lock record keys
169 $keys = array_map( [ $this, 'recordKeyForPath' ], $paths );
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 );
180 // Fetch all the existing lock records...
181 $lockRecords = $memc->getMulti( $keys );
183 // Remove the requested locks from all records...
184 foreach ( $pathsByType as $type => $paths ) {
185 foreach ( $paths as $path ) {
186 $locksKey = $this->recordKeyForPath( $path ); // lock record
187 if ( !isset( $lockRecords[$locksKey] ) ) {
188 $status->warning( 'lockmanager-fail-releaselock', $path );
189 continue; // nothing to do
191 $locksHeld = $this->sanitizeLockArray( $lockRecords[$locksKey] );
192 if ( isset( $locksHeld[$type][$this->session
] ) ) {
193 unset( $locksHeld[$type][$this->session
] ); // unregister this session
194 $lockRecords[$locksKey] = $locksHeld;
196 $status->warning( 'lockmanager-fail-releaselock', $path );
201 // Persist the new lock record values...
202 foreach ( $paths as $path ) {
203 $locksKey = $this->recordKeyForPath( $path );
204 if ( !isset( $lockRecords[$locksKey] ) ) {
205 continue; // nothing to do
207 $locksHeld = $lockRecords[$locksKey];
208 if ( $locksHeld === $this->newLockArray() ) {
209 $ok = $memc->delete( $locksKey );
211 $ok = $memc->set( $locksKey, $locksHeld, self
::MAX_LOCK_TTL
);
214 $this->logger
->debug( __METHOD__
. ": released lock on key $locksKey.\n" );
216 $status->fatal( 'lockmanager-fail-releaselock', $path );
220 // Unlock all of the active lock record keys...
221 $this->releaseMutexes( $memc, $keys );
227 * @see QuorumLockManager::releaseAllLocks()
228 * @return StatusValue
230 protected function releaseAllLocks() {
231 return StatusValue
::newGood(); // not supported
235 * @see QuorumLockManager::isServerUp()
236 * @param string $lockSrv
239 protected function isServerUp( $lockSrv ) {
240 return (bool)$this->getCache( $lockSrv );
244 * Get the MemcachedBagOStuff object for a $lockSrv
246 * @param string $lockSrv Server name
247 * @return MemcachedBagOStuff|null
249 protected function getCache( $lockSrv ) {
250 if ( !isset( $this->cacheServers
[$lockSrv] ) ) {
251 throw new InvalidArgumentException( "Invalid cache server '$lockSrv'." );
254 $online = $this->statusCache
->get( "online:$lockSrv" );
255 if ( $online === false ) {
256 $online = $this->cacheServers
[$lockSrv]->set( __CLASS__
. ':ping', 1, 1 );
257 if ( !$online ) { // server down?
258 $this->logger
->warning( __METHOD__
. ": Could not contact $lockSrv." );
260 $this->statusCache
->set( "online:$lockSrv", (int)$online, 30 );
263 return $online ?
$this->cacheServers
[$lockSrv] : null;
267 * @param string $path
270 protected function recordKeyForPath( $path ) {
271 return implode( ':', [ __CLASS__
, 'locks', $this->sha1Base36Absolute( $path ) ] );
275 * @return array An empty lock structure for a key
277 protected function newLockArray() {
278 return [ self
::LOCK_SH
=> [], self
::LOCK_EX
=> [] ];
283 * @return array An empty lock structure for a key
285 protected function sanitizeLockArray( $a ) {
286 if ( is_array( $a ) && isset( $a[self
::LOCK_EX
] ) && isset( $a[self
::LOCK_SH
] ) ) {
290 $this->logger
->error( __METHOD__
. ": reset invalid lock array." );
292 return $this->newLockArray();
296 * @param MemcachedBagOStuff $memc
297 * @param array $keys List of keys to acquire
300 protected function acquireMutexes( MemcachedBagOStuff
$memc, array $keys ) {
303 // Acquire the keys in lexicographical order, to avoid deadlock problems.
304 // If P1 is waiting to acquire a key P2 has, P2 can't also be waiting for a key P1 has.
307 // Try to quickly loop to acquire the keys, but back off after a few rounds.
308 // This reduces memcached spam, especially in the rare case where a server acquires
309 // some lock keys and dies without releasing them. Lock keys expire after a few minutes.
310 $loop = new WaitConditionLoop(
311 function () use ( $memc, $keys, &$lockedKeys ) {
312 foreach ( array_diff( $keys, $lockedKeys ) as $key ) {
313 if ( $memc->add( "$key:mutex", 1, 180 ) ) { // lock record
314 $lockedKeys[] = $key;
318 return array_diff( $keys, $lockedKeys )
319 ? WaitConditionLoop
::CONDITION_CONTINUE
326 if ( count( $lockedKeys ) != count( $keys ) ) {
327 $this->releaseMutexes( $memc, $lockedKeys ); // failed; release what was locked
335 * @param MemcachedBagOStuff $memc
336 * @param array $keys List of acquired keys
338 protected function releaseMutexes( MemcachedBagOStuff
$memc, array $keys ) {
339 foreach ( $keys as $key ) {
340 $memc->delete( "$key:mutex" );
345 * Make sure remaining locks get cleared for sanity
347 function __destruct() {
348 while ( count( $this->locksHeld
) ) {
349 foreach ( $this->locksHeld
as $path => $locks ) {
350 $this->doUnlock( [ $path ], self
::LOCK_EX
);
351 $this->doUnlock( [ $path ], self
::LOCK_SH
);