Subject: ANNOUNCE: new module Tie::TransactHash - edit hash in transactions
From: [email-masked] (Michael De La Rue)
Date: 17 Feb 1997 14:25:05 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.modules

Tie::TransactHash 0.02 is now being uploaded by CPAN.  It replaces
0.01 which wasn't publically announced and probably had some serious
bugs.  It is a hash class which overlays any other hash (passed as a
reference to the new() function) and allows it to be edited in
transactions.  This provides the following advantages:

	- all or nothing changes

	- the hash stays in order during the edit - changes can be made
	  to elements in the hash whilst going through them all with each()

	- the time during which the hash could be corrupted is limited
	  to the time that the commit function is running.

The module works by storing changes in a Tie-IxHash (patch included -
I've had no response from GSAR about it yet though).  The interface is
as normal for a hash except that the object also has the methods

	$h->commit()
	$h->reset() #alias to rollback also
	$h->autostore(T/F)
	$h->verify_write()

commit() stores all of the changes made to the overlayed TransactHash
into the underlying hash.  

reset() makes the overlayed hash forget all changes and return to
looking the same as the underlying hash.

autostore() sets whether the TransactHash should automatically call a
commit if it is destroyed (e.g. at program exit).  

           ******** BEGIN WARNING FOR PERL 5.003 **********
With perl5.003, the destructors didn't seem to be called properly at
program exit, and the Hash had to be deleted explicitly.  This is no
longer true with perl 5.003_25 so should be okay when perl 5.004 is
released.  In the meantime use a sequence like the quit command in the
example program if you want an automatic commit when the hash is
DESTROYed
           ********  END WARNING FOR PERL 5.003  **********

verify_write() should compare the values in the underlying hash after
a commit with the changes and check that everything is as should be.
It's not been tested properly though.  Tell me if you care about this;
it will mainly check for internal consistency (of the TransactHash
module) because, without a proper transaction log, it's never possible
to guarantee that writes will be safe.

Included is an example program that allows the direct editing of the
contents of any Berkley DB file.  I use this for debugging programs by
checking that the dbm contains the right values and by changing values
within dbms to see what effect they have.

There is a set of tests for the module, but at present they don't
actually write to a database (they use a normal in memory perl hash).
They should cover most of the functionality though.

Comments and contributions (especially bug fixes) appreciated as ever.

	Michael De La Rue

-- 

            <http://www.tardis.ed.ac.uk/~mikedlr/biography.html>
  Scottish Climbing Archive: <http://www.tardis.ed.ac.uk/~mikedlr/climbing/>
Linux/Unix clone@ftp://src.doc.ic.ac.uk/packages/linux/sunsite.unc-mirror/docs/