lib/DBM/Deep/Engine.pm

   1 package DBM::Deep::Engine;
   2
   3 use 5.006_000;
   4
   5 use strict;
   6 use warnings FATAL => 'all';
   7
   8 use DBM::Deep::Iterator ();
   9
  10 # File-wide notes:
  11 # * Every method in here assumes that the storage has been appropriately
  12 #   safeguarded. This can be anything from flock() to some sort of manual
  13 #   mutex. But, it's the caller's responsability to make sure that this has
  14 #   been done.
  15
  16 # Setup file and tag signatures.  These should never change.
  17 sub SIG_FILE     () { 'DPDB' }
  18 sub SIG_HEADER   () { 'h'    }
  19 sub SIG_HASH     () { 'H'    }
  20 sub SIG_ARRAY    () { 'A'    }
  21 sub SIG_NULL     () { 'N'    }
  22 sub SIG_DATA     () { 'D'    }
  23 sub SIG_INDEX    () { 'I'    }
  24 sub SIG_BLIST    () { 'B'    }
  25 sub SIG_FREE     () { 'F'    }
  26 sub SIG_SIZE     () {  1     }
  27
  28 =head1 NAME
  29
  30 DBM::Deep::Engine
  31
  32 =head1 PURPOSE
  33
  34 This is an internal-use-only object for L<DBM::Deep/>. It mediates the low-level
  35 mapping between the L<DBM::Deep/> objects and the storage medium.
  36
  37 The purpose of this documentation is to provide low-level documentation for
  38 developers. It is B<not> intended to be used by the general public. This
  39 documentation and what it documents can and will change without notice.
  40
  41 =head1 OVERVIEW
  42
  43 The engine exposes an API to the DBM::Deep objects (DBM::Deep, DBM::Deep::Array,
  44 and DBM::Deep::Hash) for their use to access the actual stored values. This API
  45 is the following:
  46
  47 =over 4
  48
  49 =item * new
  50
  51 =item * read_value
  52
  53 =item * get_classname
  54
  55 =item * make_reference
  56
  57 =item * key_exists
  58
  59 =item * delete_key
  60
  61 =item * write_value
  62
  63 =item * get_next_key
  64
  65 =item * setup
  66
  67 =item * begin_work
  68
  69 =item * commit
  70
  71 =item * rollback
  72
  73 =item * lock_exclusive
  74
  75 =item * lock_shared
  76
  77 =item * unlock
  78
  79 =back
  80
  81 They are explained in their own sections below. These methods, in turn, may
  82 provide some bounds-checking, but primarily act to instantiate objects in the
  83 Engine::Sector::* hierarchy and dispatch to them.
  84
  85 =head1 TRANSACTIONS
  86
  87 Transactions in DBM::Deep are implemented using a variant of MVCC. This attempts
  88 to keep the amount of actual work done against the file low while stil providing
  89 Atomicity, Consistency, and Isolation. Durability, unfortunately, cannot be done
  90 with only one file.
  91
  92 =head2 STALENESS
  93
  94 If another process uses a transaction slot and writes stuff to it, then
  95 terminates, the data that process wrote it still within the file. In order to
  96 address this, there is also a transaction staleness counter associated within
  97 every write.  Each time a transaction is started, that process increments that
  98 transaction's staleness counter. If, when it reads a value, the staleness
  99 counters aren't identical, DBM::Deep will consider the value on disk to be stale
 100 and discard it.
 101
 102 =head2 DURABILITY
 103
 104 The fourth leg of ACID is Durability, the guarantee that when a commit returns,
 105 the data will be there the next time you read from it. This should be regardless
 106 of any crashes or powerdowns in between the commit and subsequent read.
 107 DBM::Deep does provide that guarantee; once the commit returns, all of the data
 108 has been transferred from the transaction shadow to the HEAD. The issue arises
 109 with partial commits - a commit that is interrupted in some fashion. In keeping
 110 with DBM::Deep's "tradition" of very light error-checking and non-existent
 111 error-handling, there is no way to recover from a partial commit. (This is
 112 probably a failure in Consistency as well as Durability.)
 113
 114 Other DBMSes use transaction logs (a separate file, generally) to achieve
 115 Durability.  As DBM::Deep is a single-file, we would have to do something
 116 similar to what SQLite and BDB do in terms of committing using synchonized
 117 writes. To do this, we would have to use a much higher RAM footprint and some
 118 serious programming that make my head hurts just to think about it.
 119
 120 =cut
 121
 122 =head2 read_value( $obj, $key )
 123
 124 This takes an object that provides _base_offset() and a string. It returns the
 125 value stored in the corresponding Sector::Value's data section.
 126
 127 =cut
 128
 129 sub read_value { die "read_value must be implemented in a child class" }
 130
 131 =head2 get_classname( $obj )
 132
 133 This takes an object that provides _base_offset() and returns the classname (if
 134 any) associated with it.
 135
 136 It delegates to Sector::Reference::get_classname() for the heavy lifting.
 137
 138 It performs a staleness check.
 139
 140 =cut
 141
 142 sub get_classname { die "get_classname must be implemented in a child class" }
 143
 144 =head2 make_reference( $obj, $old_key, $new_key )
 145
 146 This takes an object that provides _base_offset() and two strings. The
 147 strings correspond to the old key and new key, respectively. This operation
 148 is equivalent to (given C<< $db->{foo} = []; >>) C<< $db->{bar} = $db->{foo} >>.
 149
 150 This returns nothing.
 151
 152 =cut
 153
 154 sub make_reference { die "make_reference must be implemented in a child class" }
 155
 156 =head2 key_exists( $obj, $key )
 157
 158 This takes an object that provides _base_offset() and a string for
 159 the key to be checked. This returns 1 for true and "" for false.
 160
 161 =cut
 162
 163 sub key_exists { die "key_exists must be implemented in a child class" }
 164
 165 =head2 delete_key( $obj, $key )
 166
 167 This takes an object that provides _base_offset() and a string for
 168 the key to be deleted. This returns the result of the Sector::Reference
 169 delete_key() method.
 170
 171 =cut
 172
 173 sub delete_key { die "delete_key must be implemented in a child class" }
 174
 175 =head2 write_value( $obj, $key, $value )
 176
 177 This takes an object that provides _base_offset(), a string for the
 178 key, and a value. This value can be anything storable within L<DBM::Deep/>.
 179
 180 This returns 1 upon success.
 181
 182 =cut
 183
 184 sub write_value { die "write_value must be implemented in a child class" }
 185
 186 =head2 setup( $obj )
 187
 188 This takes an object that provides _base_offset(). It will do everything needed
 189 in order to properly initialize all values for necessary functioning. If this is
 190 called upon an already initialized object, this will also reset the inode.
 191
 192 This returns 1.
 193
 194 =cut
 195
 196 sub setup { die "setup must be implemented in a child class" }
 197
 198 =head2 begin_work( $obj )
 199
 200 This takes an object that provides _base_offset(). It will set up all necessary
 201 bookkeeping in order to run all work within a transaction.
 202
 203 If $obj is already within a transaction, an error wiill be thrown. If there are
 204 no more available transactions, an error will be thrown.
 205
 206 This returns undef.
 207
 208 =cut
 209
 210 sub begin_work { die "begin_work must be implemented in a child class" }
 211
 212 =head2 rollback( $obj )
 213
 214 This takes an object that provides _base_offset(). It will revert all
 215 actions taken within the running transaction.
 216
 217 If $obj is not within a transaction, an error will be thrown.
 218
 219 This returns 1.
 220
 221 =cut
 222
 223 sub rollback { die "rollback must be implemented in a child class" }
 224
 225 =head2 commit( $obj )
 226
 227 This takes an object that provides _base_offset(). It will apply all
 228 actions taken within the transaction to the HEAD.
 229
 230 If $obj is not within a transaction, an error will be thrown.
 231
 232 This returns 1.
 233
 234 =cut
 235
 236 sub commit { die "commit must be implemented in a child class" }
 237
 238 =head2 get_next_key( $obj, $prev_key )
 239
 240 This takes an object that provides _base_offset() and an optional string
 241 representing the prior key returned via a prior invocation of this method.
 242
 243 This method delegates to C<< DBM::Deep::Iterator->get_next_key() >>.
 244
 245 =cut
 246
 247 # XXX Add staleness here
 248 sub get_next_key {
 249     my $self = shift;
 250     my ($obj, $prev_key) = @_;
 251
 252     # XXX Need to add logic about resetting the iterator if any key in the
 253     # reference has changed
 254     unless ( $prev_key ) {
 255         $obj->{iterator} = DBM::Deep::Iterator->new({
 256             base_offset => $obj->_base_offset,
 257             engine      => $self,
 258         });
 259     }
 260
 261     return $obj->{iterator}->get_next_key( $obj );
 262 }
 263
 264 =head2 lock_exclusive()
 265
 266 This takes an object that provides _base_offset(). It will guarantee that
 267 the storage has taken precautions to be safe for a write.
 268
 269 This returns nothing.
 270
 271 =cut
 272
 273 sub lock_exclusive {
 274     my $self = shift;
 275     my ($obj) = @_;
 276     return $self->storage->lock_exclusive( $obj );
 277 }
 278
 279 =head2 lock_shared()
 280
 281 This takes an object that provides _base_offset(). It will guarantee that
 282 the storage has taken precautions to be safe for a read.
 283
 284 This returns nothing.
 285
 286 =cut
 287
 288 sub lock_shared {
 289     my $self = shift;
 290     my ($obj) = @_;
 291     return $self->storage->lock_shared( $obj );
 292 }
 293
 294 =head2 unlock()
 295
 296 This takes an object that provides _base_offset(). It will guarantee that
 297 the storage has released the most recently-taken lock.
 298
 299 This returns nothing.
 300
 301 =cut
 302
 303 sub unlock {
 304     my $self = shift;
 305     my ($obj) = @_;
 306
 307     my $rv = $self->storage->unlock( $obj );
 308
 309     $self->flush if $rv;
 310
 311     return $rv;
 312 }
 313
 314 =head1 INTERNAL METHODS
 315
 316 The following methods are internal-use-only to DBM::Deep::Engine and its
 317 child classes.
 318
 319 =cut
 320
 321 =head2 flush()
 322
 323 This takes no arguments. It will do everything necessary to flush all things to
 324 disk. This is usually called during unlock() and setup().
 325
 326 This returns nothing.
 327
 328 =cut
 329
 330 sub flush {
 331     my $self = shift;
 332
 333     # Why do we need to have the storage flush? Shouldn't autoflush take care of
 334     # things? -RobK, 2008-06-26
 335     $self->storage->flush;
 336
 337     return;
 338 }
 339
 340 1;
 341 __END__