NAME

       Lucy::Docs::FileLocking - Manage indexes on shared volumes.

SYNOPSIS

           use Sys::Hostname qw( hostname );
           my $hostname = hostname() or die "Can't get unique hostname";
           my $manager = Lucy::Index::IndexManager->new( host => $hostname );

           # Index time:
           my $indexer = Lucy::Index::Indexer->new(
               index   => '/path/to/index',
               manager => $manager,
           );

           # Search time:
           my $reader = Lucy::Index::IndexReader->open(
               index   => '/path/to/index',
               manager => $manager,
           );
           my $searcher = Lucy::Search::IndexSearcher->new( index => $reader );

DESCRIPTION

       Normally, index locking is an invisible process.  Exclusive write access is controlled via
       lockfiles within the index directory and problems only arise if multiple processes attempt
       to acquire the write lock simultaneously; search-time processes do not ordinarily require
       locking at all.

       On shared volumes, however, the default locking mechanism fails, and manual intervention
       becomes necessary.

       Both read and write applications accessing an index on a shared volume need to identify
       themselves with a unique "host" id, e.g. hostname or ip address.  Knowing the host id
       makes it possible to tell which lockfiles belong to other machines and therefore must not
       be removed when the lockfile's pid number appears not to correspond to an active process.

       At index-time, the danger is that multiple indexing processes from different machines
       which fail to specify a unique "host" id can delete each others' lockfiles and then
       attempt to modify the index at the same time, causing index corruption.  The search-time
       problem is more complex.

       Once an index file is no longer listed in the most recent snapshot, Indexer attempts to
       delete it as part of a post-commit() cleanup routine.  It is possible that at the moment
       an Indexer is deleting files which it believes no longer needed, a Searcher referencing an
       earlier snapshot is in fact using them.  The more often that an index is either updated or
       searched, the more likely it is that this conflict will arise from time to time.

       Ordinarily, the deletion attempts are not a problem.   On a typical unix volume, the files
       will be deleted in name only: any process which holds an open filehandle against a given
       file will continue to have access, and the file won't actually get vaporized until the
       last filehandle is cleared.  Thanks to "delete on last close semantics", an Indexer can't
       truly delete the file out from underneath an active Searcher.   On Windows, where file
       deletion fails whenever any process holds an open handle, the situation is different but
       still workable: Indexer just keeps retrying after each commit until deletion finally
       succeeds.

       On NFS, however, the system breaks, because NFS allows files to be deleted out from
       underneath active processes.  Should this happen, the unlucky read process will crash with
       a "Stale NFS filehandle" exception.

       Under normal circumstances, it is neither necessary nor desirable for IndexReaders to
       secure read locks against an index, but for NFS we have to make an exception.
       LockFactory's make_shared_lock() method exists for this reason; supplying an IndexManager
       instance to IndexReader's constructor activates an internal locking mechanism using
       make_shared_lock() which prevents concurrent indexing processes from deleting files that
       are needed by active readers.

       Since shared locks are implemented using lockfiles located in the index directory (as are
       exclusive locks), reader applications must have write access for read locking to work.
       Stale lock files from crashed processes are ordinarily cleared away the next time the same
       machine -- as identified by the "host" parameter -- opens another IndexReader. (The
       classic technique of timing out lock files is not feasible because search processes may
       lie dormant indefinitely.) However, please be aware that if the last thing a given machine
       does is crash, lock files belonging to it may persist, preventing deletion of obsolete
       index data.