<html><head><title>CHI::Driver::Development</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.15,
using Pod::Simple::PullParser v3.15,
under Perl v5.012002 at Wed Mar 2 00:52:11 2011 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<div class='indexgroup'>
<ul class='indexList indexList1'>
<li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
<li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
<li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
<li class='indexItem indexItem1'><a href='#NAMING'>NAMING</a>
<li class='indexItem indexItem1'><a href='#MOOSE'>MOOSE</a>
<li class='indexItem indexItem1'><a href='#NAMESPACE'>NAMESPACE</a>
<li class='indexItem indexItem1'><a href='#METHODS'>METHODS</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#Required_methods'>Required methods</a>
<li class='indexItem indexItem2'><a href='#Overridable_methods'>Overridable methods</a>
<li class='indexItem indexItem2'><a href='#Optional_methods'>Optional methods</a>
</ul>
<li class='indexItem indexItem1'><a href='#DISCARD_POLICIES'>DISCARD POLICIES</a>
<li class='indexItem indexItem1'><a href='#TESTING'>TESTING</a>
<li class='indexItem indexItem1'><a href='#AUTHOR'>AUTHOR</a>
<li class='indexItem indexItem1'><a href='#SEE_ALSO'>SEE ALSO</a>
<li class='indexItem indexItem1'><a href='#COPYRIGHT_%26_LICENSE'>COPYRIGHT & LICENSE</a>
</ul>
</div>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>CHI::Driver::Development -- Manual for developing new CHI drivers</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<pre> package CHI::Driver::MyDriver;
use Moose;
use strict;
use warnings;
extends 'CHI::Driver';
has ...;
__PACKAGE__->meta->make_immutable();
sub fetch {
my ( $self, $key ) = @_;
}
sub store {
my ( $self, $key, $data ) = @_;
}
sub remove {
my ( $self, $key ) = @_;
}
sub clear {
my ($self) = @_;
}
sub get_keys {
my ($self) = @_;
}
sub get_namespaces {
my ($self) = @_;
}</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>This document describes how to implement a new CHI driver.</p>
<p>The easiest way to start is to look at existing drivers, such as <a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3AMemory" class="podlinkpod"
>CHI::Driver::Memory</a> and <a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3AFastMmap" class="podlinkpod"
>CHI::Driver::FastMmap</a>.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAMING"
>NAMING</a></h1>
<p>If you are going to publicly release your driver, call it 'CHI::Driver::<i>something</i>' so that users can create it with</p>
<pre> CHI->new(driver => 'I<something>');</pre>
<p>If it's an internal driver, you can call it whatever you like and create it like</p>
<pre> CHI->new(driver_class => 'My::Internal::CHI::Driver');</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="MOOSE"
>MOOSE</a></h1>
<p>CHI driver classes must be <a href="http://search.cpan.org/perldoc?Moose" class="podlinkpod"
>Moose</a> based to be fully functional, since we use Moose roles to implement various features. For backward compatibility, non-Moose drivers will still work at a basic level, but you will see an error if using any feature requiring a role.</p>
<p>All drivers must directly or indirectly extend <a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver" class="podlinkpod"
>CHI::Driver</a>.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAMESPACE"
>NAMESPACE</a></h1>
<p>All cache handles have an assigned namespace that you can access with <code>$self->namespace</code>. You should use the namespace to partition your data store. That is, two cache objects with different namespaces should be able to access the same key without any collision.</p>
<p>Examples:</p>
<ul>
<li>The Memory driver uses a separate sub-hash inside its main memory hash for each namespace.</li>
<li>The File driver uses a separate top-level directory for each namespace.</li>
<li>The FastMmap driver uses a separate Cache::FastMmap file for each namespace.</li>
</ul>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS"
>METHODS</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Required_methods"
>Required methods</a></h2>
<p>The following methods have no default implementation, and MUST be defined by your subclass:</p>
<dl>
<dt><a name="store_(_$self,_$key,_$data,_$expires_at,_$options_)"
>store ( $self, $key, $data, $expires_at, $options )</a></dt>
<dd>
<p>Associate <i>$data</i> with <i>$key</i> in the namespace, overwriting any existing entry. Called by <a href="#set" class="podlinkpod"
>"set"</a>. <i>$data</i> will contain any necessary metadata, including expiration options, so you can just store it as a single block.</p>
<p>The <i>$expires_at</i> epoch value is provided in case you are working with an existing cache implementation (like memcached) that also has an interest in storing the expiration time for its own purposes. Normally, you can ignore this.</p>
<p><$options> contains the hash of options passed to <a href="#set" class="podlinkpod"
>"set"</a>, in case you want to implement driver-specific set options. Normally, you can ignore this.</p>
<dt><a name="fetch_(_$self,_$key_)"
>fetch ( $self, $key )</a></dt>
<dd>
<p>Returns the data associated with <i>$key</i> in the namespace. Called by <a href="#get" class="podlinkpod"
>"get"</a>. The main CHI::Driver superclass will take care of extracting out metadata like expiration options and determining if the value has expired.</p>
<dt><a name="remove_(_$self,_$key_)"
>remove ( $self, $key )</a></dt>
<dd>
<p>Remove the data associated with the <i>$key</i> in the namespace.</p>
<dt><a name="clear_(_$self_)"
>clear ( $self )</a></dt>
<dd>
<p>Remove all data associated with the namespace. (Technically not required, but the default implementation, which iterates over all keys and calls <a href="#remove" class="podlinkpod"
>"remove"</a> for each, is very inefficient).</p>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Overridable_methods"
>Overridable methods</a></h2>
<p>The following methods have a default implementation, but MAY be overriden by your subclass:</p>
<dl>
<dt><a name="BUILD_(_$self,_$options_)"
>BUILD ( $self, $options )</a></dt>
<dd>
<p>Define the Moose BUILD method if you want to process any options specific to your driver.</p>
<dt><a name="fetch_multi_hashref_(_$keys_)"
>fetch_multi_hashref ( $keys )</a></dt>
<dd>
<p>Override this if you want to efficiently process multiple fetches. Return a hash reference from keys to fetched data. If a key is not available, it may be left out of the hash or paired with undef. The default method will iterate over <i>$keys</i> and call fetch for each.</p>
<p>This method is called by <a href="http://search.cpan.org/perldoc?get_multi_arrayref" class="podlinkpod"
>get_multi_arrayref</a> and <a href="http://search.cpan.org/perldoc?get_multi_hashref" class="podlinkpod"
>get_multi_hashref</a>.</p>
<dt><a name="store_multi_(_$key_data,_$options_)"
>store_multi ( $key_data, $options )</a></dt>
<dd>
<p>Override this if you want to efficiently process multiple stores. <i>$key_data</i> is a hash of keys and data that should be stored. The default will iterate over <i>$key_data</i> and call store for each pair.</p>
<p>This method is called by <a href="http://search.cpan.org/perldoc?set_multi" class="podlinkpod"
>set_multi</a>.</p>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Optional_methods"
>Optional methods</a></h2>
<p>The following methods have no default implementation, and MAY be defined by your subclass, but are not required for basic cache operations.</p>
<dl>
<dt><a name="get_keys_(_$self_)"
>get_keys ( $self )</a></dt>
<dd>
<p>Return all keys in the namespace. It is acceptable to either include or omit expired keys.</p>
<dt><a name="get_namespaces_(_$self_)"
>get_namespaces ( $self )</a></dt>
<dd>
<p>Return namespaces associated with the cache. It is acceptable to either include or omit namespaces with no valid keys.</p>
</dd>
</dl>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="DISCARD_POLICIES"
>DISCARD POLICIES</a></h1>
<p>You can create new discard policies for <a href="http://search.cpan.org/perldoc?size%20aware" class="podlinkpod"
>CHI/SIZE AWARENESS</a> caches, to choose items to discard when the cache gets full. For example, the Memory driver implements an LRU policy.</p>
<p>To implement a discard policy <i>foo</i>, define a subroutine <i>discard_policy_foo</i>, which takes a driver object and returns a closure that returns one key each time it is called. The closure should maintain state so that each key is only returned once.</p>
<p>For example, here's the Memory driver's LRU implementation. It utilizes a hash containing the last used time for each key.</p>
<pre> sub discard_policy_lru {
my ($self) = @_;
my $last_used_time = $self->{metadata_for_namespace}->{last_used_time};
my @keys_in_lru_order =
sort { $last_used_time->{$a} <=> $last_used_time->{$b} } $self->get_keys;
return sub {
shift(@keys_in_lru_order);
};
}</pre>
<p>You can set the default discard policy for your driver by overriding default_discard_policy; otherwise the default is 'arbitrary'.</p>
<pre> sub default_discard_policy { 'lru' }</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="TESTING"
>TESTING</a></h1>
<p>CHI has a standard set of unit tests that should be used to ensure your driver is fully implementing the CHI API.</p>
<p>To use CHI's tests (replacing <i>MyDriver</i> with the name of your driver):</p>
<ul>
<li>Install Test::Class, and add Test::Class to the build dependencies for your distribution.</li>
<li>Add a module called <i>CHI::Driver::MyDriver::t::CHIDriverTests</i> to your distribution containing:
<pre> package CHI::Driver::MyDriver::t::CHIDriverTests;
use strict;
use warnings;
use CHI::Test;
use base qw(CHI::t::Driver);
sub new_cache_options {
my $self = shift;
return (
$self->SUPER::new_cache_options(),
driver_class => 'CHI::Driver::MyDriver',
# Any other CHI->new parameters for your test driver
);
}
1;</pre>
</li>
<li>Add a test script called <i>t/CHI-driver-tests.t</i> to your distribution containing:
<pre> #!perl -w
use strict;
use warnings;
use CHI::Driver::MyDriver::t::CHIDriverTests;
CHI::Driver::MyDriver::t::CHIDriverTests->runtests;</pre>
</li>
<li>You may need to override other methods in <i>CHI::Driver::MyDriver::t::CHIDriverTests</i>, e.g. to skip tests that do not apply to your driver. See CHI::t::Driver::Memory and CHI::t::Driver::File in this distribution for examples.</li>
</ul>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Jonathan Swartz</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SEE_ALSO"
>SEE ALSO</a></h1>
<p><a href="http://search.cpan.org/perldoc?CHI" class="podlinkpod"
>CHI</a>, <a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver" class="podlinkpod"
>CHI::Driver</a></p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COPYRIGHT_&_LICENSE"
>COPYRIGHT & LICENSE</a></h1>
<p>Copyright (C) 2007 Jonathan Swartz.</p>
<p>CHI is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.</p>
<p>This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.</p>
<!-- end doc -->
</body></html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
c575b3572b1a595b8b6ae0529951ea8a
>
files
>
11
