1 <?php

     2 /**

     3  * Zend Framework

     4  *

     5  * LICENSE

     6  *

     7  * This source file is subject to the new BSD license that is bundled

     8  * with this package in the file LICENSE.txt.

     9  * It is also available through the world-wide-web at this URL:

    10  * http://framework.zend.com/license/new-bsd

    11  * If you did not receive a copy of the license and are unable to

    12  * obtain it through the world-wide-web, please send an email

    13  * to license@zend.com so we can send you a copy immediately.

    14  *

    15  * @category   Zend

    16  * @package    Zend_Search_Lucene

    17  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

    18  * @license    http://framework.zend.com/license/new-bsd     New BSD License

    19  * @version    $Id: LockManager.php 20096 2010-01-06 02:05:09Z bkarwin $

    20  */

    21 

    22 /** Zend_Search_Lucene_Storage_Directory */

    23 require_once 'Zend/Search/Lucene/Storage/Directory.php';

    24 

    25 /** Zend_Search_Lucene_Storage_File */

    26 require_once 'Zend/Search/Lucene/Storage/File.php';

    27 

    28 /**

    29  * This is an utility class which provides index locks processing functionality

    30  *

    31  * @category   Zend

    32  * @package    Zend_Search_Lucene

    33  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

    34  * @license    http://framework.zend.com/license/new-bsd     New BSD License

    35  */

    36 class Zend_Search_Lucene_LockManager

    37 {

    38     /**

    39      * consts for name of file to show lock status

    40      */

    41     const WRITE_LOCK_FILE                = 'write.lock.file';

    42     const READ_LOCK_FILE                 = 'read.lock.file';

    43     const READ_LOCK_PROCESSING_LOCK_FILE = 'read-lock-processing.lock.file';

    44     const OPTIMIZATION_LOCK_FILE         = 'optimization.lock.file';

    45 

    46     /**

    47      * Obtain exclusive write lock on the index

    48      *

    49      * @param Zend_Search_Lucene_Storage_Directory $lockDirectory

    50      * @return Zend_Search_Lucene_Storage_File

    51      * @throws Zend_Search_Lucene_Exception

    52      */

    53     public static function obtainWriteLock(Zend_Search_Lucene_Storage_Directory $lockDirectory)

    54     {

    55         $lock = $lockDirectory->createFile(self::WRITE_LOCK_FILE);

    56         if (!$lock->lock(LOCK_EX)) {

    57             require_once 'Zend/Search/Lucene/Exception.php';

    58             throw new Zend_Search_Lucene_Exception('Can\'t obtain exclusive index lock');

    59         }

    60         return $lock;

    61     }

    62 

    63     /**

    64      * Release exclusive write lock

    65      *

    66      * @param Zend_Search_Lucene_Storage_Directory $lockDirectory

    67      */

    68     public static function releaseWriteLock(Zend_Search_Lucene_Storage_Directory $lockDirectory)

    69     {

    70         $lock = $lockDirectory->getFileObject(self::WRITE_LOCK_FILE);

    71         $lock->unlock();

    72     }

    73 

    74     /**

    75      * Obtain the exclusive "read escalation/de-escalation" lock

    76      *

    77      * Required to protect the escalate/de-escalate read lock process

    78      * on GFS (and potentially other) mounted filesystems.

    79      *

    80      * Why we need this:

    81      *  While GFS supports cluster-wide locking via flock(), it's

    82      *  implementation isn't quite what it should be.  The locking

    83      *  semantics that work consistently on a local filesystem tend to

    84      *  fail on GFS mounted filesystems.  This appears to be a design defect

    85      *  in the implementation of GFS.  How this manifests itself is that

    86      *  conditional promotion of a shared lock to exclusive will always

    87      *  fail, lock release requests are honored but not immediately

    88      *  processed (causing erratic failures of subsequent conditional

    89      *  requests) and the releasing of the exclusive lock before the

    90      *  shared lock is set when a lock is demoted (which can open a window

    91      *  of opportunity for another process to gain an exclusive lock when

    92      *  it shoudln't be allowed to).

    93      *

    94      * @param Zend_Search_Lucene_Storage_Directory $lockDirectory

    95      * @return Zend_Search_Lucene_Storage_File

    96      * @throws Zend_Search_Lucene_Exception

    97      */

    98     private static function _startReadLockProcessing(Zend_Search_Lucene_Storage_Directory $lockDirectory)

    99     {

   100         $lock = $lockDirectory->createFile(self::READ_LOCK_PROCESSING_LOCK_FILE);

   101         if (!$lock->lock(LOCK_EX)) {

   102             require_once 'Zend/Search/Lucene/Exception.php';

   103             throw new Zend_Search_Lucene_Exception('Can\'t obtain exclusive lock for the read lock processing file');

   104         }

   105         return $lock;

   106     }

   107 

   108     /**

   109      * Release the exclusive "read escalation/de-escalation" lock

   110      *

   111      * Required to protect the escalate/de-escalate read lock process

   112      * on GFS (and potentially other) mounted filesystems.

   113      *

   114      * @param Zend_Search_Lucene_Storage_Directory $lockDirectory

   115      */

   116     private static function _stopReadLockProcessing(Zend_Search_Lucene_Storage_Directory $lockDirectory)

   117     {

   118         $lock = $lockDirectory->getFileObject(self::READ_LOCK_PROCESSING_LOCK_FILE);

   119         $lock->unlock();

   120     }

   121 

   122 

   123     /**

   124      * Obtain shared read lock on the index

   125      *

   126      * It doesn't block other read or update processes, but prevent index from the premature cleaning-up

   127      *

   128      * @param Zend_Search_Lucene_Storage_Directory $defaultLockDirectory

   129      * @return Zend_Search_Lucene_Storage_File

   130      * @throws Zend_Search_Lucene_Exception

   131      */

   132     public static function obtainReadLock(Zend_Search_Lucene_Storage_Directory $lockDirectory)

   133     {

   134         $lock = $lockDirectory->createFile(self::READ_LOCK_FILE);

   135         if (!$lock->lock(LOCK_SH)) {

   136             require_once 'Zend/Search/Lucene/Exception.php';

   137             throw new Zend_Search_Lucene_Exception('Can\'t obtain shared reading index lock');

   138         }

   139         return $lock;

   140     }

   141 

   142     /**

   143      * Release shared read lock

   144      *

   145      * @param Zend_Search_Lucene_Storage_Directory $lockDirectory

   146      */

   147     public static function releaseReadLock(Zend_Search_Lucene_Storage_Directory $lockDirectory)

   148     {

   149         $lock = $lockDirectory->getFileObject(self::READ_LOCK_FILE);

   150         $lock->unlock();

   151     }

   152 

   153     /**

   154      * Escalate Read lock to exclusive level

   155      *

   156      * @param Zend_Search_Lucene_Storage_Directory $lockDirectory

   157      * @return boolean

   158      */

   159     public static function escalateReadLock(Zend_Search_Lucene_Storage_Directory $lockDirectory)

   160     {

   161         self::_startReadLockProcessing($lockDirectory);

   162 

   163         $lock = $lockDirectory->getFileObject(self::READ_LOCK_FILE);

   164 

   165         // First, release the shared lock for the benefit of GFS since

   166         // it will fail the conditional request to promote the lock to

   167         // "exclusive" while the shared lock is held (even when we are

   168         // the only holder).

   169         $lock->unlock();

   170 

   171         // GFS is really poor.  While the above "unlock" returns, GFS

   172         // doesn't clean up it's tables right away (which will potentially

   173         // cause the conditional locking for the "exclusive" lock to fail.

   174         // We will retry the conditional lock request several times on a

   175         // failure to get past this.  The performance hit is negligible

   176         // in the grand scheme of things and only will occur with GFS

   177         // filesystems or if another local process has the shared lock

   178         // on local filesystems.

   179         for ($retries = 0; $retries < 10; $retries++) {

   180             if ($lock->lock(LOCK_EX, true)) {

   181                 // Exclusive lock is obtained!

   182                 self::_stopReadLockProcessing($lockDirectory);

   183                 return true;

   184             }

   185 

   186             // wait 1 microsecond

   187             usleep(1);

   188         }

   189 

   190         // Restore lock state

   191         $lock->lock(LOCK_SH);

   192 

   193         self::_stopReadLockProcessing($lockDirectory);

   194         return false;

   195     }

   196 

   197     /**

   198      * De-escalate Read lock to shared level

   199      *

   200      * @param Zend_Search_Lucene_Storage_Directory $lockDirectory

   201      */

   202     public static function deEscalateReadLock(Zend_Search_Lucene_Storage_Directory $lockDirectory)

   203     {

   204         $lock = $lockDirectory->getFileObject(self::READ_LOCK_FILE);

   205         $lock->lock(LOCK_SH);

   206     }

   207 

   208     /**

   209      * Obtain exclusive optimization lock on the index

   210      *

   211      * Returns lock object on success and false otherwise (doesn't block execution)

   212      *

   213      * @param Zend_Search_Lucene_Storage_Directory $lockDirectory

   214      * @return mixed

   215      */

   216     public static function obtainOptimizationLock(Zend_Search_Lucene_Storage_Directory $lockDirectory)

   217     {

   218         $lock = $lockDirectory->createFile(self::OPTIMIZATION_LOCK_FILE);

   219         if (!$lock->lock(LOCK_EX, true)) {

   220             return false;

   221         }

   222         return $lock;

   223     }

   224 

   225     /**

   226      * Release exclusive optimization lock

   227      *

   228      * @param Zend_Search_Lucene_Storage_Directory $lockDirectory

   229      */

   230     public static function releaseOptimizationLock(Zend_Search_Lucene_Storage_Directory $lockDirectory)

   231     {

   232         $lock = $lockDirectory->getFileObject(self::OPTIMIZATION_LOCK_FILE);

   233         $lock->unlock();

   234     }

   235 

   236 }