view release on metacpan or  search on metacpan

README  view on Meta::CPAN

README

DB_File::Lock version 0.05
by David Harris <dharris@drh.net>


    -- 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