Memcached::libmemcached is a very thin, highly efficient, wrapper around the libmemcached library. It's implemented almost entirely in C.

It gives full access to the rich functionality offered by libmemcached. libmemcached is fast, light on memory usage, thread safe, and provide full access to server side methods.

- Synchronous and Asynchronous support.
- TCP and Unix Socket protocols.
- A half dozen or so different hash algorithms.
- Implementations of the new cas, replace, and append operators.
- Man pages written up on entire API.
- Implements both modulo and consistent hashing solutions.

(Memcached::libmemcached is fairly new and not all the functions in libmemcached have perl interfaces yet. It's usually trivial to add functions - just a few lines in libmemcached.xs, a few lines of documentation, and a few lines of testing. Volunteers welcome!)

The libmemcached library documentation (which is bundled with this module) serves as the primary reference for the functionality.

This documentation provides summary of the functions, along with any issues specific to this perl interface, and references to the documentation for the corresponding functions in the underlying library.

The term "memcache" is used to refer to the memcached_st structure at the heart of the libmemcached library. We'll use $memc to represent this structure in perl code. (The libmemcached library documentation uses ptr.)

The function names in the libmemcached library have exactly the same names in Memcached::libmemcached.

The function arguments are also the same as the libmemcached library and documentation, with two exceptions:

* There are no length arguments. Wherever the libmemcached documentation shows a length argument (input or output) the corresponding argument doesn't exist in the Perl API because it's not needed.

* Some arguments are optional.

Many libmemcached function arguments are output values: the argument is the address of the value that the function will modify. For these the perl function will modify the argument directly if it can. For example, in this call:

$value = memcached_get($memc, $key, $flags, $rc);

The $flags and $rc arguments are output values that are modified by the memcached_get() function.

See the "Type Mapping" section for the fine detail of how each argument type is handled.

Most of the functions return an integer status value. This is shown as memcached_return in the libmemcached documentation.

In the perl interface this value is not returned directly. Instead a simple boolean is returned: true for 'success', defined but false for some 'unsuccessful' conditions like 'not found', and undef for all other cases (i.e., errors).

Functions relating to managing lists of servers (memcached_server_push, and memcached_server_list) have not been implemented because they're not needed and likely to be deprecated by libmemcached.

Functions relating to iterating through results (memcached_result_*) have not been implemented yet. They're not a priority because similar functionality is available via the callbacks. See "set_callback_coderefs".

Triggers the asynchronous fetching of multiple keys at once. For multiple key operations it is always faster to use this function. You must then use memcached_fetch() or memcached_fetch_result() to retrieve any keys found. No error is given on keys that are not found.

memcached servers have the ability to increment and decrement unsigned integer keys (overflow and underflow are not detected). This gives you the ability to use memcached to generate shared sequences of values.

Increments the integer value associated with $key by $offset and returns the new value in $new_value_out.

If the object specified by key does not exist, one of two things may happen: If the expiration value is MEMCACHED_EXPIRATION_NOT_ADD, the operation will fail. For all other expiration values, the operation will succeed by seeding the value for that key with a initial value to expire with the provided expiration time. The flags will be set to zero.

Decrements the integer value associated with $key by $offset and returns the new value in $new_value_out.

If the object specified by key does not exist, one of two things may happen: If the expiration value is MEMCACHED_EXPIRATION_NOT_ADD, the operation will fail. For all other expiration values, the operation will succeed by seeding the value for that key with a initial value to expire with the provided expiration time. The flags will be set to zero.

memcached_strerror() takes a memcached_return value and returns a string describing the error. The string should be treated as read-only (it may be so in future versions). See also Memcached::libmemcached::memcached_strerror.

This function is rarely needed in the Perl interface because the return code is a dualvar that already contains the error string.

Normally libmemcached hashes the $key value to select which memcached server to communicate with. If you have several keys relating to a single object then it's very likely that the corresponding values will be stored in different memcached servers.

It would be more efficient, in general, when setting and getting multiple related values, if it was possible to specify a different value to be hashed to select which memcached server to communicate with. With libmemcached, you can.

Most of the functions for setting and getting values have *_by_key variants for exactly this reason. These all have an extra $master_key parameter immediately after the $memc parameter. For example:

Returns the error message and code from the most recent call to any libmemcached function that returns a memcached_return, which most do.

The return value is a dualvar, like $!, which means it has separate numeric and string values. The numeric value is the memcached_return integer value, and the string value is the corresponding error message what memcached_strerror() would return.

As a special case, if the memcached_return is MEMCACHED_ERRNO, indicating a system call error, then the string returned by strerror() is appended.

This method is also currently callable as memcached_errstr() for compatibility with an earlier version, but that deprecated alias will start warning and then cease to exist in future versions.

Combines memcached_mget() and a memcached_fetch() loop into a single highly efficient call.

Fetched values are stored in \%dest_hash, updating existing values or adding new ones as appropriate.

This method is also currently callable as memcached_mget_into_hashref() for compatibility with an earlier version, but that deprecated alias will start warning and then cease to exist in future versions.

So it's very similar to "mget_into_hashref" but less efficient for large numbers of keys (because the keys have to be pushed onto the argument stack) and less flexible (because you can't add/update elements into an existing hash).

This method is provided to optimize subclasses that want to provide a Cache::Memcached compatible API with maximum efficiency. Note, however, that get_multi does not support the Cache::Memcached feature where a key can be a reference to an array [ $master_key, $key ]. Use "memcached_mget_by_key" directly if you need that feature.

This interface is experimental and likely to change. (It's also currently used by Cache::Memcached::libmemcached, so don't use it if you're using that module.)

Specify functions which will be executed when values are set and/or get using $memc.

When the callbacks are executed $_ is the value and the arguments are the key and flags value. Both $_ and the flags may be modified.

Currently the functions must return an empty list.

This method is also currently callable as memcached_set_callback_coderefs() for compatibility with an earlier version, but that deprecated alias will start warning and then cease to exist in future versions.

Calls the memcached_stat_execute() function to issue a "STAT $stats_args" command to the connected memcached servers. The $stats_args argument is usually an empty string.

The callback function is called for each return value from each server. The callback will be passed at least these parameters:

sub my_stats_callback {
my ($key, $value, $hostport) = @_;
# Do what you like with the above!
return;
}

Currently the callback must return an empty list.

Prior to version 0.4402 the callback was passed a fourth argument which was a copy of the $stats_args value. That is no longer the case. As a temporary aid to migration, the walk_stats method does local $_ = $stats_args and passes $_ as the forth argument. That will work so long as the code in the callback doesn't alter $_. If your callback code requires $stats_args you should change it to be a closure instead.