NAME

Krang::Cache - a read-only, non-persistent, private, LRU cache

SYNOPSIS

Turn on the cache:

  pkg('Cache')->start();

Do some *read-only* work as usual:

  @stories = Krang::Story::find();
  $publisher->publish_stories(...);
  ...

Turn off the cache:

  pkg('Cache')->stop();

DESCRIPTION

This module implements a read-only, non-persistent, private, LRU cache. Let me break it down for you:

• readonly
  
This cache is read-only, which means that you can't use it if you'll be trying to save objects in the cache. Any attempt to do so will result in an error.
• non-persistent
  
This cache is held in memory and won't be visible in other processes.
• private
  
Since the cache is in process memory it won't affect other processes.
• LRU
  
This cache expires objects in Least Recently Used order. Whenever an object is requested from the cache it goes to the top of the list and objects are always removed from the bottom when the cache is full.

Currently the cache stores Krang::Element, Krang::User and Krang::Group objects, and is used solely during publishing.

INTERFACE

• Krang::Cache->start()
  
Start caching objects. Calling this multiple times increments an internal counter, so it's safe to have nested cache contexts and the cache won't go off till the last one stop()s.
• Krang::Cache->stop()
  
Stop caching objects. Calling this multiple times decrements an internal counter and doesn't take effect till the count reaches 0.

NOTE: It is very important to make sure stop() gets called after start(). You should have an eval{} around code between start() and stop() and be sure to call stop() if the code die()s. Failing to do so can produce very strange results in persistent environments like mod_perl.

• Krang::Cache->active()
  
Returns 1 if the cache is on, 0 if it's off.
• $size = Krang::Cache->size()
  
• Krang::Cache->size($size)
  
Get or set the cache size. This is the number of objects allowed to live in the cache at one time. Setting this value less than the current fill will cause objects to be removed.

The default cache size is 1000.

• ($hits, $loads, $fill) = Krang::Cache->stats()
  
Returns how many times the cache had the object requested, how many objects have been loaded into the cache and how many objects currently reside in the cache. This may be called after stop() and the totals are zeroed by start().
• $obj = Krang::Cache->get('Krang::Element' => $element_id)
  
Request an object from the cache, using a class name and an id. Returns undef if the object is not in the cache or if the cache is off.
• $obj = Krang::Cache->set('Krang::Element' => $element_id => $element)
  
Sets an object in the cache, using a class name, an id and a reference to the object.