NAME
   Object::Transaction - Virtual base class for transactions on files
   containing serialized hash objects

SYNOPSIS
           use Object::Transaction;

           transaction($coderef, @codeargs);
           commit();
           abandon();
           $there_is_a_pending_transaction = transaction_pending()

           package Pkg;

           @ISA = qw(Object::Transaction);

           use Object::Transaction;

           $obj = sub new { ... }
           sub file($ref,$id) { ... }

           $obj = load Pkg $id;
           $obj->savelater();
           $obj->save();
           $obj->removelater();
           $obj->remove();
           $obj->commit();
           $obj->uncache();
           $obj->abandon();
           $oldobj = $obj->old();

           $reference = $obj->objectref();
           $obj = $reference->loadref();

           $id = sub id { ... }
           $restart_commit = sub precommit() { }
           @passby = sub presave($old) { ... }
           sub postsave($old,@passby) { ... }
           $newid = sub preload($id) { .... }
           sub postload() { ... }
           sub preremove() { ... }
           sub postremove() { ... }

DESCRIPTION
   Object::Transaction provides transaction support for hash-based objects
   that are stored one-per-file using Storable. Multiuser access is
   supported. In the future, serializing methods other than Storable will
   be supported.

   Object::Transaction is a virtual base class. In order to use it, you
   must inherit from it and override the "new" method and the "file"
   method.

   Optomistic locking is used: it is possible that a transaction will fail
   because the data that is is based upon has changed out from under it.

EXAMPLE
           package User;

           @ISA = qw(Object::Transaction);

           use Object::Transaction;

           my $top = "/some/path";

           sub new {
                   my ($package, $login) = @_;
                   die unless getpwnam($login);
                   return bless { UID => getpwnam($login) };
           }

           sub file {
                   my ($ref, $id) = @_;
                   $id = $ref->id() unless $id;
                   return "$top/users/$id/data.storable";
           }

           sub id {
                   my ($this) = @_;
                   return $this->{UID};
           }

           sub preload
           {
                   my ($id) = @_;
                   return if getpwuid($id);
                   return getpwnam($id) if getpwnam($id);
                   die;
           }

           sub postload
           {
                   my ($this) = @_;
                   my ($name,$passwd,$uid,$gid,$quota,$comment,$gcos,$dir,
                           $shell,$expire) = getpwuid($this->{UID});
                   $this->{SHELL} = $shell;
           }

           sub presave
           {
                   my ($this, $old) = @_;
                   my $id = $this->{UID};
                   mkdir("$top/users/$id", 0700);
                   delete $this->{SHELL};
           }

           sub postsave
           {
                   goto &postload;
           }

           sub postremove
           {
                   delete from pw file...
           }

           my $joe = new User "joe";
           $joe->savelater();

           my $fred = new User "fred";
           $fred->savelater();

           $joe->commit();

METHODS PROVIDED
   Object::Transaction provides the following methods.

   "load($id)"    "load" is the way to bring an object into memory. It is
                  usually invoked as "my $obj = load MyObject $id".

                  There are two opportunities to customize the behavior of
                  "load": "preload" for things that should happen before
                  loading and "postload" for things that should happen
                  after loading.

                  Object::Transaction caches objects that are loaded. This
                  is done both for performance reasons and to make sure
                  that only one copy of an object is in memory at a time.
                  If caching is not desired, the "uncache" method must be
                  invoked after loading.



   "savelater()"  "savelater" is the usual method of saving an object. The
                  object is not saved at the time that "savelater" is
                  invoked. It is actually saved when "commit" is invoked.

                  There are two opportunities to customize the behavior of
                  "savelater": "presave" for things that should happen
                  before saving and "postsave" for things that should
                  happen after saving. These are invoked when the object is
                  actually being saved.

   "save()"       Simply "savelater" combined with a "commit".



   "removelater()"
                  "removelater" is the usual method of removing an object.
                  The object is not removed at the time that "removelater"
                  is invoked. It is actually removed when "commit" is
                  invoked.

                  There are two opporunities to customize the behavior of
                  "removelater": "preremove" for things that should happen
                  before removing and "postremove" for things that should
                  happen after removing. These are invoked when the object
                  is actually being removed.

   "remove()"     Simply "removelater" combined with a "commit"



   "commit()"     "commit" writes all pending changes to disk. Either all
                  changes will be saved or none of them will. Deadlocks are
                  avoided by locking files in order.

                  Object::Transaction uses opportunistic locking. Commit
                  can fail. If it fails, it will "die" with a message that
                  begins "DATACHANGE: file". It is advisable to wrap your
                  entire transaction inside an eval so that it can be
                  re-tried in the event that the data on disk changed
                  between the time is was loaded and commited.

                  In the event of a commit failure, the object cache will
                  be reset. Do not keep any old references to objects after
                  such a failure. To avoid keeping old references, it is
                  advised that the first "load()" call happen inside the
                  "eval".

   "transaction($funcref,@args)"
                  "transaction()" is a wrapper for a complete transaction.
                  Transactions that fail due to opportunistic locking
                  problems will be re-run automatically. Beware
                  side-effects!

                  The first parameter is a reference to a function. Any
                  additional parameters will be passed as parameters to
                  that function. The return value of "transaction()" is the
                  return value of "&$funcref()".

                  It is not necessary to use the "transaction()" method.
                  Just beware that "commit()", "save()", and "remove()" can
                  fail. "transaction()" will keep trying until it suceeds;
                  it failes for a reason other than an opportunistic
                  locking problem; or it gives up because it has had too
                  many (more than $ObjTransLclCnfg::maxtries) failures.

                  It is important that objects not be cached from one
                  invocation of "transaction()" to another. The following
                  would fail badly.

                          my $obj1 = load MyObject $obj1;

                          my $p = fork();

                          transaction(sub {
                                  $obj1->savelater();
                                  commit();
                          });

                  To fix it, move the object load to inside the
                  "transaction()" call.

   "transaction_pending()"
                  "transaction_pending()" returns true if there is a
                  transaction pending. (savelater() called, but commit()
                  not yet called).



   "abandon()"    As an alternative to "commit", all changes may be
                  abandoned. Calling "abandon()" does not undo changes made
                  to the in-memory copies of objects.



   "uncache()"    Object::Transaction caches all objects. To flush an
                  object from Object::Transaction's cache, invoke the
                  "uncache" method on the object.

                  Be careful when doing this -- it makes it possible to
                  have more than one copy of the same object in memory.

                  "uncache()" can be invoked as a class method rather than
                  an object method ("Object::Transaction-"uncache()>). When
                  invoked as a class method, the entire cache is flushed.

   "readlock()"   By default Object::Transaction does not lock objects
                  unless they are being modified.

                  The "readlock()" method insures that objects are properly
                  locked and unchanged during a transaction even if they
                  are not being modified. "savelater()" takes precedence
                  over "readlock()" so they can be combined freely.

                  Paranoid programmers should use "readlock()" on most
                  objects.

                  "readlock()" doesn't actually lock objects, it just
                  verifies that they haven't changed when the transaction
                  commits.

   "old()"        Return the previous version of an object. Previous is
                  only loosely defined.

   "objectref()"  Objectref creates a tiny object that is a reference to an
                  object. The reference can be turned back into the object
                  by invoking "loadref()". For example:

                          $reference = $object->objectref();

                          $object = $reference->loadref();

                  The reference is suitable for persistant storage as a
                  member in a persistant object.

   "cache()"      Objects are cached so that multiple loads of the same
                  identifier result in only one object in memory. Newly
                  created objects that are created with
                  "Object::Transaction::new" will be put in the cache
                  immediately. If an object is created some other way, and
                  there is chance that it will be "load()"ed before the
                  tranaction commits, there is the potential for a problem.
                  Invoking "cache()" puts an object into the cache so that
                  "load()" won't fail.

REQUIRED METHODS TO OVERRIDE
   The following methods must be overriden.

   "initialize"   Object::Transaction provides a contructor. The
                  constructor provide delegates much of the work to a
                  callback that you can override: "initialize()".

   "file($ref,$id)"
                  You must provide a function that returns the filename
                  that an object is stored in. The "file" method can be
                  invoked in two ways: as an object method call without an
                  $id parameter; or as a class method call with an $id
                  parameter.

OPTIONAL METHODS TO OVERRIDE
   The following methods may be overridden.



   "preload($id)" "preload()" is invoked as nearly the first step of
                  "load". It is generally used to make sure that the $id is
                  valid. "preload()" is a class method rather than an
                  object method.

                  The return value of "preload" is a replacement $id. For
                  example, it might be called as "preload("Joe")" to load
                  the user named Joe, but if users are numbered rather than
                  named it could return the number for Joe. A return value
                  of undef is ignored.

                  No lock on the underlying file is present at the time
                  "preload" or "postload" is called.

   "postload($id)"
                  "postload" is invoked after the object has been loaded
                  into memory but before transaction completeness is
                  checked.

                  The underlying file is not locked at the time that
                  "postload" is invoked. Previous versions of
                  Object::Transaction locked the underlying object while
                  "postload" was invoked.

                  If a transaction rollback is required, "postload" will be
                  invoked again after the object has been reverted to its
                  pre-transaction state.



   "presave($old)"
                  "presave()" is invoked just before an object is written
                  to disk.

                  Objects are stored on disk in the file specified by the
                  "file" method. The directory in which that file resides
                  must exist by the time "presave()" finishes. "presave"
                  should make the directory if it isn't already made.

                  The underlying file may or may not be locked at the time
                  "presave" is invoked.

                  "presave" can be invoked as a side-effect of "load" if
                  the object must roll back to a previous version.

                  The parameter $old is a copy of the object as of the time
                  it was first loaded into memory.

                  Any return values from "presave" will be remembered and
                  passed to "postsave".

                  "presave" may not invoke "save()", "commit()", or
                  "savelater()".



   "postsave($old,@psv)"
                  "postsave" is invoked after an object has been written to
                  disk.

                  The underlying file is always locked at the time
                  "postsave" is invoked.

                  Invocations of "presave" and "postsave" are always
                  paired.

                  The parameter $old is a copy of the object as of the time
                  it was first loaded into memory.

                  The parameter @psv is the return value from "presave".

                  "postsave" may not invoke "save()", "commit()", or
                  "savelater()".



   "precommit($old)"
                  "precommit" is invoked just before files are locked in
                  "commit()". This is before "presave()".

                  Unlike "presave()" and "postsave()", "precommit()" may
                  use "savelater()" to add new objects to the transaction.
                  If it does so, it must return a true value.



   "id()"         Object::Transaction expects to be able to find the unique
                  identifier (id) for each object as "$obj-"{'ID'}>. If
                  that isn't the case, you can override the "id" function
                  to provide an alternative.

   "new()"        The new method that Object::Transaction defines is
                  minimal. It does a callback to "initialize()" as an
                  additional hook for customization.

PUBLIC MEMBER DATA
   The following data members are used by Object::Transaction.

   "ID"           Object::Transaction expect to find the id for an object
                  in "$obj-"{'ID'}>. This can be overridden by defining
                  your own "id" function.

   "OLD"          When an object is loaded into memory a copy is made. The
                  copy can be found at "$obj-"{OLD}>. The copy should not
                  be modified. The copy is explicitly passed to "presave"
                  and "postsave".

PRIVATE MEMBER DATA
   Object::Transaction adds a few data members to each object for its own
   internal use.

   These are:

           __frozen
           __transfollowers
           __transleader
           __rollback
           __removenow
           __toremove
           __transdata
           __readonly
           __trivial
           __atcommit
           __poison

   None of these should be touched.

FUNCTIONS
   There are a few functions exported by Object::Transaction. These
   functions are also available as methods. They are "transaction()",
   "transaction_pending()", "uncache()", "commit()", and "abandon()".

BUGS
   A program or computer crash at just the wrong moment can allow an object
   that should be deleted to escape deletion. Any future attempt to access
   such an object will cause it to self-destruct.

   In some situations objects will be saved even if niether "save()" nor
   "savelater()" is invoked. This happens if "readlock()" is used and the
   transaction leader object (one per transaction) choosen turns out to be
   an object for which only "readlock()" was called.

AUTHOR
   David Muir Sharnoff <[email protected]>

COPYRIGHT
   Copyright (C) 1999-2002, Internet Journals Corporation
   <www.bepress.com>. Copyright (C) 2002, David Muir Sharnoff. All rights
   reserved. License hearby granted for anyone to use this module at their
   own risk. Please feed useful changes back to David Muir Sharnoff
   <[email protected]>.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.