NAME¶

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

VERSION¶

version 0.61

SYNOPSIS¶

    package CHI::Driver::MyDriver;
    use Moo;
    use strict;
    use warnings;
    extends 'CHI::Driver';
    has ...;
    sub fetch {
        my ( $self, $key ) = @_;
    }
    sub store {
        my ( $self, $key, $data[, $expires_in] ) = @_;
    }
    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 => '+My::Internal::CHI::Driver');

MOO / MOOSE¶

CHI driver classes must be Moo or Moose based to be fully functional, since we use Moose roles to implement various features. For backward compatibility, non-Moo/Moose drivers will still work at a basic level, but you will see an error if using any feature requiring a role.

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.

METHODS¶

DISCARD POLICIES¶

You can create new discard policies for size aware caches, to choose items to discard when the cache gets full. For example, the Memory driver implements an LRU policy.

To implement a discard policy foo, define a subroutine discard_policy_foo, 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.

For example, here's the Memory driver's LRU implementation. It utilizes a hash containing the last used time for each key.

   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);
       };
   }

You can set the default discard policy for your driver by overriding default_discard_policy; otherwise the default is 'arbitrary'.

   sub default_discard_policy { 'lru' }

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 it 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 testing_driver_class { 'CHI::Driver::MyDriver' }
      sub new_cache_options {
          my $self = shift;
          return (
              $self->SUPER::new_cache_options(),
              # Any necessary 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.

SEE ALSO¶

CHI

AUTHOR¶

Jonathan Swartz <swartz@pobox.com>

COPYRIGHT AND LICENSE¶

This software is copyright (c) 2021 by Jonathan Swartz.

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