User:AnomieBOT/source/AnomieBOT/API/Cache.pm/doc

NAME

AnomieBOT::API::Cache - AnomieBOT API cache base class

SYNOPSIS

 use AnomieBOT::API::Cache;
 
 my $cache = AnomieBOT::API::Cache->create( $subclass, $optionString );
 $cache->set( 'foo', 'bar' );
 say $cache->get( 'foo' );  # Outputs "bar"

DESCRIPTION

AnomieBOT::API::Cache is a base class for non-persistent caching of data. The interface is generally inspired by memcached.

KEYS

The general idea is that data items can be stored under "keys", which are ASCII strings, no whitespace or angle brackets, with a maximum length of 250 bytes.

To make things easier to use, the following 'magic' sequences are recognized in a key:

<>

Marks a "prefix" in the key, which may be flushed with $cache->flush_prefix(). Note that keys ending with <> are reserved for internal use.

<<text>>

Internally, text is replaced with a hash of the text. This is useful if a page title is to be included in the key to avoid exceeding the 250-byte limit.

Note that the magic sequences may internally expand to more bytes than they use in the original string, causing excess-key-length errors.

METHODS

AnomieBOT::API::Cache->create( $subclass, $optionString )

Creates a new AnomieBOT::API::Cache object of the specified subclass, passing it the specified option string. The subclass will be "AnomieBOT::API::Cache::$subclass"; see the documentation for each subclass for details on the options string.

$cache->get( $key, ... )

If only one key is passed, returns the value stored for $key, or undef if the key does not exist.

If multiple keys are passed, returns a hash mapping each key to the stored value. If the key does not exist in the cache, it will not be present in the returned hash.

$cache->gets( $key, ... )

If only one key is passed, returns a list of two values: the value (if any) stored for $key and a token for use with cas().

If multiple keys are passed, returns two hashes: one mapping each key to the stored value and a second mapping each key to the CAS token. If the key does not exist in the cache, it will not be present in the first hash.

Note that tokens may be undef; this is not an error.

$cache->set( $key, $value )

$cache->set( $key, $value, $expiry )

$cache->set( \%hash )

$cache->set( \%hash, $expiry )

Stores one or more values to the cache. The forms including a hashref are equivalent to multiple calls to $cache->set().

Values may be anything accepted by Storable::freeze.

If specified, $expiry specifies when the cache item should expire. The value is considered the number of seconds the value is valid for if less than or equal to 315360000 (approximately 10 years), or a Unix epoch value (number of seconds since 1970-01-01T00:00:00Z) if greater.

The first two forms return a boolean (true on success, false on failure), or undef on error; the forms taking a hashref return a hash mapping each key to a boolean or undef.

$cache->add( $key, $value )

$cache->add( $key, $value, $expiry )

$cache->add( \%hash )

$cache->add( \%hash, $expiry )

Just like $cache->set(), except that the value is only stored if the key doesn't already exist in the cache.

$cache->replace( $key, $value )

$cache->replace( $key, $value, $expiry )

$cache->replace( \%hash )

$cache->replace( \%hash, $expiry )

Just like $cache->set(), except that the value is only stored if the key already exists in the cache.

$cache->cas( $key, $value, $token )

$cache->cas( $key, $value, $token, $expiry )

$cache->cas( \%hash, \%tokens )

$cache->cas( \%hash, \%tokens, $expiry )

Just like $cache->set(), except that the value is only stored if the value for the key has not been modified since the CAS token was fetched from $cache->gets().

Note that, in the hashref case, \%hash holds the key-value pairs to be stored while \%tokens holds the tokens for each key.

$cache->delete( $key, ... )

Deletes the specified keys from the cache. Return values are the same as for $cache->set().

$cache->flush_prefix( $prefix )

Causes all keys beginning with $prefix followed by <> to be effectively removed from the cache. Note this may not actually delete the keys, it may just make them inaccessible by changing how <> is munged.

$cache->incr( $key )

$cache->incr( $key, $amount )

$cache->decr( $key )

$cache->decr( $key, $amount )

Increment or decrement the value of the key. Note that the key must already exist in the cache, and the value and amount must be positive integers.

$amount defaults to 1 if not given. Returns the new value for the key on success ("0 but true" if the value is 0), false on failure, or undef on error.

$cache->touch( $expiry, $key, ... )

Updates the expiry of the specified keys from the cache. Return values are the same as for $cache->set().

INTERNAL METHODS

These methods are intended for use by subclasses.

AnomieBOT::API::Cache->explode_option_string( $optionString )

Converts an option string of the form "key=value;key=value" to a hash. Semicolons and backslashes must be escaped with a backslash.

$cache->munge_key( $key )

Replaces the 'magic' tokens in $key and validates it. Returns the munged key on success, or undef on failure. May call $cache->munge_prefix() and/or $cache->munge_hash().

$cache->munge_prefix( $prefix )

Used to handle the <> magic token in a key. $prefix is the bit of the key before the <>. Returns some bit of text to insert inside the <>. Do not include angle brackets, whitespace, or non-ASCII characters in your return value, it will break things.

The default implementation tries to look up the key "$prefix<>". If not found, a new random value is stored under that key. In either case, the value is returned.

If you change $cache->flush_prefix(), you'll probably want to change this too. If nothing else, have it return the empty string.

$cache->munge_hash( $text )

Used to handle the <<text>> magic token in a key. Returns the hash text, by default the base-64 representation of SHA-256.

COPYRIGHT

Copyright 2013 Anomie

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.