Bric::App::Cache(3p)  User Contributed Perl Documentation Bric::App::Cache(3p)



NAME
       Bric::App::Cache - Object for managing Application-wide global data.

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2006-03-18 01:26:34 +0100 (Sat, 18 Mar 2006) $

SYNOPSIS
         use Bric::App::Cache;
         my $c = Bric::App::Cache->new;
         $c = $c->set($key, $val);
         my $val = $c->get($key);

         my $time = $c->get_lmu_time;
         $c = $c->set_lmu_time;

         my $site_id = $c->get_user_cx($user_id);
         $c = $c->set_user_cx($user_id, $site_id);

DESCRIPTION
       This module provides a cache object to cache data that needs to persist
       across all processes and across all requests, through time and space.
       The cache is cleared on server restart - for more permenant storage see
       Bric::Util::DBI.

       A Bric::App::Cache object is available from Mason components in the
       global variable $c.

IMPLEMENTATION
       This module is implemented as a two-level cache in order to provide the
       best possible performance.

       The first level is provided by Cache::Mmap. Cache::Mmap is a very fast,
       shared, file-based cache. However, it is also a fixed-size cache that
       will drop items from the cache when the cache becomes full or the item
       to be stored is too large.

       When an object cannot be stored in the first-level cache it is passed
       to the second-level. The second-level cache (also known as a backing
       store) is provided by Cache::Cache. Cache::Cache is quite a bit slower
       than Cache::Mmap but has the advantage of being variable-sized. As such
       it grows dynamically and won't refuse to store an object unless it runs
       out of disk space.

       The "get()" procedure is:

       o   Look in first-level cache for item.  If found, return it and
           finish.

       o   Look in second-level cache for item.  If found, return it and
           finish.

       o   Note in first-level cache that item is not in second-level cache.
           This will prevent a look in the second-level cache on the next
           request for this item.

       And the "set()" prodedure is:

       o   Try to set the item in the first-level cache. If success, finish.
           If fail, delete old item if it exists.

       o   Set the item in the second-level cache. This must succeed or a
           fatal error will result.

       NOTE: Under "QA_MODE" all "set()"s are sent to the secondary-cache to
       allow the cache to be debugged. Cache::Mmap lacks the ability to list
       all keys in the cache which is used by the "QA_MODE" code.

INTERFACE
   Constructors
       my $c = Bric::App::Cache->new()
           Instantiates a Bric::App::Cache object. No initial values may be
           passed.

           Throws:

           o   Unable to instantiate cache.

           Side Effects: NONE.

           Notes: NONE.

       my $org = Bric::App::Cache->lookup()
           Not implemented - not needed.

           Throws:

           o   Bric::App::Cache::lookup() method not implemented.

           Side Effects: NONE.

           Notes: NONE.

       Bric::App::Cache->list()
           Not implemented - not needed.

           Throws:

           o   Bric::App::Cache::list() method not implemented.

           Side Effects: NONE.

           Notes: NONE.

   Destructors
       $org->DESTROY
           Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

   Public Class Methods
       Bric::App::Cache->list_ids()
           Not implemented - not needed.

           Throws:

           o   Bric::App::Cache::list_ids() method not implemented.

           Side Effects: NONE.

           Notes: NONE.

       Bric::App::Cache->clear()
           Clears the cache of all stored data.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

   Public Instance Methods
       my $val = $c->get($key)
           Returns a value for the specified key. Call $c->set($key, $value)
           to store a value.

           Throws:

           o   Unable to fetch value from the cache.

           Side Effects: NONE.

           Notes: NONE.

       $self = $c->set($key, $value);
           Stores $value as referenced by $key. Call $c->get($key) to retrieve
           $value.

           Throws:

           o   Unable to cache value.

           Side Effects: NONE.

           Notes: NONE.

       my $lmu_time = $c->get_lmu_time
           Returns the epoch time when a user object was last modified.

           Throws:

           o   Unable to fetch value from the cache.

           Side Effects: NONE.

           Notes: NONE.

       $self = $c->set_lmu_time($lmu_time)
           Sets the epoch time when a user object was last modified.

           Throws:

           o   Unable to cache value.

           Side Effects: NONE.

           Notes: NONE.

       my $site_id = $c->get_user_cx($user_id)
           Returns the current site context for the user with the $user_id ID.
           A value of 0 (zero) means that there is no context, in which case
           the user can see all the workflows from all the sites to which she
           has access. If the value is undefined, then the context isn't set.

           Side Effects: If "QA_MODE" is enabled, then $user_id and $site_id
           will be checked to ensure that they are proper arguments.

       $c = $c->set_user_cx($user_id, $site_id)
           Sets the site context for the user with the $user_id ID. Pass in
           "undef" to indicate an unknown context. Pass in 0 (zero) to
           indicate that the user has no context, and so can access all of the
           workflows in all of the sites to which she has access. Otherwise,
           simply pass in the site ID the user has selected.

           Side Effects: If "QA_MODE" is enabled, then $user_id and $site_id
           will be checked to ensure that they are proper arguments.

PRIVATE
   Private Class Methods
       NONE.

   Private Instance Methods
       NONE.

   Private Functions
       $val = _read_backing_store($key)
           Reads a value from the backing store.  See the IMPLEMENTATION
           section avove for details.

           Throws:

           o   Unable to fetch value from the backing cache.

           Side Effects: NONE.

           Notes: NONE.

       _write_backing_store($key, $val)
           Writes a value to the backing store.  See the IMPLEMENTATION
           section avove for details.

           Throws:

           o   Unable to cache value in the backing cache.

           Side Effects: NONE.

           Notes: NONE.

NOTES
       NONE.

AUTHOR
       David Wheeler <david@justatheory.com>

       Sam Tregar <stregar@about-inc.com>

SEE ALSO
       Bric, Bric::App::Session, Apache::Session



perl v5.12.2                      2006-03-17              Bric::App::Cache(3p)
