5.7.51. Bugzilla::Memcached

5.7.51.1. NAME

Bugzilla::Memcached - Interface between Bugzilla and Memcached.

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

5.7.51.3. 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()|Bugzilla/memcached.

5.7.51.4. 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.

5.7.51.5. 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).

5.7.51.6. 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_tsfield, 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 });

This documentation undoubtedly has bugs; if you find some, please file them here.