1 package DBM::Deep::Engine;
6 use warnings FATAL => 'all';
8 use DBM::Deep::Iterator ();
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
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' }
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.
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.
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
55 =item * make_reference
73 =item * lock_exclusive
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.
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
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
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.)
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.
122 =head2 read_value( $obj, $key )
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.
129 sub read_value { die "read_value must be implemented in a child class" }
131 =head2 get_classname( $obj )
133 This takes an object that provides _base_offset() and returns the classname (if
134 any) associated with it.
136 It delegates to Sector::Reference::get_classname() for the heavy lifting.
138 It performs a staleness check.
142 sub get_classname { die "get_classname must be implemented in a child class" }
144 =head2 make_reference( $obj, $old_key, $new_key )
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} >>.
150 This returns nothing.
154 sub make_reference { die "make_reference must be implemented in a child class" }
156 =head2 key_exists( $obj, $key )
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.
163 sub key_exists { die "key_exists must be implemented in a child class" }
165 =head2 delete_key( $obj, $key )
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
173 sub delete_key { die "delete_key must be implemented in a child class" }
175 =head2 write_value( $obj, $key, $value )
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/>.
180 This returns 1 upon success.
184 sub write_value { die "write_value must be implemented in a child class" }
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.
196 sub setup { die "setup must be implemented in a child class" }
198 =head2 begin_work( $obj )
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.
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.
210 sub begin_work { die "begin_work must be implemented in a child class" }
212 =head2 rollback( $obj )
214 This takes an object that provides _base_offset(). It will revert all
215 actions taken within the running transaction.
217 If $obj is not within a transaction, an error will be thrown.
223 sub rollback { die "rollback must be implemented in a child class" }
225 =head2 commit( $obj )
227 This takes an object that provides _base_offset(). It will apply all
228 actions taken within the transaction to the HEAD.
230 If $obj is not within a transaction, an error will be thrown.
236 sub commit { die "commit must be implemented in a child class" }
238 =head2 get_next_key( $obj, $prev_key )
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.
243 This method delegates to C<< DBM::Deep::Iterator->get_next_key() >>.
247 # XXX Add staleness here
250 my ($obj, $prev_key) = @_;
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,
261 return $obj->{iterator}->get_next_key( $obj );
264 =head2 lock_exclusive()
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.
269 This returns nothing.
276 return $self->storage->lock_exclusive( $obj );
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.
284 This returns nothing.
291 return $self->storage->lock_shared( $obj );
296 This takes an object that provides _base_offset(). It will guarantee that
297 the storage has released the most recently-taken lock.
299 This returns nothing.
307 my $rv = $self->storage->unlock( $obj );
314 =head1 INTERNAL METHODS
316 The following methods are internal-use-only to DBM::Deep::Engine and its
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().
326 This returns nothing.
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;
340 =head2 load_sector( $loc )
342 This takes an id/location/offset and loads the sector based on the engine's
347 sub load_sector { $_[0]->sector_type->load( @_ ) }
351 The following are readonly attributes.
361 sub storage { $_[0]{storage} }
363 sub sector_type { die "sector_type must be implemented in a child class" }