Анализ согласованного хеш-алгоритма, используемого в расширении php-memcache

**master** — исходная версия 3.0.8 beta.

**master-test** — первая тестовая версия на основе исходной.

**master-testv2** — окончательная тестовая версия на основе исходной, с добавлением методов тестирования.

Для получения дополнительной информации по данному проекту, пожалуйста, перейдите по ссылке:
http://my.oschina.net/imoses/blog

Серия статей «Анализ расширения php-memcache».

Модуль memcached для PHP
------------------------
Этому модулю требуется библиотека zlib, которая используется для сжатия и распаковки данных «на лету». Кроме того, для использования модуля необходим memcached.

Сайт memcached находится здесь:
    http://www.danga.com/memcached/

Вероятно, вам потребуется libevent для установки memcached:
Вы можете скачать его здесь: http://www.monkey.org/~provos/libevent/

Как запустить тесты:
1. sh tests/memcache.sh
2. TEST_PHP_EXECUTABLE=/usr/local/bin/php php -dextension=modules/memcache.so run-tests.php -d extension=modules/memcache.so

Новый API в версии 3
--------------------

В версии 3 представлен новый класс MemcachePool, который реализует новый API. Старый класс Memcache всё ещё поддерживается (но считается устаревшим) с тем же интерфейсом для обратной совместимости. Обратите внимание, что для использования функций CAS, значения по умолчанию для увеличения/уменьшения, добавления и вставки, а также бинарного протокола, необходима новая версия memcached.

Доступны новые директивы INI, позволяющие контролировать протокол, избыточность и выбор стратегии хеширования. Это:

* **Бинарный протокол приводит к меньшему трафику и более эффективен** как для клиента, так и для сервера при генерации и анализе.

    memcache.protocol = {ascii, binary}     # default ascii

* Когда эта функция включена, клиент отправляет запросы N серверам параллельно, что приводит к некоторой степени избыточности или зеркалирования, подходящей для использования в качестве хранилища сеансов.

Если целостность данных имеет большее значение, рекомендуется использовать настоящий реплицирующий бэкенд memcached, такой как «repcached» (http://sourceforge.net/projects/repcached/).

    memcache.redundancy = <int>         # default 1
    memcache.session_redundancy = <int>     # default 2

* Стратегия и функция хеширования. Согласованная стратегия хеширования теперь используется по умолчанию, поскольку она позволяет добавлять и удалять серверы из пула без переадресации большинства ключей на другой сервер (то есть аннулирования кеша).

    memcache.hash_strategy = {standard, consistent} # default consistent
    memcache.hash_function = {crc32, fnv}           # default crc32

* Сжатие включено по умолчанию. Порог, контролирующий минимальную длину строки, которая запускает сжатие, можно изменить следующим образом:

    memcache.compress_threshold = <int>     # default 20000

Директивы используются конструктором MemcachePool, поэтому вы можете создать несколько пулов с разными настройками, используя ini_set() творчески. Например:

ini_set('memcache.protocol', 'binary');

$binarypool = new MemcachePool();
$binarypool->addServer(...)

ini_set('memcache.protocol', 'ascii');
ini_set('memcache.redundancy', '2');

$redundantpool = new MemcachePool();
$redundantpool->addServer(...);

ini_set('memcache.redundancy', '1');

Новый интерфейс выглядит так:

class MemcachePool() {
    bool connect(string host, int tcp_port = 11211, int udp_port = 0, bool persistent = true, int weight = 1, int timeout = 1, int retry_interval = 15)
    bool addServer(string host, int tcp_port = 11211, int udp_port = 0, bool persistent = true, int weight = 1, int timeout = 1, int retry_interval = 15, bool status = true)
    bool setServerParams(string host, int tcp_port = 11211, int timeout = 1, int retry_interval = 15, bool status = true)

/**
 * Поддерживает получение флагов и значений CAS
 */
mixed get(mixed key, mixed &flags = null, mixed &cas = null)

/**
 * Поддержка мульти-набора, например
 *  $memcache->set(array('key1' => 'val1', 'key2' => 'val1'), null, 0, 60)
 */
bool add(mixed key, mixed var = null, int flag = 0, int exptime = 0)
bool set(mixed key, mixed var = null, int flag = 0, int exptime = 0)
bool replace(mixed key, mixed var = null, int flag = 0, int exptime = 0)

/**
 * Сравнение и замена, использует CAS **Параметры метода get() из MemcachePool:**

    bool cas(mixed key, mixed var = null, int flag = 0, int exptime = 0, int cas = 0)

**Описание:** выполняет операцию CAS (Compare and Swap).

**Параметры:**
* key — ключ;
* var — значение;
* flag — флаг;
* exptime — время жизни в секундах;
* cas — номер версии.

**Возвращаемое значение:** логическое значение true или false.

---

   bool append(mixed key, mixed var = null, int flag = 0, int exptime = 0);
   bool prepend(mixed key, mixed var = null, int flag = 0, int exptime = 0).

**Описание:** добавляет значение к существующему.

**Параметры:**
* key — ключ;
* var — добавляемое значение;
* flag — флаг;
* exptime — время жизни в секундах.

**Возвращаемое значение:** логическое значение true или false.

---

   bool delete(mixed key, int exptime = 0).

**Описание:** удаляет значение по ключу.

**Параметры:**
* key — ключ;
* exptime — время жизни в секундах (по умолчанию 0).

**Возвращаемое значение:** логическое значение true или false.

---

   mixed increment(mixed key, int value = 1, int defval = 0, int exptime = 0);
   mixed decrement(mixed key, int value = 1, int defval = 0, int exptime = 0).

**Описание:** увеличивает или уменьшает значение ключа на указанное число.

**Параметры:**
* key — ключ;
* value — величина изменения (по умолчанию +1 для increment и -1 для decrement);
* defval — новое значение, если ключа не существует (даже если 0);
* exptime — время жизни в секундах (по умолчанию 0).

**Возвращаемое значение:** целое число или массив целых чисел.

---

   bool setFailureCallback(function callback).

**Описание:** устанавливает функцию обратного вызова при ошибке запроса.

**Параметр:** callback — функция обратного вызова.

**Возвращаемое значение:** логическое значение true или false.

---

   string findServer(string key).

**Описание:** находит сервер, на который будет хэширован ключ.

**Параметр:** key — ключ.

**Возвращаемое значение:** строка «hostname:port» при успешном выполнении или false при неудаче (например, при неверном ключе).