1 package DBM::Deep::Engine;
6 use warnings FATAL => 'all';
7 no warnings 'recursion';
9 use DBM::Deep::Iterator ();
12 # * Every method in here assumes that the storage has been appropriately
13 # safeguarded. This can be anything from flock() to some sort of manual
14 # mutex. But, it's the caller's responsability to make sure that this has
17 sub SIG_HASH () { 'H' }
18 sub SIG_ARRAY () { 'A' }
26 This is an internal-use-only object for L<DBM::Deep>. It mediates the low-level
27 mapping between the L<DBM::Deep> objects and the storage medium.
29 The purpose of this documentation is to provide low-level documentation for
30 developers. It is B<not> intended to be used by the general public. This
31 documentation and what it documents can and will change without notice.
35 The engine exposes an API to the DBM::Deep objects (DBM::Deep, DBM::Deep::Array,
36 and DBM::Deep::Hash) for their use to access the actual stored values. This API
47 =item * make_reference
65 =item * lock_exclusive
73 They are explained in their own sections below. These methods, in turn, may
74 provide some bounds-checking, but primarily act to instantiate objects in the
75 Engine::Sector::* hierarchy and dispatch to them.
79 Transactions in DBM::Deep are implemented using a variant of MVCC. This attempts
80 to keep the amount of actual work done against the file low while stil providing
81 Atomicity, Consistency, and Isolation. Durability, unfortunately, cannot be done
86 If another process uses a transaction slot and writes stuff to it, then
87 terminates, the data that process wrote it still within the file. In order to
88 address this, there is also a transaction staleness counter associated within
89 every write. Each time a transaction is started, that process increments that
90 transaction's staleness counter. If, when it reads a value, the staleness
91 counters aren't identical, DBM::Deep will consider the value on disk to be stale
96 The fourth leg of ACID is Durability, the guarantee that when a commit returns,
97 the data will be there the next time you read from it. This should be regardless
98 of any crashes or powerdowns in between the commit and subsequent read.
99 DBM::Deep does provide that guarantee; once the commit returns, all of the data
100 has been transferred from the transaction shadow to the HEAD. The issue arises
101 with partial commits - a commit that is interrupted in some fashion. In keeping
102 with DBM::Deep's "tradition" of very light error-checking and non-existent
103 error-handling, there is no way to recover from a partial commit. (This is
104 probably a failure in Consistency as well as Durability.)
106 Other DBMSes use transaction logs (a separate file, generally) to achieve
107 Durability. As DBM::Deep is a single-file, we would have to do something
108 similar to what SQLite and BDB do in terms of committing using synchonized
109 writes. To do this, we would have to use a much higher RAM footprint and some
110 serious programming that make my head hurts just to think about it.
116 =head2 read_value( $obj, $key )
118 This takes an object that provides _base_offset() and a string. It returns the
119 value stored in the corresponding Sector::Value's data section.
123 sub read_value { die "read_value must be implemented in a child class" }
125 =head2 get_classname( $obj )
127 This takes an object that provides _base_offset() and returns the classname (if
128 any) associated with it.
130 It delegates to Sector::Reference::get_classname() for the heavy lifting.
132 It performs a staleness check.
136 sub get_classname { die "get_classname must be implemented in a child class" }
138 =head2 make_reference( $obj, $old_key, $new_key )
140 This takes an object that provides _base_offset() and two strings. The
141 strings correspond to the old key and new key, respectively. This operation
142 is equivalent to (given C<< $db->{foo} = []; >>) C<< $db->{bar} = $db->{foo} >>.
144 This returns nothing.
148 sub make_reference { die "make_reference must be implemented in a child class" }
150 =head2 key_exists( $obj, $key )
152 This takes an object that provides _base_offset() and a string for
153 the key to be checked. This returns 1 for true and "" for false.
157 sub key_exists { die "key_exists must be implemented in a child class" }
159 =head2 delete_key( $obj, $key )
161 This takes an object that provides _base_offset() and a string for
162 the key to be deleted. This returns the result of the Sector::Reference
167 sub delete_key { die "delete_key must be implemented in a child class" }
169 =head2 write_value( $obj, $key, $value )
171 This takes an object that provides _base_offset(), a string for the
172 key, and a value. This value can be anything storable within L<DBM::Deep>.
174 This returns 1 upon success.
178 sub write_value { die "write_value must be implemented in a child class" }
182 This takes an object that provides _base_offset(). It will do everything needed
183 in order to properly initialize all values for necessary functioning. If this is
184 called upon an already initialized object, this will also reset the inode.
190 sub setup { die "setup must be implemented in a child class" }
192 =head2 begin_work( $obj )
194 This takes an object that provides _base_offset(). It will set up all necessary
195 bookkeeping in order to run all work within a transaction.
197 If $obj is already within a transaction, an error wiill be thrown. If there are
198 no more available transactions, an error will be thrown.
204 sub begin_work { die "begin_work must be implemented in a child class" }
206 =head2 rollback( $obj )
208 This takes an object that provides _base_offset(). It will revert all
209 actions taken within the running transaction.
211 If $obj is not within a transaction, an error will be thrown.
217 sub rollback { die "rollback must be implemented in a child class" }
219 =head2 commit( $obj )
221 This takes an object that provides _base_offset(). It will apply all
222 actions taken within the transaction to the HEAD.
224 If $obj is not within a transaction, an error will be thrown.
230 sub commit { die "commit must be implemented in a child class" }
232 =head2 get_next_key( $obj, $prev_key )
234 This takes an object that provides _base_offset() and an optional string
235 representing the prior key returned via a prior invocation of this method.
237 This method delegates to C<< DBM::Deep::Iterator->get_next_key() >>.
241 # XXX Add staleness here
244 my ($obj, $prev_key) = @_;
246 # XXX Need to add logic about resetting the iterator if any key in the
247 # reference has changed
248 unless ( defined $prev_key ) {
249 eval "use " . $self->iterator_class; die $@ if $@;
250 $obj->{iterator} = $self->iterator_class->new({
251 base_offset => $obj->_base_offset,
256 return $obj->{iterator}->get_next_key( $obj );
259 =head2 lock_exclusive()
261 This takes an object that provides _base_offset(). It will guarantee that
262 the storage has taken precautions to be safe for a write.
264 This returns nothing.
271 return $self->storage->lock_exclusive( $obj );
276 This takes an object that provides _base_offset(). It will guarantee that
277 the storage has taken precautions to be safe for a read.
279 This returns nothing.
286 return $self->storage->lock_shared( $obj );
291 This takes an object that provides _base_offset(). It will guarantee that
292 the storage has released the most recently-taken lock.
294 This returns nothing.
302 my $rv = $self->storage->unlock( $obj );
309 =head1 INTERNAL METHODS
311 The following methods are internal-use-only to DBM::Deep::Engine and its
318 This takes no arguments. It will do everything necessary to flush all things to
319 disk. This is usually called during unlock() and setup().
321 This returns nothing.
328 # Why do we need to have the storage flush? Shouldn't autoflush take care of
329 # things? -RobK, 2008-06-26
330 $self->storage->flush;
335 =head2 load_sector( $loc )
337 This takes an id/location/offset and loads the sector based on the engine's
342 sub load_sector { $_[0]->sector_type->load( @_ ) }
346 This takes an object that provides _base_offset() and deletes all its
347 elements, returning nothing.
351 sub clear { die "clear must be implemented in a child class" }
353 =head2 cache / clear_cache
355 This is the cache of loaded Reference sectors.
359 sub cache { $_[0]{cache} ||= {} }
360 sub clear_cache { %{$_[0]->cache} = () }
362 =head2 supports( $option )
364 This returns a boolean depending on if this instance of DBM::Dep supports
365 that feature. C<$option> can be one of:
375 Any other value will return false.
379 sub supports { die "supports must be implemented in a child class" }
383 The following are readonly attributes.
391 =item * iterator_class
397 sub storage { $_[0]{storage} }
399 sub sector_type { die "sector_type must be implemented in a child class" }
400 sub iterator_class { die "iterator_class must be implemented in a child class" }
402 # This code is to make sure we write all the values in the $value to the
403 # disk and to make sure all changes to $value after the assignment are
404 # reflected on disk. This may be counter-intuitive at first, but it is
406 # NOTE - simply tying $value won't perform a STORE on each value. Hence,
407 # the copy to a temp value.
410 my ($value, $value_sector) = @_;
411 my $r = Scalar::Util::reftype( $value ) || '';
413 if ( $r eq 'ARRAY' ) {
415 tie @$value, 'DBM::Deep', {
416 base_offset => $value_sector->offset,
417 staleness => $value_sector->staleness,
418 storage => $self->storage,
422 bless $value, 'DBM::Deep::Array' unless Scalar::Util::blessed( $value );
424 elsif ( $r eq 'HASH' ) {
426 tie %$value, 'DBM::Deep', {
427 base_offset => $value_sector->offset,
428 staleness => $value_sector->staleness,
429 storage => $self->storage,
433 bless $value, 'DBM::Deep::Hash' unless Scalar::Util::blessed( $value );