NAME

Data::Fallback - fallback through an array of levels till you find your data, cacheing where desired

DESCRIPTION

The simplest, good example for Data::Fallback, is cacheing a database to a conf file, then to memory. In general, the user supplies an array ref of hash refs (an object property named list), where each hash ref explains how to get data for that step. Each hash ref needs a package, which currently can be Memory, ConfFile, DBI, or WholeFile. Update acceptance can be set for each level.

Data::Fallback then goes through the array, checking for data, stopping when it finds said data, updates up the array, as requested, and returns the data.

A group can be thought of as a row and an item a column.

INFORMAL EXAMPLE

Start with a table foo.

  column       data

  ------       ----
  id           1
  name         Chopper

and a file foo.cache. I offer two sets of hits, in a mod_perl of daemon environment, both trying to

  SELECT id FROM foo WHERE name = 'Chopper'

  Set 1
    Hit 1a
      Check memory    -> data not there
      Check foo.cache -> data not there
      Check db        -> data is there
      Update foo.cache
      Update memory
      Return id = 1

    Hit 1b
      Check memory    -> data is there
      Return id = 1

  Set 2, after a restart
    Hit 2a
      Check memory    -> data not there
      Check foo.cache -> data is there
      Update memory
      Return id = 1

    Hit 2b
      Check memory    -> data is there
      Return id = 1

So, even after the restart, the database only gets hit once.

EXAMPLE

  #!/usr/bin/perl -w

  use strict;
  use Data::Fallback;
  use Carp qw(confess);

  # I use dumper just to show some complex structures
  use Data::Dumper;

  # here I write out a couple files which I late clean up
  # the idea is that the over file, overrides the default file

  my $over_file    = "/tmp/data_fallback_over";
  my $default_file = "/tmp/data_fallback_default";

  open (FILE, ">$over_file") || confess "couldn't open $over_file: $!";
  print FILE "key2 over2";
  close(FILE);

  open (FILE, ">$default_file") || confess "couldn't open $default_file: $!";
  print FILE "key1 default1\nkey2 default2";
  close(FILE);

  my $self = Data::Fallback->new({

  # list is an array ref of hash refs to fall through looking for data

    list => [
      {
        # accept_update says to update the conf
        accept_update => 'group',

        # this means to cache everything
        cache_level => 'all',

        # where to get the content
        content => $over_file,
      },
      {
        cache_level => 'all',
        content     => $default_file,
      },
    ],

    # need to name list
    list_name => 'test',

    # object global for package
    package => 'ConfFile',

    zeroth_hash => {
      ttl => '5 seconds',
    },
  });
  print $self->get('key2') . "\n";
  print Dumper $self->{history};
  print $self->get('key2') . "\n";
  print Dumper $self->{history};
  print $self->get('key1') . "\n";
  print Dumper $self->{history};
  print $self->get('key1') . "\n";
  print Dumper $self->{history};
  unlink $over_file, $default_file;

PACKAGES

You are able to write your own packages that aren't a part of Data::Fallback. Such packages would look something like this

#!/usr/bin/perl -w

package Mine;

use strict; use Data::Fallback; use vars qw(@ISA);

@ISA = qw(Data::Fallback);

and methods for at least each of the following _GET, SET_ITEM, SET_GROUP, SET_SESSION_ITEM, SET_SESSION_CONTENT. This functionality allows you to build your content however you like, from wherever you like. For example, let's supposing you have your own objects that build entire pages. You could simply wrap around said objects with the above methods. Put a nice WholeFile cache that accepts updates in front of your personal object. On the first hit, your content gets generated, in some potentially very expensive way. On the second hit you cache from either the Memory package, or the WholeFile level you inserted. Currently, there are cacheing issues, but I hope yo clear them up in time.

APOLOGIES

This perldoc isn't the best, but I plan on continued development for sometime. In other words, a better perldoc is to come. And a better test suite. If you feel so inclined to use Data::Fallback::Daemon, do so realizing that the protocol is sure to change. The TO_DO shows where the poject is headed.

THANKS

Thanks to Rob Brown, Paul Seamons, Allen Bettilyon and Dan Hanks for listening to my babblings and offering feedback. Thanks to Rob Brown for testing my first version. Also, thanks to Paul for Net::Server and helping me set up Data::Fallback::Daemon. Lincoln Stein's AUTHOR INFORMATION was borrowed from heavily.

AUTHOR

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Address bug reports and comments to: cpan@spack.net.

When sending bug reports, please provide the version of Data::Fallback, the version of Perl, and the name and version of the operating system you are using.

CPAN RT