NAME

Rose::DBx::Object::Cached::CHI - Rose::DB::Object Cache using the CHI interface

SYNOPSIS

package Category;

use Rose::DBx::Object::Cached::CHI;
our @ISA = qw(Rose::DBx::Object::Cached::CHI);

__PACKAGE__->meta->table('categories');

__PACKAGE__->meta->columns
(
  id          => { type => 'int', primary_key => 1 },
  name        => { type => 'varchar', length => 255 },
  description => { type => 'text' },
);

__PACKAGE__->meta->add_unique_key('name');

__PACKAGE__->meta->initialize;

...

## Defaults to an in memory cache that does not expire.

$cat1 = Category->new(id   => 123,
                      name => 'Art');

$cat1->save or die $category->error;


$cat2 = Category->new(id => 123);

# This will load from the memory cache, not the database
$cat2->load or die $cat2->error;

...

## Set the cache driver for all Rose::DB::Object derived objects
$Rose::DBx::Object::Cached::CHI::SETTINGS = {
  driver     => 'FastMmap',
  root_dir   => '/tmp/global_fastmmap',
};

$cat1 = Category->new(id   => 123,
                      name => 'Art')->save;

## In another script

$Rose::DBx::Object::Cached::CHI::SETTINGS = {
  driver     => 'FastMmap',
  root_dir   => '/tmp/global_fastmmap',
};

# This will load from the FastMmap cache, not the database
$cat2 = Category->new(id   => 123,
                      name => 'Art')->load;

...

## Set the cache driver for all Category derived objects
Category->cached_objects_settings(
  driver     => 'FastMmap',
  root_dir   => '/tmp/global_fastmmap',
);

...


## Set cache expire time for all Category objects
Category->cached_objects_expire_in('5 seconds');

## Set cache expire time for all Rose::DB::Object derived objects
$Rose::DBx::Object::Cached::CHI::SETTINGS = {
  driver     => 'Memory',
  expires_in    => '15 minutes',
};

<OR>

$Rose::DBx::Object::Cached::CHI::SETTINGS = {
  driver     => 'FastMmap',
  root_dir   => '/tmp/global_fastmmap',
  expires_in    => '15 minutes',
};

## Any driver for CHI will work.

DESCRIPTION

This module intends to extend the caching ability in Rose::DB::Object allowing objects to be cached by any driver that can be used with the CHI interface. This opens the possibility to cache objects across scripts or even servers by opening up methods of caching such as FastMmap and memcached.

Most of the code is taken straight from Rose::DB::Object::Cached. This does not extend Rose::DB::Object::Cached because function calls and how the cache is accessed needed to be changed thoughout the code.

MAJOR DIFFERENCE from Rose::DB::Object::Cached

All objects derived from a Rose::DBx::Object::Cached class are set and retrieved from CHI, therefore 2 objects that are loaded with the same parameters are not the same code reference.

In Rose::DB::Object::Cached

$cat1 = Category->new(id   => 123,
                        name => 'Art');

$cat1->save;

$cat2-> Category->new(id   => 123,
                        name => 'Art');

$cat2->load;

print $cat1->name; # prints "Art"

print $cat2->name; # prints "Art"

$cat1->name('Blah');

print $cat2->name; # prints "Blah"

In Rose::DBx::Object::Cached

$cat1 = Category->new(id   => 123,
                        name => 'Art');

$cat1->save;

$cat2-> Category->new(id   => 123,
                        name => 'Art');

$cat2->load;

print $cat1->name; # prints "Art"
print $cat2->name; # prints "Art"

$cat1->name('Blah');
print $cat2->name; # prints "Art"

GLOBALS

$SETTINGS

This global is used to set CHI settings for all objects derived from Rose::DBx::Object::Cached::CHI. Any settings here will override any default settings, but will conceded to settings configured by the class method cached_objects_settings

Example:

$Rose::DBx::Object::Cached::CHI::SETTINGS = { driver => 'FastMmap', root_dir => '/tmp/global_fastmmap', };

CLASS METHODS

Only class methods that do not exist in Rose::DB::Object::Cached are listed here.

cached_objects_settings [PARAMS]

If called with no arguments this will return the current cache settings. PARAMS are any valid options for the CHI constructor.

Example:

Category->cached_objects_settings (
    driver     => 'FastMmap',
    root_dir   => '/tmp/global_fastmmap',
    expires_in    => '15 minutes',
)

default_cached_objects_settings [PARAMS]

Returns the default CHI settings for the class. This method should be implemented by a sub class if custom settings are required.

package Category;
use base Rose::DBx::Object::Cached::CHI;

...

sub default_cached_objects_settings (
    return {
        driver     => 'FastMmap',
        root_dir   => '/tmp/global_fastmmap',
        expires_in    => '15 minutes',
    };
)

If this method is not implemented in a sub class it will return the following:

{ driver => 'Memory', global => 1 }

OBJECT METHODS

Only object methods that do not exist in Rose::DB::Object::Cached are listed here.

is_cache_in_sync

Because the cache is only updated when loading and saving this method will return weather the cache has been updated since the object was last loaded.

Returns true if the object is in sync with what exists in the cache. Returns false if the cache has been updated since the object was loaded.

IMPORTANT: Starting in version 0.16 this is now an optional function that must be turned on by setting $Rose::DBx::Object::Cached::CHI::USE_IN_SYNC to a true value. The cost of making a call to get the CHI object hurt the overall speed of the module.

PRIVATE METHODS

__xrdbopriv_clone

Calls the clone method in Rose::DB::Object::Helpers

__xrdbopriv_strip

Calls the strip method in Rose::DB::Object::Helpers

TODO

Tests

Currently tests only exist for MySQL. Almost all of these have been copied directly from the tests that exist for Rose::DB::Object.

AUTHOR

Kevin C. McGrath
CPAN ID: KMCGRATH

COPYRIGHT

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

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

perl(1).

cpanm Rose::DBx::Object::Cached::CHI

perl -MCPAN -e shell
install Rose::DBx::Object::Cached::CHI