---
name: "Poet::Cache"
section: "3pm"
platform: "linux"
package: "libpoet-perl"
version: "0.16-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Poet::Cache"
---

# Poet::Cache(3pm)

## NAME

Poet::Cache -- Poet caching with CHI

## SYNOPSIS

```
    # In a conf file...
    cache:
       defaults:
          driver: Memcached
          servers: ["10.0.0.15:11211", "10.0.0.15:11212"]
    # In a script...
    use Poet::Script qw($cache);
    # In a module...
    use Poet qw($cache);
    # In a component...
    my $cache = $m->cache;
    # For an arbitrary namespace...
    my $cache = Poet::Cache->new(namespace => 'Some::Namespace')
    # then...
    my $customer = $cache->get($name);
    if ( !defined $customer ) {
        $customer = get_customer_from_db($name);
        $cache->set( $name, $customer, "10 minutes" );
    }
    my $customer2 = $cache->compute($name2, "10 minutes", sub {
        get_customer_from_db($name2)
    });
```

## DESCRIPTION

Poet::Cache is a subclass of CHI. CHI provides a unified caching API over a variety of storage backends, such as memory, plain files, memory mapped files, memcached, and DBI.

Each package and Mason component uses its own CHI namespace so that caches remain separate.

## CONFIGURATION

The Poet configuration entry 'cache', if any, will be passed to Poet::Cache-\>**config()**. This can go in any Poet conf file, e.g. `"local.cfg"` or `"global/cache.cfg"`.

Here's a simple configuration that caches everything to files under `"data/cache"`. This is also the default if no configuration is present.

```
   cache:
      defaults:
         driver: File
         root_dir: ${root}/data/cache
```

Here's a more involved configuration that defines several "storage types" and assigns each namespace a storage type.

```
   cache:
      defaults:
         expires_variance: 0.2
      storage:
         file:
            driver: File
            root_dir: ${root}/data/cache
         memcached:
            driver: Memcached
            servers: ["10.0.0.15:11211", "10.0.0.15:11212"]
            compress_threshold: 4096
      namespace:
         /some/component:       { storage: file, expires_in: 5min }
         /some/other/component: { storage: memcached, expires_in: 1h }
         Some::Library:         { storage: memcached, expires_in: 10min }
```

Given the configuration above, and the code

```
    package Some::Library;
    use Poet qw($cache);
```

this `$cache` will be created with properties

```
    driver: Memcached
    servers: ["10.0.0.15:11211", "10.0.0.15:11212"]
    compress_threshold: 4096
    expires_in: 10min
```

## USAGE

### Obtaining cache handle

- •

  In a script (namespace will be 'main'):

  ```
      use Poet::Script qw($cache);
  ```

- •

  In a module `"MyApp::Foo"` (namespace will be 'MyApp::Foo'):

  ```
      use Poet qw($cache);
  ```

- •

  In a component `"/foo/bar"` (namespace will be '/foo/bar'):

  ```
      my $cache = $m->cache;
  ```

- •

  Manually for an arbitrary namespace:

  ```
      my $cache = Poet::Cache->new(namespace => 'Some::Namespace');

      # or

      my $cache = MyApp::Cache->new(category => 'Some::Namespace');
  ```

### Using cache handle

```
    my $customer = $cache->get($name);
    if ( !defined $customer ) {
        $customer = get_customer_from_db($name);
        $cache->set( $name, $customer, "10 minutes" );
    }
    my $customer2 = $cache->compute($name2, "10 minutes", sub {
        get_customer_from_db($name2)
    });
```

See CHI and Mason::Plugin::Cache for more details.

## MODIFIABLE METHODS

These methods are not intended to be called externally, but may be useful to override or modify with method modifiers in subclasses.

- initialize\_caching

  Called once when the Poet environment is initialized. By default, calls `"__PACKAGE__->config"` with the configuration entry 'cache'.

## SEE ALSO

Poet

## AUTHOR

Jonathan Swartz \<swartz@pobox.com\>

## COPYRIGHT AND LICENSE

This software is copyright (c) 2012 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.