| /* Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| parcel Lucy; |
| |
| /** Manage indexes on shared volumes. |
| * |
| * 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 <code>host</code> 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 <code>host</code> 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 <code>host</code> 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. |
| */ |
| |
| inert class Lucy::Docs::FileLocking { } |
| |
| |
