README DB_File::Lock version 0.02 by David Harris -- WHAT DOES THIS MODULE DO? This module provides a wrapper for the DB_File module, adding locking. When you need locking, simply use this module in place of DB_File and add an extra argument onto the tie command specifying if the file should be locked for reading or writing. The alternative is to write code like: open(LOCK, "<$db_filename.lock") or die; flock(LOCK, LOCK_SH) or die; tie(%db_hash, 'DB_File', $db_filename, O_RDONLY, 0600, $DB_HASH) or die; ... then read the database ... untie(%db_hash); close(LOCK); This module lets you write tie(%db_hash, 'DB_File', $db_filename, O_RDONLY, 0600, $DB_HASH, 'read') or die; ... then read the database ... untie(%db_hash); This is better for two reasons: (1) Less cumbersome to write. (2) A fatal exception in the code working on the database which does not lead to process termination will probably not close the lockfile and therefore cause a dropped lock. -- WHY MIGHT ONE NEED A LOCKING WRAPPER MODULE? There can be many reasons: (1) You have an application which is going to modify a DB_File database and it's possible that multiple instances of the application will be run at the same time. If you don't do locking then you can easily corrupt the database file. (a) You get tired of writing your locking code manually and want it handled for you by a nice module. You know, it's kind of cumbersome writing all that stuff out. :-) (b) You are running in an environment (such as mod_perl or code which may be inside an eval { .. } error trapper) where your code may be interrupted by a fatal error and not immediately lead to process termination. This can cause dropped locks. (c) You are using $db->fd to lock the database _AFTER_ you have tied the database. This fatally flawed and does lead to database corruption. (This method was promoted in the old DB_File docs and in the Camel book.) See the ``Why you shouldn't use "fd" to lock a database'' section in the new DB_File docs. (d) You have thought of some reason I have not. :-) (2) You are using mod_perl. This ends the discussion right there -- it is _imperative_ to use a DB_File locking wrapper with mod_perl. See http://perl.apache.org/guide/dbm.html#mod_perl_and_dbm for more info. -- IS THIS THE CORRECT LOCKING WRAPPER FOR MY APPLICATION? There are three locking wrappers for DB_File in CPAN right now. Each one implements locking differently and has different goals in mind. It is therefore worth knowing the difference, so that you can pick the right one for your application. Here are the three locking wrappers: Tie::DB_Lock -- DB_File wrapper which creates copies of the database file for read access, so that you have kind of a multiversioning concurrent read system. However, updates are still serial. Use for databases where reads may be lengthy and consistency problems may occur. Tie::DB_LockFile -- DB_File wrapper that has the ability to lock and unlock the database while it is being used. Avoids the tie-before-flock problem by simply re-tie-ing the database when you get or drop a lock. Because of the flexibility in dropping and re-acquiring the lock in the middle of a session, this can be massaged into a system that will work with long updates and/or reads if the application follows the hints in the POD documentation. DB_File::Lock (this module) -- extremely lightweight DB_File wrapper that simply flocks a lockfile before tie-ing the database and drops the lock after the untie. Allows one to use the same lockfile for multiple databases to avoid deadlock problems, if desired. Use for databases where updates are reads are quick and simple flock locking semantics are enough. (This text duplicated in the POD documentation, by the way.) -- INSTALL To install the module, do the usual: perl Makefile.PL make make test make install The test files in this module require a valid fork command. If your platform does not have fork(2), then please accept failures on the test phase of this module. ___________________ Copyright (c) 1999-2000 David R. Harris. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.