Commit | Line | Data |
bf941eae |
1 | package DBM::Deep::Engine; |
2 | |
3 | use 5.006_000; |
4 | |
5 | use strict; |
6 | use warnings FATAL => 'all'; |
8385c429 |
7 | no warnings 'recursion'; |
29460253 |
8 | |
bf941eae |
9 | use DBM::Deep::Iterator (); |
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 | |
a4d36ff6 |
17 | sub SIG_HASH () { 'H' } |
18 | sub SIG_ARRAY () { 'A' } |
19 | |
64a531e5 |
20 | =head1 NAME |
21 | |
22 | DBM::Deep::Engine |
23 | |
24 | =head1 PURPOSE |
25 | |
1c62d370 |
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. |
64a531e5 |
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 | |
f4d0ac97 |
57 | =item * setup |
64a531e5 |
58 | |
24b0b7b9 |
59 | =item * clear |
ae6c15b8 |
60 | |
64a531e5 |
61 | =item * begin_work |
62 | |
63 | =item * commit |
64 | |
65 | =item * rollback |
66 | |
67 | =item * lock_exclusive |
68 | |
69 | =item * lock_shared |
70 | |
71 | =item * unlock |
72 | |
73 | =back |
74 | |
75 | They are explained in their own sections below. These methods, in turn, may |
76 | provide some bounds-checking, but primarily act to instantiate objects in the |
77 | Engine::Sector::* hierarchy and dispatch to them. |
78 | |
79 | =head1 TRANSACTIONS |
80 | |
81 | Transactions in DBM::Deep are implemented using a variant of MVCC. This attempts |
82 | to keep the amount of actual work done against the file low while stil providing |
83 | Atomicity, Consistency, and Isolation. Durability, unfortunately, cannot be done |
84 | with only one file. |
85 | |
86 | =head2 STALENESS |
87 | |
88 | If another process uses a transaction slot and writes stuff to it, then |
89 | terminates, the data that process wrote it still within the file. In order to |
90 | address this, there is also a transaction staleness counter associated within |
91 | every write. Each time a transaction is started, that process increments that |
92 | transaction's staleness counter. If, when it reads a value, the staleness |
93 | counters aren't identical, DBM::Deep will consider the value on disk to be stale |
94 | and discard it. |
95 | |
96 | =head2 DURABILITY |
97 | |
98 | The fourth leg of ACID is Durability, the guarantee that when a commit returns, |
99 | the data will be there the next time you read from it. This should be regardless |
100 | of any crashes or powerdowns in between the commit and subsequent read. |
101 | DBM::Deep does provide that guarantee; once the commit returns, all of the data |
102 | has been transferred from the transaction shadow to the HEAD. The issue arises |
103 | with partial commits - a commit that is interrupted in some fashion. In keeping |
104 | with DBM::Deep's "tradition" of very light error-checking and non-existent |
105 | error-handling, there is no way to recover from a partial commit. (This is |
106 | probably a failure in Consistency as well as Durability.) |
107 | |
108 | Other DBMSes use transaction logs (a separate file, generally) to achieve |
109 | Durability. As DBM::Deep is a single-file, we would have to do something |
110 | similar to what SQLite and BDB do in terms of committing using synchonized |
111 | writes. To do this, we would have to use a much higher RAM footprint and some |
112 | serious programming that make my head hurts just to think about it. |
113 | |
114 | =cut |
115 | |
417f635b |
116 | =head1 METHODS |
117 | |
f4d0ac97 |
118 | =head2 read_value( $obj, $key ) |
64a531e5 |
119 | |
f4d0ac97 |
120 | This takes an object that provides _base_offset() and a string. It returns the |
121 | value stored in the corresponding Sector::Value's data section. |
122 | |
123 | =cut |
124 | |
125 | sub read_value { die "read_value must be implemented in a child class" } |
126 | |
127 | =head2 get_classname( $obj ) |
128 | |
129 | This takes an object that provides _base_offset() and returns the classname (if |
130 | any) associated with it. |
131 | |
132 | It delegates to Sector::Reference::get_classname() for the heavy lifting. |
133 | |
134 | It performs a staleness check. |
135 | |
136 | =cut |
137 | |
138 | sub get_classname { die "get_classname must be implemented in a child class" } |
139 | |
140 | =head2 make_reference( $obj, $old_key, $new_key ) |
141 | |
142 | This takes an object that provides _base_offset() and two strings. The |
143 | strings correspond to the old key and new key, respectively. This operation |
144 | is equivalent to (given C<< $db->{foo} = []; >>) C<< $db->{bar} = $db->{foo} >>. |
145 | |
146 | This returns nothing. |
147 | |
148 | =cut |
149 | |
150 | sub make_reference { die "make_reference must be implemented in a child class" } |
151 | |
152 | =head2 key_exists( $obj, $key ) |
153 | |
154 | This takes an object that provides _base_offset() and a string for |
155 | the key to be checked. This returns 1 for true and "" for false. |
156 | |
157 | =cut |
158 | |
159 | sub key_exists { die "key_exists must be implemented in a child class" } |
160 | |
161 | =head2 delete_key( $obj, $key ) |
162 | |
163 | This takes an object that provides _base_offset() and a string for |
164 | the key to be deleted. This returns the result of the Sector::Reference |
165 | delete_key() method. |
166 | |
167 | =cut |
168 | |
169 | sub delete_key { die "delete_key must be implemented in a child class" } |
170 | |
171 | =head2 write_value( $obj, $key, $value ) |
172 | |
173 | This takes an object that provides _base_offset(), a string for the |
1c62d370 |
174 | key, and a value. This value can be anything storable within L<DBM::Deep>. |
f4d0ac97 |
175 | |
176 | This returns 1 upon success. |
177 | |
178 | =cut |
179 | |
180 | sub write_value { die "write_value must be implemented in a child class" } |
181 | |
182 | =head2 setup( $obj ) |
183 | |
184 | This takes an object that provides _base_offset(). It will do everything needed |
185 | in order to properly initialize all values for necessary functioning. If this is |
186 | called upon an already initialized object, this will also reset the inode. |
187 | |
188 | This returns 1. |
189 | |
190 | =cut |
191 | |
192 | sub setup { die "setup must be implemented in a child class" } |
193 | |
194 | =head2 begin_work( $obj ) |
195 | |
196 | This takes an object that provides _base_offset(). It will set up all necessary |
197 | bookkeeping in order to run all work within a transaction. |
198 | |
199 | If $obj is already within a transaction, an error wiill be thrown. If there are |
200 | no more available transactions, an error will be thrown. |
201 | |
202 | This returns undef. |
203 | |
204 | =cut |
205 | |
206 | sub begin_work { die "begin_work must be implemented in a child class" } |
207 | |
208 | =head2 rollback( $obj ) |
209 | |
210 | This takes an object that provides _base_offset(). It will revert all |
211 | actions taken within the running transaction. |
212 | |
213 | If $obj is not within a transaction, an error will be thrown. |
214 | |
215 | This returns 1. |
216 | |
217 | =cut |
218 | |
219 | sub rollback { die "rollback must be implemented in a child class" } |
220 | |
221 | =head2 commit( $obj ) |
222 | |
223 | This takes an object that provides _base_offset(). It will apply all |
224 | actions taken within the transaction to the HEAD. |
225 | |
226 | If $obj is not within a transaction, an error will be thrown. |
227 | |
228 | This returns 1. |
229 | |
230 | =cut |
231 | |
232 | sub commit { die "commit must be implemented in a child class" } |
64a531e5 |
233 | |
bf941eae |
234 | =head2 get_next_key( $obj, $prev_key ) |
235 | |
236 | This takes an object that provides _base_offset() and an optional string |
237 | representing the prior key returned via a prior invocation of this method. |
238 | |
239 | This method delegates to C<< DBM::Deep::Iterator->get_next_key() >>. |
240 | |
241 | =cut |
242 | |
243 | # XXX Add staleness here |
244 | sub get_next_key { |
245 | my $self = shift; |
246 | my ($obj, $prev_key) = @_; |
247 | |
f4d0ac97 |
248 | # XXX Need to add logic about resetting the iterator if any key in the |
249 | # reference has changed |
0b3cba50 |
250 | unless ( defined $prev_key ) { |
417f635b |
251 | eval "use " . $self->iterator_class; die $@ if $@; |
19b913ce |
252 | $obj->{iterator} = $self->iterator_class->new({ |
bf941eae |
253 | base_offset => $obj->_base_offset, |
254 | engine => $self, |
255 | }); |
256 | } |
257 | |
258 | return $obj->{iterator}->get_next_key( $obj ); |
259 | } |
260 | |
f4d0ac97 |
261 | =head2 lock_exclusive() |
262 | |
263 | This takes an object that provides _base_offset(). It will guarantee that |
264 | the storage has taken precautions to be safe for a write. |
265 | |
266 | This returns nothing. |
267 | |
268 | =cut |
269 | |
270 | sub lock_exclusive { |
271 | my $self = shift; |
272 | my ($obj) = @_; |
273 | return $self->storage->lock_exclusive( $obj ); |
274 | } |
275 | |
276 | =head2 lock_shared() |
277 | |
278 | This takes an object that provides _base_offset(). It will guarantee that |
279 | the storage has taken precautions to be safe for a read. |
280 | |
281 | This returns nothing. |
282 | |
283 | =cut |
284 | |
285 | sub lock_shared { |
286 | my $self = shift; |
287 | my ($obj) = @_; |
288 | return $self->storage->lock_shared( $obj ); |
289 | } |
290 | |
291 | =head2 unlock() |
292 | |
293 | This takes an object that provides _base_offset(). It will guarantee that |
294 | the storage has released the most recently-taken lock. |
295 | |
296 | This returns nothing. |
297 | |
298 | =cut |
299 | |
300 | sub unlock { |
301 | my $self = shift; |
302 | my ($obj) = @_; |
303 | |
304 | my $rv = $self->storage->unlock( $obj ); |
305 | |
306 | $self->flush if $rv; |
307 | |
308 | return $rv; |
309 | } |
310 | |
311 | =head1 INTERNAL METHODS |
312 | |
313 | The following methods are internal-use-only to DBM::Deep::Engine and its |
314 | child classes. |
315 | |
316 | =cut |
317 | |
318 | =head2 flush() |
319 | |
320 | This takes no arguments. It will do everything necessary to flush all things to |
321 | disk. This is usually called during unlock() and setup(). |
322 | |
323 | This returns nothing. |
324 | |
325 | =cut |
326 | |
327 | sub flush { |
328 | my $self = shift; |
329 | |
330 | # Why do we need to have the storage flush? Shouldn't autoflush take care of |
331 | # things? -RobK, 2008-06-26 |
332 | $self->storage->flush; |
333 | |
334 | return; |
335 | } |
336 | |
d6ecf579 |
337 | =head2 load_sector( $loc ) |
338 | |
339 | This takes an id/location/offset and loads the sector based on the engine's |
340 | defined sector type. |
341 | |
342 | =cut |
343 | |
344 | sub load_sector { $_[0]->sector_type->load( @_ ) } |
345 | |
2ba14e04 |
346 | =head2 clear( $obj ) |
347 | |
348 | This takes an object that provides _base_offset() and deletes all its |
349 | elements, returning nothing. |
350 | |
351 | =cut |
352 | |
417f635b |
353 | sub clear { die "clear must be implemented in a child class" } |
354 | |
4f034d8f |
355 | =head2 cache / clear_cache |
356 | |
357 | This is the cache of loaded Reference sectors. |
358 | |
359 | =cut |
360 | |
361 | sub cache { $_[0]{cache} ||= {} } |
362 | sub clear_cache { %{$_[0]->cache} = () } |
363 | |
580e5ee2 |
364 | =head2 supports( $option ) |
365 | |
366 | This returns a boolean depending on if this instance of DBM::Dep supports |
367 | that feature. C<$option> can be one of: |
368 | |
369 | =over 4 |
370 | |
371 | =item * transactions |
372 | |
66285e35 |
373 | =item * singletons |
374 | |
580e5ee2 |
375 | =back |
376 | |
66285e35 |
377 | Any other value will return false. |
378 | |
580e5ee2 |
379 | =cut |
380 | |
381 | sub supports { die "supports must be implemented in a child class" } |
382 | |
417f635b |
383 | =head1 ACCESSORS |
d6ecf579 |
384 | |
385 | The following are readonly attributes. |
386 | |
387 | =over 4 |
388 | |
389 | =item * storage |
390 | |
4f034d8f |
391 | =item * sector_type |
392 | |
417f635b |
393 | =item * iterator_class |
394 | |
d6ecf579 |
395 | =back |
396 | |
397 | =cut |
398 | |
399 | sub storage { $_[0]{storage} } |
400 | |
401 | sub sector_type { die "sector_type must be implemented in a child class" } |
417f635b |
402 | sub iterator_class { die "iterator_class must be implemented in a child class" } |
d6ecf579 |
403 | |
c2472ede |
404 | # This code is to make sure we write all the values in the $value to the |
405 | # disk and to make sure all changes to $value after the assignment are |
406 | # reflected on disk. This may be counter-intuitive at first, but it is |
407 | # correct dwimmery. |
408 | # NOTE - simply tying $value won't perform a STORE on each value. Hence, |
409 | # the copy to a temp value. |
410 | sub _descend { |
411 | my $self = shift; |
412 | my ($value, $value_sector) = @_; |
413 | my $r = Scalar::Util::reftype( $value ) || ''; |
414 | |
415 | if ( $r eq 'ARRAY' ) { |
416 | my @temp = @$value; |
417 | tie @$value, 'DBM::Deep', { |
418 | base_offset => $value_sector->offset, |
419 | staleness => $value_sector->staleness, |
420 | storage => $self->storage, |
421 | engine => $self, |
422 | }; |
423 | @$value = @temp; |
424 | bless $value, 'DBM::Deep::Array' unless Scalar::Util::blessed( $value ); |
425 | } |
426 | elsif ( $r eq 'HASH' ) { |
427 | my %temp = %$value; |
428 | tie %$value, 'DBM::Deep', { |
429 | base_offset => $value_sector->offset, |
430 | staleness => $value_sector->staleness, |
431 | storage => $self->storage, |
432 | engine => $self, |
433 | }; |
434 | %$value = %temp; |
435 | bless $value, 'DBM::Deep::Hash' unless Scalar::Util::blessed( $value ); |
436 | } |
bb1daf85 |
437 | |
438 | return; |
c2472ede |
439 | } |
440 | |
bf941eae |
441 | 1; |
442 | __END__ |