1DBM::Deep::Engine(3pm)User Contributed Perl DocumentationDBM::Deep::Engine(3pm)
2
3
4

NAME

6       DBM::Deep::Engine - mediate mapping between DBM::Deep objects and
7       storage medium
8

PURPOSE

10       This is an internal-use-only object for DBM::Deep. It mediates the low-
11       level mapping between the DBM::Deep objects and the storage medium.
12
13       The purpose of this documentation is to provide low-level documentation
14       for developers. It is not intended to be used by the general public.
15       This documentation and what it documents can and will change without
16       notice.
17

OVERVIEW

19       The engine exposes an API to the DBM::Deep objects (DBM::Deep,
20       DBM::Deep::Array, and DBM::Deep::Hash) for their use to access the
21       actual stored values. This API is the following:
22
23       •   new
24
25       •   read_value
26
27       •   get_classname
28
29       •   make_reference
30
31       •   key_exists
32
33       •   delete_key
34
35       •   write_value
36
37       •   get_next_key
38
39       •   setup
40
41       •   clear
42
43       •   begin_work
44
45       •   commit
46
47       •   rollback
48
49       •   lock_exclusive
50
51       •   lock_shared
52
53       •   unlock
54
55       They are explained in their own sections below. These methods, in turn,
56       may provide some bounds-checking, but primarily act to instantiate
57       objects in the Engine::Sector::* hierarchy and dispatch to them.
58

TRANSACTIONS

60       Transactions in DBM::Deep are implemented using a variant of MVCC. This
61       attempts to keep the amount of actual work done against the file low
62       while still providing Atomicity, Consistency, and Isolation.
63       Durability, unfortunately, cannot be done with only one file.
64
65   STALENESS
66       If another process uses a transaction slot and writes stuff to it, then
67       terminates, the data that process wrote is still within the file. In
68       order to address this, there is also a transaction staleness counter
69       associated within every write.  Each time a transaction is started,
70       that process increments that transaction's staleness counter. If, when
71       it reads a value, the staleness counters aren't identical, DBM::Deep
72       will consider the value on disk to be stale and discard it.
73
74   DURABILITY
75       The fourth leg of ACID is Durability, the guarantee that when a commit
76       returns, the data will be there the next time you read from it. This
77       should be regardless of any crashes or powerdowns in between the commit
78       and subsequent read.  DBM::Deep does provide that guarantee; once the
79       commit returns, all of the data has been transferred from the
80       transaction shadow to the HEAD. The issue arises with partial commits -
81       a commit that is interrupted in some fashion. In keeping with
82       DBM::Deep's "tradition" of very light error-checking and non-existent
83       error-handling, there is no way to recover from a partial commit. (This
84       is probably a failure in Consistency as well as Durability.)
85
86       Other DBMSes use transaction logs (a separate file, generally) to
87       achieve Durability.  As DBM::Deep is a single-file, we would have to do
88       something similar to what SQLite and BDB do in terms of committing
89       using synchronized writes. To do this, we would have to use a much
90       higher RAM footprint and some serious programming that makes my head
91       hurt just to think about it.
92

METHODS

94   read_value( $obj, $key )
95       This takes an object that provides _base_offset() and a string. It
96       returns the value stored in the corresponding Sector::Value's data
97       section.
98
99   get_classname( $obj )
100       This takes an object that provides _base_offset() and returns the
101       classname (if any) associated with it.
102
103       It delegates to Sector::Reference::get_classname() for the heavy
104       lifting.
105
106       It performs a staleness check.
107
108   make_reference( $obj, $old_key, $new_key )
109       This takes an object that provides _base_offset() and two strings. The
110       strings correspond to the old key and new key, respectively. This
111       operation is equivalent to (given "$db->{foo} = [];") "$db->{bar} =
112       $db->{foo}".
113
114       This returns nothing.
115
116   key_exists( $obj, $key )
117       This takes an object that provides _base_offset() and a string for the
118       key to be checked. This returns 1 for true and "" for false.
119
120   delete_key( $obj, $key )
121       This takes an object that provides _base_offset() and a string for the
122       key to be deleted. This returns the result of the Sector::Reference
123       delete_key() method.
124
125   write_value( $obj, $key, $value )
126       This takes an object that provides _base_offset(), a string for the
127       key, and a value. This value can be anything storable within DBM::Deep.
128
129       This returns 1 upon success.
130
131   setup( $obj )
132       This takes an object that provides _base_offset(). It will do
133       everything needed in order to properly initialize all values for
134       necessary functioning. If this is called upon an already initialized
135       object, this will also reset the inode.
136
137       This returns 1.
138
139   begin_work( $obj )
140       This takes an object that provides _base_offset(). It will set up all
141       necessary bookkeeping in order to run all work within a transaction.
142
143       If $obj is already within a transaction, an error will be thrown. If
144       there are no more available transactions, an error will be thrown.
145
146       This returns undef.
147
148   rollback( $obj )
149       This takes an object that provides _base_offset(). It will revert all
150       actions taken within the running transaction.
151
152       If $obj is not within a transaction, an error will be thrown.
153
154       This returns 1.
155
156   commit( $obj )
157       This takes an object that provides _base_offset(). It will apply all
158       actions taken within the transaction to the HEAD.
159
160       If $obj is not within a transaction, an error will be thrown.
161
162       This returns 1.
163
164   get_next_key( $obj, $prev_key )
165       This takes an object that provides _base_offset() and an optional
166       string representing the prior key returned via a prior invocation of
167       this method.
168
169       This method delegates to "DBM::Deep::Iterator->get_next_key()".
170
171   lock_exclusive()
172       This takes an object that provides _base_offset(). It will guarantee
173       that the storage has taken precautions to be safe for a write.
174
175       This returns nothing.
176
177   lock_shared()
178       This takes an object that provides _base_offset(). It will guarantee
179       that the storage has taken precautions to be safe for a read.
180
181       This returns nothing.
182
183   unlock()
184       This takes an object that provides _base_offset(). It will guarantee
185       that the storage has released the most recently-taken lock.
186
187       This returns nothing.
188

INTERNAL METHODS

190       The following methods are internal-use-only to DBM::Deep::Engine and
191       its child classes.
192
193   flush()
194       This takes no arguments. It will do everything necessary to flush all
195       things to disk. This is usually called during unlock() and setup().
196
197       This returns nothing.
198
199   load_sector( $loc )
200       This takes an id/location/offset and loads the sector based on the
201       engine's defined sector type.
202
203   clear( $obj )
204       This takes an object that provides _base_offset() and deletes all its
205       elements, returning nothing.
206
207   cache / clear_cache
208       This is the cache of loaded Reference sectors.
209
210   supports( $option )
211       This returns a boolean depending on if this instance of DBM::Dep
212       supports that feature. $option can be one of:
213
214       •   transactions
215
216       •   singletons
217
218       Any other value will return false.
219

ACCESSORS

221       The following are readonly attributes.
222
223       •   storage
224
225       •   sector_type
226
227       •   iterator_class
228
229
230
231perl v5.38.0                      2023-09-03            DBM::Deep::Engine(3pm)