<<

# Bugzilla::Memcached

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
  - Setting
  - Getting
  - Clearing
- Bugzilla::Object CACHE
- DIRECT DATABASE UPDATES

# NAME

Bugzilla::Memcached - Interface between Bugzilla and Memcached.

# SYNOPSIS

     use Bugzilla;

     my $memcached = Bugzilla->memcached;

     # grab data from the cache. there is no need to check if memcached is
     # available or enabled.
     my $data = $memcached->get({ key => 'data_key' });
     if (!defined $data) {
         # not in cache, generate the data and populate the cache for next time
         $data = some_long_process();
         $memcached->set({ key => 'data_key', value => $data });
     }
     # do something with $data

     # updating the profiles table directly shouldn't be attempted unless you know
     # what you're doing. if you do update a table directly, you need to clear that
     # object from memcached.
     $dbh->do("UPDATE profiles SET request_count=10 WHERE login_name=?", undef, $login);
     $memcached->clear({ table => 'profiles', name => $login });

# DESCRIPTION

If Memcached is installed and configured, Bugzilla can use it to cache data across requests and between webheads. Unlike the request and process caches, only scalars, hashrefs, and arrayrefs can be stored in Memcached.

Memcached integration is only required for large installations of Bugzilla -- if you have multiple webheads then configuring Memcache is recommended.

Bugzilla::Memcached provides an interface to a Memcached server/servers, with the ability to get, set, or clear entries from the cache.

The stored value must be an unblessed hashref, unblessed array ref, or a scalar. Currently nested data structures are supported but require manual de-tainting after reading from Memcached (flat data structures are automatically de-tainted).

All values are stored in the Memcached systems using the prefix configured with the `memcached_namespace` parameter, as well as an additional prefix managed by this class to allow all values to be cleared when `checksetup.pl` is executed.

Do not create an instance of this object directly, instead use Bugzilla->memcached().

# METHODS

`enabled`

  Returns true if Memcached support is available and enabled.

## Setting

Adds a value to Memcached.

`set({ key => $key, value => $value })`

  Adds the `value` using the specific `key`.

`set({ table => $table, id => $id, name => $name, data => $data })`

  Adds the `data` using a keys generated from the `table`, `id`, and `name`. All three parameters must be provided, however `name` can be provided but set to `undef`.

  This is a convenience method which allows cached data to be later retrieved by specifying the `table` and either the `id` or `name`.

`set_config({ key => $key, data => $data })`

  Adds the `data` using the `key` while identifying the data as part of Bugzilla's configuration (such as fields, products, components, groups, etc). Values set with `set_config` are automatically cleared when changes are made to Bugzilla's configuration.

## Getting

Retrieves a value from Memcached. Returns `undef` if no matching values were found in the cache.

`get({ key => $key })`

  Return `value` with the specified `key`.

`get({ table => $table, id => $id })`

  Return `value` with the specified `table` and `id`.

`get({ table => $table, name => $name })`

  Return `value` with the specified `table` and `name`.

`get_config({ key => $key })`

  Return `value` with the specified `key` from the configuration cache. See `set_config` for more information.

## Clearing

Removes the matching value from Memcached.

`clear({ key => $key })`

  Removes `value` with the specified `key`.

`clear({ table => $table, id => $id })`

  Removes `value` with the specified `table` and `id`, as well as the corresponding `table` and `name` entry.

`clear({ table => $table, name => $name })`

  Removes `value` with the specified `table` and `name`, as well as the corresponding `table` and `id` entry.

`clear_config({ key => $key })`

  Remove `value` with the specified `key` from the configuration cache. See `set_config` for more information.

`clear_config`

  Removes all configuration related values from the cache. See `set_config` for more information.

`clear_all`

  Removes all values from the cache.

# Bugzilla::Object CACHE

The main driver for Memcached integration is to allow Bugzilla::Object based objects to be automatically cached in Memcache. This is enabled on a per-package basis by setting the `USE_MEMCACHED` constant to any true value.

The current implementation is an opt-in (USE_MEMCACHED is false by default), however this will change to opt-out once further testing has been completed (USE_MEMCACHED will be true by default).

# DIRECT DATABASE UPDATES

If an object is cached and the database is updated directly (instead of via `$object->update()`), then it's possible for the data in the cache to be out of sync with the database.

As an example let's consider an extension which adds a timestamp field `last_activitiy_ts` to the profiles table and user object which contains the user's last activity. If the extension were to call `$user->update()`, then an audit entry would be created for each change to the `last_activity_ts` field, which is undesirable.

To remedy this, the extension updates the table directly. It's critical with Memcached that it then clears the cache:

     $dbh->do("UPDATE profiles SET last_activity_ts=? WHERE userid=?",
              undef, $timestamp, $user_id);
     Bugzilla->memcached->clear({ table => 'profiles', id => $user_id });

<<