blib/lib/DBM/Deep/Engine.pm

filter: Statementstmt 81.2% 52 / 64 Branchbran 100% 12 / 12 Conditioncond 75.0% 3 / 4 MC/DCmcdc 50.0% 1 / 2 Subroutinesub 55.5% 15 / 27 Podpod 100% 21 / 21 totaltotal 80.0% 104 / 130 CC 9 SCAR 8.7
CC
9
Cov
84%
_descend
6.0
cache
2.1
read_value
2.0
CRAP 2.4
« blib/lib/DBM/Deep/Hash.pm ↑ Summary blib/lib/DBM/Deep.pm »
1 package DBM::Deep::Engine;
2  
3 48 ▶use 5.006_000;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 48 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 48 ▶use warnings FATAL => 'all';
Subroutine BEGIN: called CC=1 SCAR=0.0
7 48 ▶no warnings 'recursion';
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 48 ▶use DBM::Deep::Iterator ();
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 # File-wide notes:
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
15 # been done.
16  
17 sub SIG_HASH () { 'H' }
18 sub SIG_ARRAY () { 'A' }
19  
20 =head1 NAME
21  
22 DBM::Deep::Engine
23  
24 =head1 PURPOSE
25  
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.
28  
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.
32  
33 =head1 OVERVIEW
34  
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
37 is the following:
38  
39 =over 4
40  
41 =item * new
42  
43 =item * read_value
44  
45 =item * get_classname
46  
47 =item * make_reference
48  
49 =item * key_exists
50  
51 =item * delete_key
52  
53 =item * write_value
54  
55 =item * get_next_key
56  
57 =item * setup
58  
59 =item * begin_work
60  
61 =item * commit
62  
63 =item * rollback
64  
65 =item * lock_exclusive
66  
67 =item * lock_shared
68  
69 =item * unlock
70  
71 =back
72  
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.
76  
77 =head1 TRANSACTIONS
78  
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
82 with only one file.
83  
84 =head2 STALENESS
85  
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
92 and discard it.
93  
94 =head2 DURABILITY
95  
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.)
105  
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.
111  
112 =cut
113  
114 =head2 read_value( $obj, $key )
115  
116 This takes an object that provides _base_offset() and a string. It returns the
117 value stored in the corresponding Sector::Value's data section.
118  
119 =cut
120  
121 0 ▶sub read_value { die "read_value must be implemented in a child class" }
Subroutine read_value: not called CC=1 SCAR=6.9
Pod documented
122  
123 =head2 get_classname( $obj )
124  
125 This takes an object that provides _base_offset() and returns the classname (if
126 any) associated with it.
127  
128 It delegates to Sector::Reference::get_classname() for the heavy lifting.
129  
130 It performs a staleness check.
131  
132 =cut
133  
134 0 ▶sub get_classname { die "get_classname must be implemented in a child class" }
Subroutine get_classname: not called CC=1 SCAR=6.9
Pod documented
135  
136 =head2 make_reference( $obj, $old_key, $new_key )
137  
138 This takes an object that provides _base_offset() and two strings. The
139 strings correspond to the old key and new key, respectively. This operation
140 is equivalent to (given C<< $db->{foo} = []; >>) C<< $db->{bar} = $db->{foo} >>.
141  
142 This returns nothing.
143  
144 =cut
145  
146 0 ▶sub make_reference { die "make_reference must be implemented in a child class" }
Subroutine make_reference: not called CC=1 SCAR=6.9
Pod documented
147  
148 =head2 key_exists( $obj, $key )
149  
150 This takes an object that provides _base_offset() and a string for
151 the key to be checked. This returns 1 for true and "" for false.
152  
153 =cut
154  
155 0 ▶sub key_exists { die "key_exists must be implemented in a child class" }
Subroutine key_exists: not called CC=1 SCAR=6.9
Pod documented
156  
157 =head2 delete_key( $obj, $key )
158  
159 This takes an object that provides _base_offset() and a string for
160 the key to be deleted. This returns the result of the Sector::Reference
161 delete_key() method.
162  
163 =cut
164  
165 0 ▶sub delete_key { die "delete_key must be implemented in a child class" }
Subroutine delete_key: not called CC=1 SCAR=6.9
Pod documented
166  
167 =head2 write_value( $obj, $key, $value )
168  
169 This takes an object that provides _base_offset(), a string for the
170 key, and a value. This value can be anything storable within L<DBM::Deep>.
171  
172 This returns 1 upon success.
173  
174 =cut
175  
176 0 ▶sub write_value { die "write_value must be implemented in a child class" }
Subroutine write_value: not called CC=1 SCAR=6.9
Pod documented
177  
178 =head2 setup( $obj )
179  
180 This takes an object that provides _base_offset(). It will do everything needed
181 in order to properly initialize all values for necessary functioning. If this is
182 called upon an already initialized object, this will also reset the inode.
183  
184 This returns 1.
185  
186 =cut
187  
188 0 ▶sub setup { die "setup must be implemented in a child class" }
Subroutine setup: not called CC=1 SCAR=6.9
Pod documented
189  
190 =head2 begin_work( $obj )
191  
192 This takes an object that provides _base_offset(). It will set up all necessary
193 bookkeeping in order to run all work within a transaction.
194  
195 If $obj is already within a transaction, an error wiill be thrown. If there are
196 no more available transactions, an error will be thrown.
197  
198 This returns undef.
199  
200 =cut
201  
202 0 ▶sub begin_work { die "begin_work must be implemented in a child class" }
Subroutine begin_work: not called CC=1 SCAR=6.9
Pod documented
203  
204 =head2 rollback( $obj )
205  
206 This takes an object that provides _base_offset(). It will revert all
207 actions taken within the running transaction.
208  
209 If $obj is not within a transaction, an error will be thrown.
210  
211 This returns 1.
212  
213 =cut
214  
215 0 ▶sub rollback { die "rollback must be implemented in a child class" }
Subroutine rollback: not called CC=1 SCAR=6.9
Pod documented
216  
217 =head2 commit( $obj )
218  
219 This takes an object that provides _base_offset(). It will apply all
220 actions taken within the transaction to the HEAD.
221  
222 If $obj is not within a transaction, an error will be thrown.
223  
224 This returns 1.
225  
226 =cut
227  
228 0 ▶sub commit { die "commit must be implemented in a child class" }
Subroutine commit: not called CC=1 SCAR=6.9
Pod documented
229  
230 =head2 get_next_key( $obj, $prev_key )
231  
232 This takes an object that provides _base_offset() and an optional string
233 representing the prior key returned via a prior invocation of this method.
234  
235 This method delegates to C<< DBM::Deep::Iterator->get_next_key() >>.
236  
237 =cut
238  
239 # XXX Add staleness here
240 sub get_next_key {
241 531 ▶ my $self = shift;
Subroutine get_next_key: called CC=2 SCAR=6.9
Pod documented
242 531 my ($obj, $prev_key) = @_;
243  
244 # XXX Need to add logic about resetting the iterator if any key in the
245 # reference has changed
246 531 ▶ unless ( defined $prev_key ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $prev_key) 153 378 531
247 153 $obj->{iterator} = $self->iterator_class->new({
248 base_offset => $obj->_base_offset,
249 engine => $self,
250 });
251 }
252  
253 531 return $obj->{iterator}->get_next_key( $obj );
254 }
255  
256 =head2 lock_exclusive()
257  
258 This takes an object that provides _base_offset(). It will guarantee that
259 the storage has taken precautions to be safe for a write.
260  
261 This returns nothing.
262  
263 =cut
264  
265 sub lock_exclusive {
266 5616 ▶ my $self = shift;
Subroutine lock_exclusive: called CC=1 SCAR=0.0
Pod documented
267 5616 my ($obj) = @_;
268 5616 return $self->storage->lock_exclusive( $obj );
269 }
270  
271 =head2 lock_shared()
272  
273 This takes an object that provides _base_offset(). It will guarantee that
274 the storage has taken precautions to be safe for a read.
275  
276 This returns nothing.
277  
278 =cut
279  
280 sub lock_shared {
281 4433 ▶ my $self = shift;
Subroutine lock_shared: called CC=1 SCAR=0.0
Pod documented
282 4433 my ($obj) = @_;
283 4433 return $self->storage->lock_shared( $obj );
284 }
285  
286 =head2 unlock()
287  
288 This takes an object that provides _base_offset(). It will guarantee that
289 the storage has released the most recently-taken lock.
290  
291 This returns nothing.
292  
293 =cut
294  
295 sub unlock {
296 10050 ▶ my $self = shift;
Subroutine unlock: called CC=2 SCAR=6.9
Pod documented
297 10050 my ($obj) = @_;
298  
299 10050 my $rv = $self->storage->unlock( $obj );
300  
301 10050 ▶ $self->flush if $rv;
Branch: 1 branch
BranchTrueFalseTotal
if $rv 5412 4638 10050
302  
303 10050 return $rv;
304 }
305  
306 =head1 INTERNAL METHODS
307  
308 The following methods are internal-use-only to DBM::Deep::Engine and its
309 child classes.
310  
311 =cut
312  
313 =head2 flush()
314  
315 This takes no arguments. It will do everything necessary to flush all things to
316 disk. This is usually called during unlock() and setup().
317  
318 This returns nothing.
319  
320 =cut
321  
322 sub flush {
323 5412 ▶ my $self = shift;
Subroutine flush: called CC=1 SCAR=0.0
Pod documented
324  
325 # Why do we need to have the storage flush? Shouldn't autoflush take care of
326 # things? -RobK, 2008-06-26
327 5412 $self->storage->flush;
328  
329 5412 return;
330 }
331  
332 =head2 load_sector( $loc )
333  
334 This takes an id/location/offset and loads the sector based on the engine's
335 defined sector type.
336  
337 =cut
338  
339 22546 ▶sub load_sector { $_[0]->sector_type->load( @_ ) }
Subroutine load_sector: called CC=1 SCAR=0.0
Pod documented
340  
341 =head2 clear
342  
343 =cut
344  
345 =head2 clear( $obj )
346  
347 This takes an object that provides _base_offset() and deletes all its
348 elements, returning nothing.
349  
350 =cut
351  
352 =head2 cache / clear_cache
353  
354 This is the cache of loaded Reference sectors.
355  
356 =cut
357  
358 2 ▶sub cache { $_[0]{cache} ||= {} }
Subroutine cache: called CC=2 SCAR=7.6
Pod documented
Condition50%1/2
$_[0]{"cache"} ||= {}
l!l
02
MC/DC0%0/1
$_[0]{"cache"} ||= {}
$_[0]{"cache"}
Truth table50%1/2
A
A= $_[0]{"cache"}
Aresult
11
00
359 2 ▶sub clear_cache { %{$_[0]->cache} = () }
Subroutine clear_cache: called CC=1 SCAR=0.0
Pod documented
360  
361 =head2 supports( $option )
362  
363 This returns a boolean depending on if this instance of DBM::Dep supports
364 that feature. C<$option> can be one of:
365  
366 =over 4
367  
368 =item * transactions
369  
370 =item * singletons
371  
372 =back
373  
374 Any other value will return false.
375  
376 =cut
377  
378 0 ▶sub supports { die "supports must be implemented in a child class" }
Subroutine supports: not called CC=1 SCAR=6.9
Pod documented
379  
380 =head2 ACCESSORS
381  
382 The following are readonly attributes.
383  
384 =over 4
385  
386 =item * storage
387  
388 =item * sector_type
389  
390 =back
391  
392 =cut
393  
394 182075 ▶sub storage { $_[0]{storage} }
Subroutine storage: called CC=1 SCAR=0.0
Pod documented
395  
396 0 ▶sub sector_type { die "sector_type must be implemented in a child class" }
Subroutine sector_type: not called CC=1 SCAR=6.9
Pod documented
397  
398 # This code is to make sure we write all the values in the $value to the
399 # disk and to make sure all changes to $value after the assignment are
400 # reflected on disk. This may be counter-intuitive at first, but it is
401 # correct dwimmery.
402 # NOTE - simply tying $value won't perform a STORE on each value. Hence,
403 # the copy to a temp value.
404 sub _descend {
405 705 ▶ my $self = shift;
Subroutine _descend: called CC=6 SCAR=17.9
406 705 my ($value, $value_sector) = @_;
407 705 ▶ my $r = Scalar::Util::reftype( $value ) || '';
Condition100%2/2
builtin::reftype($value) || ''
l!l
192513
MC/DC100%1/1
builtin::reftype($value) || ''
builtin::reftype($value)
Truth table100%2/2
A
A= builtin::reftype($value)
Aresult
11
00
408  
409 705 ▶ if ( $r eq 'ARRAY' ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($r eq 'ARRAY') { } 38 667 705
elsif ($r eq 'HASH') { } 154 513 667
410 38 my @temp = @$value;
411 38 tie @$value, 'DBM::Deep', {
412 base_offset => $value_sector->offset,
413 staleness => $value_sector->staleness,
414 storage => $self->storage,
415 engine => $self,
416 };
417 38 @$value = @temp;
418 38 ▶ bless $value, 'DBM::Deep::Array' unless Scalar::Util::blessed( $value );
Branch: 1 branch
BranchTrueFalseTotal
unless builtin::blessed($value) 26 12 38
419 }
420 elsif ( $r eq 'HASH' ) {
421 154 my %temp = %$value;
422 154 tie %$value, 'DBM::Deep', {
423 base_offset => $value_sector->offset,
424 staleness => $value_sector->staleness,
425 storage => $self->storage,
426 engine => $self,
427 };
428 154 %$value = %temp;
429 154 ▶ bless $value, 'DBM::Deep::Hash' unless Scalar::Util::blessed( $value );
Branch: 1 branch
BranchTrueFalseTotal
unless builtin::blessed($value) 144 10 154
430 }
431  
432 705 return;
433 }
434  
435 48 1;
436 __END__
« blib/lib/DBM/Deep/Hash.pm ↑ Summary blib/lib/DBM/Deep.pm »