Debian Codegraph @

Debconf/DbDriver/Cache.pm

raw
1 #!/usr/bin/perl
2
3 =head1 NAME
4
5 Debconf::DbDriver::Cache - caching database driver
6
7 =cut
8
9 package Debconf::DbDriver::Cache;
10 use warnings;
11 use strict;
12 use Debconf::Log qw{:all};
13 use base 'Debconf::DbDriver';
14
15 =head1 DESCRIPTION
16
17 This is a base class for cacheable database drivers. Use this as the base
18 class for your driver if it makes sense to load and store items as a whole
19 (eg, if you are using text files to represent each item, or downloading whole
20 items over the net).
21
22 Don't use this base class for your driver if it makes more sense for your
23 driver to access individual parts of each item independantly (by
24 querying a (fast) database, for example).
25
26 =head1 FIELDS
27
28 =over 4
29
30 =item cache
31
32 A reference to a hash that holds the data for each loaded item in the
33 database. Each hash key is a item name; hash values are either undef
34 (used to indicate that a item used to exist here, but was deleted), or
35 are themselves references to hashes that hold the item data.
36
37 =item dirty
38
39 A reference to a hash that holds data about what items in the cache are
40 dirty. Each hash key is an item name; if the value is true, the item is
41 dirty.
42
43 =back
44
45 =cut
46
47 use fields qw(cache dirty);
48
49 =head1 ABSTRACT METHODS
50
51 Derived classes need to implement these methods in most cases.
52
53 =head2 load(itemname)
54
55 Ensure that the given item is loaded. It will want to call back to the
56 cacheadd method (see below) to add an item or items to the cache.
57
58 =head2 save(itemname,value)
59
60 This method will be passed a an identical hash reference with the same
61 format as what the load method should return. The data in the hash should
62 be saved.
63
64 =head2 remove(itemname)
65
66 Remove a item from the database.
67
68 =head1 METHODS
69
70 =head2 iterator
71
72 Derived classes should override this method and construct their own
73 iterator. Then at the end call:
74
75 $this->SUPER::iterator($myiterator);
76
77 This method will take it from there.
78
79 =cut
80
81 sub iterator {
82 my $this=shift;
83 my $subiterator=shift;
84
85 my @items=keys %{$this->{cache}};
86 my $iterator=Debconf::Iterator->new(callback => sub {
87 # So, the trick is we will first iterate over everything in
88 # the cache. Then, we will let the underlying driver take
89 # over and iterate everything outside the cache. If it
90 # returns something that is in the cache (and we're
91 # weeding), or something that is marked deleted in cache, just
92 # ask it for the next thing.
93 while (my $item = pop @items) {
94 next unless defined $this->{cache}->{$item};
95 return $item;
96 }
97 return unless $subiterator;
98 my $ret;
99 do {
100 $ret=$subiterator->iterate;
101 } while defined $ret and exists $this->{cache}->{$ret};
102 return $ret;
103 });
104 return $iterator;
105 }
106
107 =head2 exists(itemname)
108
109 Derived classes should override this method. Be sure to call
110 SUPER::exists(itemname) first, and return whatever it returns
111 *unless* it returns 0, to check if the item exists in the cache
112 first!
113
114 This method returns one of three values:
115
116 true -- yes, it's in the cache
117 undef -- marked as deleted in the cache, so does not exist
118 0 -- not in the cache; up to derived class now
119
120 =cut
121
122 sub exists {
123 my $this=shift;
124 my $item=shift;
125
126 return $this->{cache}->{$item}
127 if exists $this->{cache}->{$item};
128 return 0;
129 }
130
131 =head2 init
132
133 On initialization, the cache is empty.
134
135 =cut
136
137 sub init {
138 my $this=shift;
139
140 $this->{cache} = {} unless exists $this->{cache};
141 }
142
143 =head2 cacheadd(itemname, entry)
144
145 Derived classes can call this method to add an item to the cache. If the item
146 is already in the cache, no change will be made.
147
148 The entry field is a rather complex hashed structure to represent
149 the item. The structure is a reference to a hash with 4 items:
150
151 =over 4
152
153 =item owners
154
155 The value of this key must be a reference to a hash whose hash keys are
156 the owner names, and hash values are true.
157
158 =item fields
159
160 The value of this key must be a reference to a hash whose hash keys are
161 the field names, and hash values are the field values.
162
163 =item variables
164
165 The value of this key must be a reference to a hash whose hash keys are
166 the variable names, and hash values are the variable values.
167
168 =item flags
169
170 The value of this key must be a reference to a hash whose hash keys are
171 the flag names, and hash values are the flag values.
172
173 =back
174
175 =cut
176
177 sub cacheadd {
178 my $this=shift;
179 my $item=shift;
180 my $entry=shift;
181
182 return if exists $this->{cache}->{$item};
183
184 $this->{cache}->{$item}=$entry;
185 $this->{dirty}->{$item}=0;
186 }
187
188 =head2 cachedata(itemname)
189
190 Looks up an item in the cache and returns a complex data structure of the same
191 format as the cacheadd() entry parameter.
192
193 =cut
194
195 sub cachedata {
196 my $this=shift;
197 my $item=shift;
198
199 return $this->{cache}->{$item};
200 }
201
202 =head2 cached(itemname)
203
204 Ensure that a given item is loaded up in the cache.
205
206 =cut
207
208 sub cached {
209 my $this=shift;
210 my $item=shift;
211
212 unless (exists $this->{cache}->{$item}) {
213 debug "db $this->{name}" => "cache miss on $item";
214 $this->load($item);
215 }
216 return $this->{cache}->{$item};
217 }
218
219 =head2 shutdown
220
221 Synchronizes the underlying database with the cache.
222
223 Saving a item involves feeding the item from the cache into the underlying
224 database, and then telling the underlying db to save it.
225
226 However, if the item is undefined in the cache, we instead tell the
227 underlying db to remove it.
228
229 Returns true unless any of the operations fail.
230
231 =cut
232
233 sub shutdown {
234 my $this=shift;
235
236 return if $this->{readonly};
237
238 my $ret=1;
239 foreach my $item (keys %{$this->{cache}}) {
240 if (not defined $this->{cache}->{$item}) {
241 # Remove item, then remove marker in cache.
242 $ret=undef unless defined $this->remove($item);
243 delete $this->{cache}->{$item};
244 }
245 elsif ($this->{dirty}->{$item}) {
246 $ret=undef unless defined $this->save($item, $this->{cache}->{$item});
247 $this->{dirty}->{$item}=0;
248 }
249 }
250 return $ret;
251 }
252
253 =head2 addowner(itemname, ownername, type)
254
255 Add an owner, if the underlying db is not readonly, and if the given
256 type is acceptable.
257
258 =cut
259
260 sub addowner {
261 my $this=shift;
262 my $item=shift;
263 my $owner=shift;
264 my $type=shift;
265
266 return if $this->{readonly};
267 $this->cached($item);
268
269 if (! defined $this->{cache}->{$item}) {
270 return if ! $this->accept($item, $type);
271 debug "db $this->{name}" => "creating in-cache $item";
272 # The item springs into existance.
273 $this->{cache}->{$item}={
274 owners => {},
275 fields => {},
276 variables => {},
277 flags => {},
278 }
279 }
280
281 if (! exists $this->{cache}->{$item}->{owners}->{$owner}) {
282 $this->{cache}->{$item}->{owners}->{$owner}=1;
283 $this->{dirty}->{$item}=1;
284 }
285 return $owner;
286 }
287
288 =head2 removeowner(itemname, ownername)
289
290 Remove an owner from the cache. If all owners are removed, the item
291 is marked as removed in the cache.
292
293 =cut
294
295 sub removeowner {
296 my $this=shift;
297 my $item=shift;
298 my $owner=shift;
299
300 return if $this->{readonly};
301 return unless $this->cached($item);
302
303 if (exists $this->{cache}->{$item}->{owners}->{$owner}) {
304 delete $this->{cache}->{$item}->{owners}->{$owner};
305 $this->{dirty}->{$item}=1;
306 }
307 unless (keys %{$this->{cache}->{$item}->{owners}}) {
308 $this->{cache}->{$item}=undef;
309 $this->{dirty}->{$item}=1;
310 }
311 return $owner;
312 }
313
314 =head2 owners(itemname)
315
316 Pull owners out of the cache.
317
318 =cut
319
320 sub owners {
321 my $this=shift;
322 my $item=shift;
323
324 return unless $this->cached($item);
325 return keys %{$this->{cache}->{$item}->{owners}};
326 }
327
328 =head2 getfield(itemname, fieldname)
329
330 Pulls the field out of the cache.
331
332 =cut
333
334 sub getfield {
335 my $this=shift;
336 my $item=shift;
337 my $field=shift;
338
339 return unless $this->cached($item);
340 return $this->{cache}->{$item}->{fields}->{$field};
341 }
342
343 =head2 setfield(itemname, fieldname, value)
344
345 Set the field in the cache, if the underlying db is not readonly.
346
347 =cut
348
349 sub setfield {
350 my $this=shift;
351 my $item=shift;
352 my $field=shift;
353 my $value=shift;
354
355 return if $this->{readonly};
356 return unless $this->cached($item);
357 $this->{dirty}->{$item}=1;
358 return $this->{cache}->{$item}->{fields}->{$field} = $value;
359 }
360
361 =head2 removefield(itemname, fieldname)
362
363 Remove the field from the cache, if the underlying db is not readonly.
364
365 =cut
366
367 sub removefield {
368 my $this=shift;
369 my $item=shift;
370 my $field=shift;
371
372 return if $this->{readonly};
373 return unless $this->cached($item);
374 $this->{dirty}->{$item}=1;
375 return delete $this->{cache}->{$item}->{fields}->{$field};
376 }
377
378 =head2 fields(itemname)
379
380 Pulls the field list out of the cache.
381
382 =cut
383
384 sub fields {
385 my $this=shift;
386 my $item=shift;
387
388 return unless $this->cached($item);
389 return keys %{$this->{cache}->{$item}->{fields}};
390 }
391
392 =head2 getflag(itemname, flagname)
393
394 Pulls the flag out of the cache.
395
396 =cut
397
398 sub getflag {
399 my $this=shift;
400 my $item=shift;
401 my $flag=shift;
402
403 return unless $this->cached($item);
404 return $this->{cache}->{$item}->{flags}->{$flag}
405 if exists $this->{cache}->{$item}->{flags}->{$flag};
406 return 'false';
407 }
408
409 =head2 setflag(itemname, flagname, value)
410
411 Sets the flag in the cache, if the underlying db is not readonly.
412
413 =cut
414
415 sub setflag {
416 my $this=shift;
417 my $item=shift;
418 my $flag=shift;
419 my $value=shift;
420
421 return if $this->{readonly};
422 return unless $this->cached($item);
423 $this->{dirty}->{$item}=1;
424 return $this->{cache}->{$item}->{flags}->{$flag} = $value;
425 }
426
427 =head2 flags(itemname)
428
429 Pulls the flag list out of the cache.
430
431 =cut
432
433 sub flags {
434 my $this=shift;
435 my $item=shift;
436
437 return unless $this->cached($item);
438 return keys %{$this->{cache}->{$item}->{flags}};
439 }
440
441 =head2 getvariable(itemname, variablename)
442
443 Pulls the variable out of the cache.
444
445 =cut
446
447 sub getvariable {
448 my $this=shift;
449 my $item=shift;
450 my $variable=shift;
451
452 return unless $this->cached($item);
453 return $this->{cache}->{$item}->{variables}->{$variable};
454 }
455
456 =head2 setvariable(itemname, variablename, value)
457
458 Sets the flag in the cache, if the underlying db is not readonly.
459
460 =cut
461
462 sub setvariable {
463 my $this=shift;
464 my $item=shift;
465 my $variable=shift;
466 my $value=shift;
467
468 return if $this->{readonly};
469 return unless $this->cached($item);
470 $this->{dirty}->{$item}=1;
471 return $this->{cache}->{$item}->{variables}->{$variable} = $value;
472 }
473
474 =head2 variables(itemname)
475
476 Pulls the variable list out of the cache.
477
478 =cut
479
480 sub variables {
481 my $this=shift;
482 my $item=shift;
483
484 return unless $this->cached($item);
485 return keys %{$this->{cache}->{$item}->{variables}};
486 }
487
488 =head1 AUTHOR
489
490 Joey Hess <[email protected]>
491
492 =cut
493
494 1