3 * Simple version of LockManager based on using FS lock files.
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 * Simple version of LockManager based on using FS lock files.
26 * All locks are non-blocking, which avoids deadlocks.
28 * This should work fine for small sites running off one server.
29 * Do not use this with 'lockDirectory' set to an NFS mount unless the
30 * NFS client is at least version 2.6.12. Otherwise, the BSD flock()
31 * locks will be ignored; see http://nfs.sourceforge.net/#section_d.
33 * @ingroup LockManager
36 class FSLockManager
extends LockManager
{
37 /** @var array Mapping of lock types to the type actually used */
38 protected $lockTypeMap = [
39 self
::LOCK_SH
=> self
::LOCK_SH
,
40 self
::LOCK_UW
=> self
::LOCK_SH
,
41 self
::LOCK_EX
=> self
::LOCK_EX
44 /** @var string Global dir for all servers */
47 /** @var array Map of (locked key => lock file handle) */
48 protected $handles = [];
54 * Construct a new instance from configuration.
56 * @param array $config Includes:
57 * - lockDirectory : Directory containing the lock files
59 function __construct( array $config ) {
60 parent
::__construct( $config );
62 $this->lockDir
= $config['lockDirectory'];
63 $this->isWindows
= ( strtoupper( substr( PHP_OS
, 0, 3 ) ) === 'WIN' );
67 * @see LockManager::doLock()
72 protected function doLock( array $paths, $type ) {
73 $status = StatusValue
::newGood();
75 $lockedPaths = []; // files locked in this attempt
76 foreach ( $paths as $path ) {
77 $status->merge( $this->doSingleLock( $path, $type ) );
78 if ( $status->isOK() ) {
79 $lockedPaths[] = $path;
81 // Abort and unlock everything
82 $status->merge( $this->doUnlock( $lockedPaths, $type ) );
92 * @see LockManager::doUnlock()
97 protected function doUnlock( array $paths, $type ) {
98 $status = StatusValue
::newGood();
100 foreach ( $paths as $path ) {
101 $status->merge( $this->doSingleUnlock( $path, $type ) );
108 * Lock a single resource key
110 * @param string $path
112 * @return StatusValue
114 protected function doSingleLock( $path, $type ) {
115 $status = StatusValue
::newGood();
117 if ( isset( $this->locksHeld
[$path][$type] ) ) {
118 ++
$this->locksHeld
[$path][$type];
119 } elseif ( isset( $this->locksHeld
[$path][self
::LOCK_EX
] ) ) {
120 $this->locksHeld
[$path][$type] = 1;
122 if ( isset( $this->handles
[$path] ) ) {
123 $handle = $this->handles
[$path];
125 Wikimedia\
suppressWarnings();
126 $handle = fopen( $this->getLockPath( $path ), 'a+' );
127 if ( !$handle && !is_dir( $this->lockDir
) ) {
128 // Create the lock directory in case it is missing
129 if ( mkdir( $this->lockDir
, 0777, true ) ) {
130 $handle = fopen( $this->getLockPath( $path ), 'a+' ); // try again
132 $this->logger
->error( "Cannot create directory '{$this->lockDir}'." );
135 Wikimedia\restoreWarnings
();
138 // Either a shared or exclusive lock
139 $lock = ( $type == self
::LOCK_SH
) ? LOCK_SH
: LOCK_EX
;
140 if ( flock( $handle, $lock | LOCK_NB
) ) {
141 // Record this lock as active
142 $this->locksHeld
[$path][$type] = 1;
143 $this->handles
[$path] = $handle;
146 $status->fatal( 'lockmanager-fail-acquirelock', $path );
149 $status->fatal( 'lockmanager-fail-openlock', $path );
157 * Unlock a single resource key
159 * @param string $path
161 * @return StatusValue
163 protected function doSingleUnlock( $path, $type ) {
164 $status = StatusValue
::newGood();
166 if ( !isset( $this->locksHeld
[$path] ) ) {
167 $status->warning( 'lockmanager-notlocked', $path );
168 } elseif ( !isset( $this->locksHeld
[$path][$type] ) ) {
169 $status->warning( 'lockmanager-notlocked', $path );
171 $handlesToClose = [];
172 --$this->locksHeld
[$path][$type];
173 if ( $this->locksHeld
[$path][$type] <= 0 ) {
174 unset( $this->locksHeld
[$path][$type] );
176 if ( $this->locksHeld
[$path] === [] ) {
177 unset( $this->locksHeld
[$path] ); // no locks on this path
178 if ( isset( $this->handles
[$path] ) ) {
179 $handlesToClose[] = $this->handles
[$path];
180 unset( $this->handles
[$path] );
183 // Unlock handles to release locks and delete
184 // any lock files that end up with no locks on them...
185 if ( $this->isWindows
) {
186 // Windows: for any process, including this one,
187 // calling unlink() on a locked file will fail
188 $status->merge( $this->closeLockHandles( $path, $handlesToClose ) );
189 $status->merge( $this->pruneKeyLockFiles( $path ) );
191 // Unix: unlink() can be used on files currently open by this
192 // process and we must do so in order to avoid race conditions
193 $status->merge( $this->pruneKeyLockFiles( $path ) );
194 $status->merge( $this->closeLockHandles( $path, $handlesToClose ) );
202 * @param string $path
203 * @param array $handlesToClose
204 * @return StatusValue
206 private function closeLockHandles( $path, array $handlesToClose ) {
207 $status = StatusValue
::newGood();
208 foreach ( $handlesToClose as $handle ) {
209 if ( !flock( $handle, LOCK_UN
) ) {
210 $status->fatal( 'lockmanager-fail-releaselock', $path );
212 if ( !fclose( $handle ) ) {
213 $status->warning( 'lockmanager-fail-closelock', $path );
221 * @param string $path
222 * @return StatusValue
224 private function pruneKeyLockFiles( $path ) {
225 $status = StatusValue
::newGood();
226 if ( !isset( $this->locksHeld
[$path] ) ) {
227 # No locks are held for the lock file anymore
228 if ( !unlink( $this->getLockPath( $path ) ) ) {
229 $status->warning( 'lockmanager-fail-deletelock', $path );
231 unset( $this->handles
[$path] );
238 * Get the path to the lock file for a key
239 * @param string $path
242 protected function getLockPath( $path ) {
243 return "{$this->lockDir}/{$this->sha1Base36Absolute( $path )}.lock";
247 * Make sure remaining locks get cleared for sanity
249 function __destruct() {
250 while ( count( $this->locksHeld
) ) {
251 foreach ( $this->locksHeld
as $path => $locks ) {
252 $this->doSingleUnlock( $path, self
::LOCK_EX
);
253 $this->doSingleUnlock( $path, self
::LOCK_SH
);