Initial Commit

database/perl/vendor/lib/DBM/Deep/Engine.pm

@@ -0,0 +1,442 @@
+package DBM::Deep::Engine;
+
+use 5.008_004;
+
+use strict;
+use warnings FATAL => 'all';
+no warnings 'recursion';
+
+use DBM::Deep::Iterator ();
+
+# File-wide notes:
+# * Every method in here assumes that the storage has been appropriately
+#   safeguarded. This can be anything from flock() to some sort of manual
+#   mutex. But, it's the caller's responsibility to make sure that this has
+#   been done.
+
+sub SIG_HASH     () { 'H' }
+sub SIG_ARRAY    () { 'A' }
+
+=head1 NAME
+
+DBM::Deep::Engine - mediate mapping between DBM::Deep objects and storage medium
+
+=head1 PURPOSE
+
+This is an internal-use-only object for L<DBM::Deep>. It mediates the low-level
+mapping between the L<DBM::Deep> objects and the storage medium.
+
+The purpose of this documentation is to provide low-level documentation for
+developers. It is B<not> intended to be used by the general public. This
+documentation and what it documents can and will change without notice.
+
+=head1 OVERVIEW
+
+The engine exposes an API to the DBM::Deep objects (DBM::Deep, DBM::Deep::Array,
+and DBM::Deep::Hash) for their use to access the actual stored values. This API
+is the following:
+
+=over 4
+
+=item * new
+
+=item * read_value
+
+=item * get_classname
+
+=item * make_reference
+
+=item * key_exists
+
+=item * delete_key
+
+=item * write_value
+
+=item * get_next_key
+
+=item * setup
+
+=item * clear
+
+=item * begin_work
+
+=item * commit
+
+=item * rollback
+
+=item * lock_exclusive
+
+=item * lock_shared
+
+=item * unlock
+
+=back
+
+They are explained in their own sections below. These methods, in turn, may
+provide some bounds-checking, but primarily act to instantiate objects in the
+Engine::Sector::* hierarchy and dispatch to them.
+
+=head1 TRANSACTIONS
+
+Transactions in DBM::Deep are implemented using a variant of MVCC. This attempts
+to keep the amount of actual work done against the file low while still providing
+Atomicity, Consistency, and Isolation. Durability, unfortunately, cannot be done
+with only one file.
+
+=head2 STALENESS
+
+If another process uses a transaction slot and writes stuff to it, then
+terminates, the data that process wrote is still within the file. In order to
+address this, there is also a transaction staleness counter associated within
+every write.  Each time a transaction is started, that process increments that
+transaction's staleness counter. If, when it reads a value, the staleness
+counters aren't identical, DBM::Deep will consider the value on disk to be stale
+and discard it.
+
+=head2 DURABILITY
+
+The fourth leg of ACID is Durability, the guarantee that when a commit returns,
+the data will be there the next time you read from it. This should be regardless
+of any crashes or powerdowns in between the commit and subsequent read.
+DBM::Deep does provide that guarantee; once the commit returns, all of the data
+has been transferred from the transaction shadow to the HEAD. The issue arises
+with partial commits - a commit that is interrupted in some fashion. In keeping
+with DBM::Deep's "tradition" of very light error-checking and non-existent
+error-handling, there is no way to recover from a partial commit. (This is
+probably a failure in Consistency as well as Durability.)
+
+Other DBMSes use transaction logs (a separate file, generally) to achieve
+Durability.  As DBM::Deep is a single-file, we would have to do something
+similar to what SQLite and BDB do in terms of committing using synchronized
+writes. To do this, we would have to use a much higher RAM footprint and some
+serious programming that makes my head hurt just to think about it.
+
+=cut
+
+=head1 METHODS
+
+=head2 read_value( $obj, $key )
+
+This takes an object that provides _base_offset() and a string. It returns the
+value stored in the corresponding Sector::Value's data section.
+
+=cut
+
+sub read_value { die "read_value must be implemented in a child class" }
+
+=head2 get_classname( $obj )
+
+This takes an object that provides _base_offset() and returns the classname (if
+any) associated with it.
+
+It delegates to Sector::Reference::get_classname() for the heavy lifting.
+
+It performs a staleness check.
+
+=cut
+
+sub get_classname { die "get_classname must be implemented in a child class" }
+
+=head2 make_reference( $obj, $old_key, $new_key )
+
+This takes an object that provides _base_offset() and two strings. The
+strings correspond to the old key and new key, respectively. This operation
+is equivalent to (given C<< $db->{foo} = []; >>) C<< $db->{bar} = $db->{foo} >>.
+
+This returns nothing.
+
+=cut
+
+sub make_reference { die "make_reference must be implemented in a child class" }
+
+=head2 key_exists( $obj, $key )
+
+This takes an object that provides _base_offset() and a string for
+the key to be checked. This returns 1 for true and "" for false.
+
+=cut
+
+sub key_exists { die "key_exists must be implemented in a child class" }
+
+=head2 delete_key( $obj, $key )
+
+This takes an object that provides _base_offset() and a string for
+the key to be deleted. This returns the result of the Sector::Reference
+delete_key() method.
+
+=cut
+
+sub delete_key { die "delete_key must be implemented in a child class" }
+
+=head2 write_value( $obj, $key, $value )
+
+This takes an object that provides _base_offset(), a string for the
+key, and a value. This value can be anything storable within L<DBM::Deep>.
+
+This returns 1 upon success.
+
+=cut
+
+sub write_value { die "write_value must be implemented in a child class" }
+
+=head2 setup( $obj )
+
+This takes an object that provides _base_offset(). It will do everything needed
+in order to properly initialize all values for necessary functioning. If this is
+called upon an already initialized object, this will also reset the inode.
+
+This returns 1.
+
+=cut
+
+sub setup { die "setup must be implemented in a child class" }
+
+=head2 begin_work( $obj )
+
+This takes an object that provides _base_offset(). It will set up all necessary
+bookkeeping in order to run all work within a transaction.
+
+If $obj is already within a transaction, an error will be thrown. If there are
+no more available transactions, an error will be thrown.
+
+This returns undef.
+
+=cut
+
+sub begin_work { die "begin_work must be implemented in a child class" }
+
+=head2 rollback( $obj )
+
+This takes an object that provides _base_offset(). It will revert all
+actions taken within the running transaction.
+
+If $obj is not within a transaction, an error will be thrown.
+
+This returns 1.
+
+=cut
+
+sub rollback { die "rollback must be implemented in a child class" }
+
+=head2 commit( $obj )
+
+This takes an object that provides _base_offset(). It will apply all
+actions taken within the transaction to the HEAD.
+
+If $obj is not within a transaction, an error will be thrown.
+
+This returns 1.
+
+=cut
+
+sub commit { die "commit must be implemented in a child class" }
+
+=head2 get_next_key( $obj, $prev_key )
+
+This takes an object that provides _base_offset() and an optional string
+representing the prior key returned via a prior invocation of this method.
+
+This method delegates to C<< DBM::Deep::Iterator->get_next_key() >>.
+
+=cut
+
+# XXX Add staleness here
+sub get_next_key {
+    my $self = shift;
+    my ($obj, $prev_key) = @_;
+
+    # XXX Need to add logic about resetting the iterator if any key in the
+    # reference has changed
+    unless ( defined $prev_key ) {
+        eval "use " . $self->iterator_class; die $@ if $@;
+        $obj->{iterator} = $self->iterator_class->new({
+            base_offset => $obj->_base_offset,
+            engine      => $self,
+        });
+    }
+
+    return $obj->{iterator}->get_next_key( $obj );
+}
+
+=head2 lock_exclusive()
+
+This takes an object that provides _base_offset(). It will guarantee that
+the storage has taken precautions to be safe for a write.
+
+This returns nothing.
+
+=cut
+
+sub lock_exclusive {
+    my $self = shift;
+    my ($obj) = @_;
+    return $self->storage->lock_exclusive( $obj );
+}
+
+=head2 lock_shared()
+
+This takes an object that provides _base_offset(). It will guarantee that
+the storage has taken precautions to be safe for a read.
+
+This returns nothing.
+
+=cut
+
+sub lock_shared {
+    my $self = shift;
+    my ($obj) = @_;
+    return $self->storage->lock_shared( $obj );
+}
+
+=head2 unlock()
+
+This takes an object that provides _base_offset(). It will guarantee that
+the storage has released the most recently-taken lock.
+
+This returns nothing.
+
+=cut
+
+sub unlock {
+    my $self = shift;
+    my ($obj) = @_;
+
+    my $rv = $self->storage->unlock( $obj );
+
+    $self->flush if $rv;
+
+    return $rv;
+}
+
+=head1 INTERNAL METHODS
+
+The following methods are internal-use-only to DBM::Deep::Engine and its
+child classes.
+
+=cut
+
+=head2 flush()
+
+This takes no arguments. It will do everything necessary to flush all things to
+disk. This is usually called during unlock() and setup().
+
+This returns nothing.
+
+=cut
+
+sub flush {
+    my $self = shift;
+
+    # Why do we need to have the storage flush? Shouldn't autoflush take care of
+    # things? -RobK, 2008-06-26
+    $self->storage->flush;
+
+    return;
+}
+
+=head2 load_sector( $loc )
+
+This takes an id/location/offset and loads the sector based on the engine's
+defined sector type.
+
+=cut
+
+sub load_sector { $_[0]->sector_type->load( @_ ) }
+
+=head2 clear( $obj )
+
+This takes an object that provides _base_offset() and deletes all its 
+elements, returning nothing.
+
+=cut
+
+sub clear { die "clear must be implemented in a child class" }
+
+=head2 cache / clear_cache
+
+This is the cache of loaded Reference sectors.
+
+=cut
+
+sub cache       { $_[0]{cache} ||= {} }
+sub clear_cache { %{$_[0]->cache} = () }
+
+=head2 supports( $option )
+
+This returns a boolean depending on if this instance of DBM::Dep supports
+that feature. C<$option> can be one of:
+
+=over 4
+
+=item * transactions
+
+=item * singletons
+
+=back
+
+Any other value will return false.
+
+=cut
+
+sub supports { die "supports must be implemented in a child class" }
+
+=head1 ACCESSORS
+
+The following are readonly attributes.
+
+=over 4
+
+=item * storage
+
+=item * sector_type
+
+=item * iterator_class
+
+=back
+
+=cut
+
+sub storage { $_[0]{storage} }
+
+sub sector_type { die "sector_type must be implemented in a child class" }
+sub iterator_class { die "iterator_class must be implemented in a child class" }
+
+# This code is to make sure we write all the values in the $value to the
+# disk and to make sure all changes to $value after the assignment are
+# reflected on disk. This may be counter-intuitive at first, but it is
+# correct dwimmery.
+#   NOTE - simply tying $value won't perform a STORE on each value. Hence,
+# the copy to a temp value.
+sub _descend {
+    my $self = shift;
+    my ($value, $value_sector) = @_;
+    my $r = Scalar::Util::reftype( $value ) || '';
+
+    if ( $r eq 'ARRAY' ) {
+        my @temp = @$value;
+        tie @$value, 'DBM::Deep', {
+            base_offset => $value_sector->offset,
+            staleness   => $value_sector->staleness,
+            storage     => $self->storage,
+            engine      => $self,
+        };
+        @$value = @temp;
+        bless $value, 'DBM::Deep::Array' unless Scalar::Util::blessed( $value );
+    }
+    elsif ( $r eq 'HASH' ) {
+        my %temp = %$value;
+        tie %$value, 'DBM::Deep', {
+            base_offset => $value_sector->offset,
+            staleness   => $value_sector->staleness,
+            storage     => $self->storage,
+            engine      => $self,
+        };
+        %$value = %temp;
+        bless $value, 'DBM::Deep::Hash' unless Scalar::Util::blessed( $value );
+    }
+
+    return;
+}
+
+1;
+__END__