Skip to content

Latest commit

 

History

History
254 lines (152 loc) · 6.18 KB

Development.pod

File metadata and controls

254 lines (152 loc) · 6.18 KB
Raw

NAME

CHI::Driver::Development -- Manual for developing new CHI drivers

SYNOPSIS

package CHI::Driver::MyDriver;
use Mouse;
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) = @_;

}

DESCRIPTION

This document describes how to implement a new CHI driver.

The easiest way to start is to look at existing drivers, such as CHI::Driver::Memory and CHI::Driver::FastMmap.

NAMING

If you are going to publicly release your driver, call it 'CHI::Driver::something' so that users can create it with

CHI->new(driver => 'I<something>');

If it's an internal driver, you can call it whatever you like and create it like

CHI->new(driver_class => 'My::Internal::CHI::Driver');

MOUSE

CHI driver classes are Mouse based. Since Mouse plays well with Moose and standard OO classes, you can choose what to use in your driver, though we recommend Mouse or Moose for consistency and clarity.

All drivers must directly or indirectly extend CHI::Driver.

NAMESPACE

All cache handles have an assigned namespace that you can access with $self->namespace. 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.

Examples:

  • The Memory driver uses a separate sub-hash inside its main memory hash for each namespace.

  • The File driver uses a separate top-level directory for each namespace.

  • The FastMmap driver uses a separate Cache::FastMmap file for each namespace.

TESTING

CHI has a standard set of unit tests that should be used to ensure your driver is fully implementing the CHI API.

To use CHI's tests (replacing MyDriver with the name of your driver):

  • Install Test::Class, and add Test::Class to the build dependencies for your distribution.

  • Add a module called CHI::Driver::MyDriver::t::CHIDriverTests to your distribution containing:

    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;

  • Add a test script called t/CHI-driver-tests.t to your distribution containing:

    #!perl -w
use strict;
use warnings;
use CHI::Driver::MyDriver::t::CHIDriverTests;
CHI::Driver::MyDriver::t::CHIDriverTests->runtests;

  • You may need to override other methods in CHI::Driver::MyDriver::t::CHIDriverTests, 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.

METHODS

Required methods

The following methods have no default implementation, and MUST be defined by your subclass:

store ( $self, $key, $data, $expires_at, $options )

Associate $data with $key in the namespace, overwriting any existing entry. Called by "set". $data will contain any necessary metadata, including expiration options, so you can just store it as a single block.

The $expires_at 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.

<$options> contains the hash of options passed to "set", in case you want to implement driver-specific set options. Normally, you can ignore this.

fetch ( $self, $key )

Returns the data associated with $key in the namespace. Called by "get". The main CHI::Driver superclass will take care of extracting out metadata like expiration options and determining if the value has expired.

remove ( $self, $key )

Remove the data associated with the $key in the namespace.

clear ( $self )

Remove all data associated with the namespace.

Overridable methods

The following methods have a default implementation, but MAY be overriden by your subclass:

BUILD ( $self, $options )

Define Mouse's BUILD method if you want to process any options specific to your driver.

fetch_multi_arrayref ( $keys )

Override this if you want to efficiently process multiple fetches. Return an array reference of data or undef corresponding to $keys. The default will iterate over $keys and call fetch for each.

Overriding this method will affect fetch_multi_array and fetch_multi_hash as well.

store_multi ( $key_data, $options )

Override this if you want to efficiently process multiple stores. $key_data is a hash of keys and data that should be stored. The default will iterate over $key_data and call store for each pair.

Optional methods

The following methods have no default implementation, and MAY be defined by your subclass, but are not required for basic cache operations.

get_keys ( $self )

Return all keys in the namespace. It is acceptable to either include or omit expired keys.

get_namespaces ( $self )

Return namespaces associated with the cache. It is acceptable to either include or omit namespaces with no valid keys.

AUTHOR

Jonathan Swartz

SEE ALSO

CHI, CHI::Driver

COPYRIGHT & LICENSE

Copyright (C) 2007 Jonathan Swartz.

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.

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