1 package DBM::Deep::Engine;
6 use warnings FATAL => 'all';
8 our $VERSION = $DBM::Deep::VERSION;
10 use DBM::Deep::Iterator ();
13 # * Every method in here assumes that the storage has been appropriately
14 # safeguarded. This can be anything from flock() to some sort of manual
15 # mutex. But, it's the caller's responsability to make sure that this has
18 sub SIG_HASH () { 'H' }
19 sub SIG_ARRAY () { 'A' }
27 This is an internal-use-only object for L<DBM::Deep>. It mediates the low-level
28 mapping between the L<DBM::Deep> objects and the storage medium.
30 The purpose of this documentation is to provide low-level documentation for
31 developers. It is B<not> intended to be used by the general public. This
32 documentation and what it documents can and will change without notice.
36 The engine exposes an API to the DBM::Deep objects (DBM::Deep, DBM::Deep::Array,
37 and DBM::Deep::Hash) for their use to access the actual stored values. This API
48 =item * make_reference
66 =item * lock_exclusive
74 They are explained in their own sections below. These methods, in turn, may
75 provide some bounds-checking, but primarily act to instantiate objects in the
76 Engine::Sector::* hierarchy and dispatch to them.
80 Transactions in DBM::Deep are implemented using a variant of MVCC. This attempts
81 to keep the amount of actual work done against the file low while stil providing
82 Atomicity, Consistency, and Isolation. Durability, unfortunately, cannot be done
87 If another process uses a transaction slot and writes stuff to it, then
88 terminates, the data that process wrote it still within the file. In order to
89 address this, there is also a transaction staleness counter associated within
90 every write. Each time a transaction is started, that process increments that
91 transaction's staleness counter. If, when it reads a value, the staleness
92 counters aren't identical, DBM::Deep will consider the value on disk to be stale
97 The fourth leg of ACID is Durability, the guarantee that when a commit returns,
98 the data will be there the next time you read from it. This should be regardless
99 of any crashes or powerdowns in between the commit and subsequent read.
100 DBM::Deep does provide that guarantee; once the commit returns, all of the data
101 has been transferred from the transaction shadow to the HEAD. The issue arises
102 with partial commits - a commit that is interrupted in some fashion. In keeping
103 with DBM::Deep's "tradition" of very light error-checking and non-existent
104 error-handling, there is no way to recover from a partial commit. (This is
105 probably a failure in Consistency as well as Durability.)
107 Other DBMSes use transaction logs (a separate file, generally) to achieve
108 Durability. As DBM::Deep is a single-file, we would have to do something
109 similar to what SQLite and BDB do in terms of committing using synchonized
110 writes. To do this, we would have to use a much higher RAM footprint and some
111 serious programming that make my head hurts just to think about it.
115 =head2 read_value( $obj, $key )
117 This takes an object that provides _base_offset() and a string. It returns the
118 value stored in the corresponding Sector::Value's data section.
122 sub read_value { die "read_value must be implemented in a child class" }
124 =head2 get_classname( $obj )
126 This takes an object that provides _base_offset() and returns the classname (if
127 any) associated with it.
129 It delegates to Sector::Reference::get_classname() for the heavy lifting.
131 It performs a staleness check.
135 sub get_classname { die "get_classname must be implemented in a child class" }
137 =head2 make_reference( $obj, $old_key, $new_key )
139 This takes an object that provides _base_offset() and two strings. The
140 strings correspond to the old key and new key, respectively. This operation
141 is equivalent to (given C<< $db->{foo} = []; >>) C<< $db->{bar} = $db->{foo} >>.
143 This returns nothing.
147 sub make_reference { die "make_reference must be implemented in a child class" }
149 =head2 key_exists( $obj, $key )
151 This takes an object that provides _base_offset() and a string for
152 the key to be checked. This returns 1 for true and "" for false.
156 sub key_exists { die "key_exists must be implemented in a child class" }
158 =head2 delete_key( $obj, $key )
160 This takes an object that provides _base_offset() and a string for
161 the key to be deleted. This returns the result of the Sector::Reference
166 sub delete_key { die "delete_key must be implemented in a child class" }
168 =head2 write_value( $obj, $key, $value )
170 This takes an object that provides _base_offset(), a string for the
171 key, and a value. This value can be anything storable within L<DBM::Deep>.
173 This returns 1 upon success.
177 sub write_value { die "write_value must be implemented in a child class" }
181 This takes an object that provides _base_offset(). It will do everything needed
182 in order to properly initialize all values for necessary functioning. If this is
183 called upon an already initialized object, this will also reset the inode.
189 sub setup { die "setup must be implemented in a child class" }
191 =head2 begin_work( $obj )
193 This takes an object that provides _base_offset(). It will set up all necessary
194 bookkeeping in order to run all work within a transaction.
196 If $obj is already within a transaction, an error wiill be thrown. If there are
197 no more available transactions, an error will be thrown.
203 sub begin_work { die "begin_work must be implemented in a child class" }
205 =head2 rollback( $obj )
207 This takes an object that provides _base_offset(). It will revert all
208 actions taken within the running transaction.
210 If $obj is not within a transaction, an error will be thrown.
216 sub rollback { die "rollback must be implemented in a child class" }
218 =head2 commit( $obj )
220 This takes an object that provides _base_offset(). It will apply all
221 actions taken within the transaction to the HEAD.
223 If $obj is not within a transaction, an error will be thrown.
229 sub commit { die "commit must be implemented in a child class" }
231 =head2 get_next_key( $obj, $prev_key )
233 This takes an object that provides _base_offset() and an optional string
234 representing the prior key returned via a prior invocation of this method.
236 This method delegates to C<< DBM::Deep::Iterator->get_next_key() >>.
240 # XXX Add staleness here
243 my ($obj, $prev_key) = @_;
245 # XXX Need to add logic about resetting the iterator if any key in the
246 # reference has changed
247 unless ( defined $prev_key ) {
248 $obj->{iterator} = $self->iterator_class->new({
249 base_offset => $obj->_base_offset,
254 return $obj->{iterator}->get_next_key( $obj );
257 =head2 lock_exclusive()
259 This takes an object that provides _base_offset(). It will guarantee that
260 the storage has taken precautions to be safe for a write.
262 This returns nothing.
269 return $self->storage->lock_exclusive( $obj );
274 This takes an object that provides _base_offset(). It will guarantee that
275 the storage has taken precautions to be safe for a read.
277 This returns nothing.
284 return $self->storage->lock_shared( $obj );
289 This takes an object that provides _base_offset(). It will guarantee that
290 the storage has released the most recently-taken lock.
292 This returns nothing.
300 my $rv = $self->storage->unlock( $obj );
307 =head1 INTERNAL METHODS
309 The following methods are internal-use-only to DBM::Deep::Engine and its
316 This takes no arguments. It will do everything necessary to flush all things to
317 disk. This is usually called during unlock() and setup().
319 This returns nothing.
326 # Why do we need to have the storage flush? Shouldn't autoflush take care of
327 # things? -RobK, 2008-06-26
328 $self->storage->flush;
333 =head2 load_sector( $loc )
335 This takes an id/location/offset and loads the sector based on the engine's
340 sub load_sector { $_[0]->sector_type->load( @_ ) }
342 =head2 cache / clear_cache
344 This is the cache of loaded Reference sectors.
348 sub cache { $_[0]{cache} ||= {} }
349 sub clear_cache { %{$_[0]->cache} = () }
351 =head2 supports( $option )
353 This returns a boolean depending on if this instance of DBM::Dep supports
354 that feature. C<$option> can be one of:
364 sub supports { die "supports must be implemented in a child class" }
368 The following are readonly attributes.
380 sub storage { $_[0]{storage} }
382 sub sector_type { die "sector_type must be implemented in a child class" }