From: Rob Kinyon <rob.kinyon@gmail.com>
Date: Mon, 30 Nov 2009 14:29:54 +0000 (-0500)
Subject: Migrated setup_fh -> setup and moved lots of POD into the base class
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=f4d0ac973fcdc7932465a23d38da10d89996eef3;p=dbsrgits%2FDBM-Deep.git

Migrated setup_fh -> setup and moved lots of POD into the base class
---

diff --git a/lib/DBM/Deep.pm b/lib/DBM/Deep.pm
index 8b7328a..68693f0 100644
--- a/lib/DBM/Deep.pm
+++ b/lib/DBM/Deep.pm
@@ -168,7 +168,7 @@ sub _init {
       local $SIG{'__DIE__'};
 
       $self->lock_exclusive;
-      $self->_engine->setup_fh( $self );
+      $self->_engine->setup( $self );
       $self->unlock;
     }; if ( $@ ) {
       my $e = $@;
@@ -417,7 +417,7 @@ sub optimize {
 
     $self->_engine->storage->open;
     $self->lock_exclusive;
-    $self->_engine->setup_fh( $self );
+    $self->_engine->setup( $self );
     $self->unlock;
 
     return 1;
diff --git a/lib/DBM/Deep/Engine.pm b/lib/DBM/Deep/Engine.pm
index 44768ac..276df95 100644
--- a/lib/DBM/Deep/Engine.pm
+++ b/lib/DBM/Deep/Engine.pm
@@ -62,7 +62,7 @@ is the following:
 
 =item * get_next_key
 
-=item * setup_fh
+=item * setup
 
 =item * begin_work
 
@@ -119,7 +119,121 @@ serious programming that make my head hurts just to think about it.
 
 =cut
 
+=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 wiill 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 )
 
@@ -135,7 +249,8 @@ 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
+    # XXX Need to add logic about resetting the iterator if any key in the
+    # reference has changed
     unless ( $prev_key ) {
         $obj->{iterator} = DBM::Deep::Iterator->new({
             base_offset => $obj->_base_offset,
@@ -146,5 +261,81 @@ sub get_next_key {
     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;
+}
+
 1;
 __END__
diff --git a/lib/DBM/Deep/Engine/File.pm b/lib/DBM/Deep/Engine/File.pm
index ccd9541..08c8335 100644
--- a/lib/DBM/Deep/Engine/File.pm
+++ b/lib/DBM/Deep/Engine/File.pm
@@ -123,13 +123,6 @@ sub new {
     return $self;
 }
 
-=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 {
     my $self = shift;
     my ($obj, $key) = @_;
@@ -165,17 +158,6 @@ sub read_value {
     return $value_sector->data;
 }
 
-=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 {
     my $self = shift;
     my ($obj) = @_;
@@ -191,16 +173,6 @@ sub get_classname {
     return $sector->get_classname;
 }
 
-=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 {
     my $self = shift;
     my ($obj, $old_key, $new_key) = @_;
@@ -252,13 +224,6 @@ sub make_reference {
     return;
 }
 
-=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 {
     my $self = shift;
     my ($obj, $key) = @_;
@@ -280,14 +245,6 @@ sub key_exists {
     return $data ? 1 : '';
 }
 
-=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 {
     my $self = shift;
     my ($obj, $key) = @_;
@@ -305,15 +262,6 @@ sub delete_key {
     });
 }
 
-=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 {
     my $self = shift;
     my ($obj, $key, $value) = @_;
@@ -439,17 +387,7 @@ sub write_value {
     return 1;
 }
 
-=head2 setup_fh( $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_fh {
+sub setup {
     my $self = shift;
     my ($obj) = @_;
 
@@ -495,18 +433,6 @@ sub setup_fh {
     return 1;
 }
 
-=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 wiill be thrown. If there are
-no more available transactions, an error will be thrown.
-
-This returns undef.
-
-=cut
-
 sub begin_work {
     my $self = shift;
     my ($obj) = @_;
@@ -537,17 +463,6 @@ sub begin_work {
     return;
 }
 
-=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 {
     my $self = shift;
     my ($obj) = @_;
@@ -586,17 +501,6 @@ sub rollback {
     return 1;
 }
 
-=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 {
     my $self = shift;
     my ($obj) = @_;
@@ -641,56 +545,6 @@ sub commit {
     return 1;
 }
 
-=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 all locks taken.
-
-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::File.
@@ -1155,23 +1009,6 @@ sub _request_sector {
     return $loc;
 }
 
-=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_fh().
-
-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;
-}
-
 =head2 ACCESSORS
 
 The following are readonly attributes.
diff --git a/lib/DBM/Deep/Storage/File.pm b/lib/DBM/Deep/Storage/File.pm
index 96862d3..2d03880 100644
--- a/lib/DBM/Deep/Storage/File.pm
+++ b/lib/DBM/Deep/Storage/File.pm
@@ -406,7 +406,7 @@ sub _lock {
                 $self->open;
 
                 #XXX This needs work
-                $obj->{engine}->setup_fh( $obj );
+                $obj->{engine}->setup( $obj );
 
                 flock($self->{fh}, $type); # re-lock