Spec-Zone .ru
спецификации, руководства, описания, API

15.6.3.3. Используя libmemcached с C и C++

libmemcached библиотека обеспечивает и C и интерфейсы C++ к memcached и является также основанием для многих различных дополнительных реализаций API, включая Perl, Python и Ruby. Понимание ядра libmemcached функции могут помочь при использовании этих других интерфейсов.

Библиотека C является самой всесторонней библиотекой интерфейса для memcached и обеспечивает функции и операционные системы, не всегда представляемые в интерфейсах, не основанных на libmemcached библиотека.

Различные функции могут быть разделены согласно их основной работе. В дополнение к функциям, которые взаимодействуют через интерфейс к базовому API, много служебных функций обеспечивают расширенную функциональность, такую как добавление и данные предна ожидании.

Создавать и устанавливать libmemcached, загрузите libmemcached пакет, выполненный, конфигурирует, и затем создает и устанавливает:

shell> tar xjf libmemcached-0.21.tar.gzshell> cd libmemcached-0.21shell> ./configureshell> makeshell> make install

На многих Операционных системах Linux можно установить соответствие libmemcached пакет через обычную конфетку, склонную - добираются, или подобные команды.

Чтобы создать приложение, которое пользуется библиотекой, сначала устанавливает список серверов. Любой непосредственно управляет серверами, сконфигурированными в пределах основного memcached_st структура, или отдельно заполняют список серверов, и затем добавляют этот список к memcached_st структура. Последний метод используется в следующем примере. Как только список сервера был установлен, можно вызвать функции, чтобы сохранить или получить данные. Простое приложение для того, чтобы установить предварительно установленное значение в localhost обеспечивается здесь:

#include <stdio.h>#include <string.h>#include <unistd.h>#include <libmemcached/memcached.h>int main(int argc, char *argv[]){  memcached_server_st *servers = NULL;  memcached_st *memc;  memcached_return rc;  char *key= "keystring";  char *value= "keyvalue";  memcached_server_st *memcached_servers_parse (char *server_strings);  memc= memcached_create(NULL);  servers= memcached_server_list_append(servers, "localhost", 11211, &rc);  rc= memcached_server_push(memc, servers);  if (rc == MEMCACHED_SUCCESS)    fprintf(stderr,"Added server successfully\n");  else    fprintf(stderr,"Couldn't add server: %s\n",memcached_strerror(memc, rc));  rc= memcached_set(memc, key, strlen(key), value, strlen(value), (time_t)0, (uint32_t)0);  if (rc == MEMCACHED_SUCCESS)    fprintf(stderr,"Key stored successfully\n");  else    fprintf(stderr,"Couldn't store key: %s\n",memcached_strerror(memc, rc));  return 0;}

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

Чтобы создать приложение, определите memcached библиотека:

shell> gcc -o memc_basic memc_basic.c -lmemcached

Выполнение вышеупомянутого примера приложения, после запуска memcached сервера, должно возвратить сообщение успеха:

shell> memc_basicAdded server successfullyKey stored successfully

15.6.3.3.1. libmemcached Основные Функции

Основа libmemcached функции, которым позволяют Вы создать, уничтожьте и клонируйте основное memcached_st структура, которая используется, чтобы взаимодействовать через интерфейс с memcached серверы. Основные функции определяются ниже:

memcached_st *memcached_create (memcached_st *ptr);

Создает новое memcached_st структура для использования с другим libmemcached API-функции. Можно предоставить существующее, статическое, memcached_st структура, или NULL иметь новое, структурированное выделенный. Возвращает указатель на создаваемую структуру, или NULL при отказе.

void memcached_free (memcached_st *ptr);

Освобождает структуру и память, выделенную ранее создаваемый memcached_st структура.

memcached_st *memcached_clone(memcached_st *clone, memcached_st *source);

Клонирует существующее memcached структура от указанного source, копирование значений по умолчанию и списка серверов определяется в структуре.

15.6.3.3.2. libmemcached Функции сервера

libmemcached API использует список серверов, сохраненных в пределах memcached_server_st структура, чтобы действовать как список серверов, используемых остальной частью функций. Использовать memcached, Вы сначала создаете список сервера, и затем применяете список серверов к допустимому libmemcached объект.

Поскольку список серверов, и список серверов в пределах активного libmemcached объектом можно управлять отдельно, можно обновить и управлять списками сервера в то время как активное libmemcached интерфейс работает.

Функции для того, чтобы управлять списком серверов в пределах a memcached_st структура:

memcached_return   memcached_server_add (memcached_st *ptr,                         char *hostname,                         unsigned int port);

Добавляет сервер, используя данный hostname и port в memcached_st поданная структура ptr.

memcached_return   memcached_server_add_unix_socket (memcached_st *ptr,                                     char *socket);

Добавляет сокет Unix к списку серверов, сконфигурированных в memcached_st структура.

unsigned int memcached_server_count (memcached_st *ptr);

Возвращает количество числа сконфигурированных серверов в пределах memcached_st структура.

memcached_server_st *   memcached_server_list (memcached_st *ptr);

Возвращает массив всех определенных узлов в пределах a memcached_st структура.

memcached_return   memcached_server_push (memcached_st *ptr,                          memcached_server_st *list);

Продвигает существующий список серверов на список серверов, сконфигурированных для тока memcached_st структура. Это добавляет серверы до конца существующего списка, и копии не проверяются.

memcached_server_st структура может использоваться, чтобы создать список memcached серверы, которые могут тогда быть применены индивидуально к memcached_st структуры.

memcached_server_st *   memcached_server_list_append (memcached_server_st *ptr,                                 char *hostname,                                 unsigned int port,                                 memcached_return *error);

Добавляет сервер, с hostname и port, к серверу перечисляют в ptr. Код результата обрабатывается error параметр, который должен указать на существующее memcached_return переменная. Функция возвращает указатель на возвращенный список.

unsigned int memcached_server_list_count (memcached_server_st *ptr);

Возвращает число серверов в списке сервера.

void memcached_server_list_free (memcached_server_st *ptr);

Освобождает память, связанную со списком сервера.

memcached_server_st *memcached_servers_parse (char *server_strings);

Анализирует строку, содержащую список серверов, где отдельные серверы разделяются запятой, пространством, или обоими, и где отдельные серверы имеют форму server[:port]. Возвращаемое значение является структурой списка сервера.

15.6.3.3.3. libmemcached Функции множества

Связанные с набором функции в пределах libmemcached обеспечьте ту же самую функциональность как базовые функции, поддерживаемые memcached протокол. Полное определение для различных функций является тем же самым для всех основных функций (add, replace, prepend, append). Например, функциональное определение для memcached_set() :

memcached_return   memcached_set (memcached_st *ptr,                  const char *key,                  size_t key_length,                  const char *value,                  size_t value_length,                  time_t expiration,                  uint32_t flags);

ptr memcached_st структура. key и key_length определите ключевое имя и длину, и value и value_length соответствующее значение и длина. Можно также установить истечение и дополнительные флаги. Для получения дополнительной информации см. Раздел 15.6.3.3.5, "Управляя libmemcached Поведения".

Эта таблица обрисовывает в общих чертах остаток от связанного с набором libmemcached функции и эквивалентные базовые функции поддерживаются memcached протоколом.

libmemcached Функция Эквивалентная Базовая Функция
memcached_set(memc, key, key_length, value, value_length, expiration, flags) Универсальный set() работа.
memcached_add(memc, key, key_length, value, value_length, expiration, flags) Универсальный add() функция.
memcached_replace(memc, key, key_length, value, value_length, expiration, flags) Универсальный replace().
memcached_prepend(memc, key, key_length, value, value_length, expiration, flags) Предварительно ожидает указанное value перед текущей стоимостью указанного key.
memcached_append(memc, key, key_length, value, value_length, expiration, flags) Добавляет указанное value после текущей стоимости указанного key.
memcached_cas(memc, key, key_length, value, value_length, expiration, flags, cas) Перезаписывает данные для данного ключа пока соответствие cas значение является все еще тем же самым в пределах сервера.
memcached_set_by_key(memc, master_key, master_key_length, key, key_length, value, value_length, expiration, flags) Подобный обобщению set(), но имеет опцию дополнительного главного ключа, который может использоваться, чтобы идентифицировать отдельный сервер.
memcached_add_by_key(memc, master_key, master_key_length, key, key_length, value, value_length, expiration, flags) Подобный обобщению add(), но имеет опцию дополнительного главного ключа, который может использоваться, чтобы идентифицировать отдельный сервер.
memcached_replace_by_key(memc, master_key, master_key_length, key, key_length, value, value_length, expiration, flags) Подобный обобщению replace(), но имеет опцию дополнительного главного ключа, который может использоваться, чтобы идентифицировать отдельный сервер.
memcached_prepend_by_key(memc, master_key, master_key_length, key, key_length, value, value_length, expiration, flags) Подобный memcached_prepend(), но имеет опцию дополнительного главного ключа, который может использоваться, чтобы идентифицировать отдельный сервер.
memcached_append_by_key(memc, master_key, master_key_length, key, key_length, value, value_length, expiration, flags) Подобный memcached_append(), но имеет опцию дополнительного главного ключа, который может использоваться, чтобы идентифицировать отдельный сервер.
memcached_cas_by_key(memc, master_key, master_key_length, key, key_length, value, value_length, expiration, flags) Подобный memcached_cas(), но имеет опцию дополнительного главного ключа, который может привыкнуть к identifyan отдельному серверу.

by_key методы добавляют два дальнейших параметра, которые определяют главный ключ, чтобы использоваться и примененными во время хеширующего этапа для того, чтобы выбрать серверы. Можно видеть это в следующем определении:

memcached_return   memcached_set_by_key(memcached_st *ptr,                        const char *master_key,                        size_t master_key_length,                        const char *key,                        size_t key_length,                        const char *value,                        size_t value_length,                        time_t expiration,                        uint32_t flags);

Все функции возвращают значение типа memcached_return, который можно сравнить с MEMCACHED_SUCCESS постоянный.

15.6.3.3.4. libmemcached Получите Функции

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

Основная функция получать-стиля, которая эквивалентна обобщению get() memcached_get(). Эта функция возвращает указатель строки, указывая на значение, связанное с указанным ключом.

char *memcached_get (memcached_st *ptr,                     const char *key, size_t key_length,                     size_t *value_length,                     uint32_t *flags,                     memcached_return *error);

Мультиключ добирается, memcached_mget(), также доступно. Используя многократный ключ добираются, работа намного более быстра, чтобы сделать в одном блоке чем получение значений ключа с отдельными звонками memcached_get(). Чтобы запустить мультиключ получают, вызывают memcached_mget():

memcached_return    memcached_mget (memcached_st *ptr,                    char **keys, size_t *key_length,                    unsigned int number_of_keys);

Возвращаемое значение является успехом работы. keys параметр должен быть массивом строк, содержащих ключи, и key_length массив, содержащий длину каждого соответствующего ключа. number_of_keys число ключей, предоставленных в массиве.

Чтобы выбрать отдельные значения, использовать memcached_fetch() получить каждое соответствующее значение.

char *memcached_fetch (memcached_st *ptr,                       const char *key, size_t *key_length,                       size_t *value_length,                       uint32_t *flags,                       memcached_return *error);

Функция возвращает значение ключа, с key, key_length и value_length параметры, заполняемые с соответствующим ключом и информацией о длине. Функциональные возвраты NULL когда нет больше значений, которое будет возвращено. Полный пример, включая заполнение ключевых данных и возврат информации обеспечивается здесь.

#include <stdio.h>#include <sstring.h>#include <unistd.h>#include <libmemcached/memcached.h>int main(int argc, char *argv[]){  memcached_server_st *servers = NULL;  memcached_st *memc;  memcached_return rc;  char *keys[]= {"huey", "dewey", "louie"};  size_t key_length[3];  char *values[]= {"red", "blue", "green"};  size_t value_length[3];  unsigned int x;  uint32_t flags;  char return_key[MEMCACHED_MAX_KEY];  size_t return_key_length;  char *return_value;  size_t return_value_length;  memc= memcached_create(NULL);  servers= memcached_server_list_append(servers, "localhost", 11211, &rc);  rc= memcached_server_push(memc, servers);  if (rc == MEMCACHED_SUCCESS)    fprintf(stderr,"Added server successfully\n");  else    fprintf(stderr,"Couldn't add server: %s\n",memcached_strerror(memc, rc));  for(x= 0; x < 3; x++)    {      key_length[x] = strlen(keys[x]);      value_length[x] = strlen(values[x]);      rc= memcached_set(memc, keys[x], key_length[x], values[x],                        value_length[x], (time_t)0, (uint32_t)0);      if (rc == MEMCACHED_SUCCESS)        fprintf(stderr,"Key %s stored successfully\n",keys[x]);      else        fprintf(stderr,"Couldn't store key: %s\n",memcached_strerror(memc, rc));    }  rc= memcached_mget(memc, keys, key_length, 3);  if (rc == MEMCACHED_SUCCESS)    {      while ((return_value= memcached_fetch(memc, return_key, &return_key_length,                                            &return_value_length, &flags, &rc)) != NULL)        {          if (rc == MEMCACHED_SUCCESS)            {              fprintf(stderr,"Key %s returned %s\n",return_key, return_value);            }        }    }  return 0;}

Выполнение вышеупомянутого приложения производит следующий вывод:

shell> memc_multi_fetchAdded server successfullyKey huey stored successfullyKey dewey stored successfullyKey louie stored successfullyKey huey returned redKey dewey returned blueKey louie returned green

15.6.3.3.5. Управление libmemcached Поведения

Поведение libmemcached может быть изменен, устанавливая один или более флагов поведения. Они могут или быть установлены глобально, или они могут быть применены во время звонка в отдельные функции. Некоторые поведения также принимают дополнительную установку, такую как хеширующий механизм, используемый, выбирая серверы.

Установить глобальные поведения:

memcached_return   memcached_behavior_set (memcached_st *ptr,                           memcached_behavior flag,                           uint64_t data);

Получить текущую установку поведения:

uint64_t   memcached_behavior_get (memcached_st *ptr,                           memcached_behavior flag);

Следующая таблица описывает libmemcached флаги поведения.

Поведение Описание
MEMCACHED_BEHAVIOR_NO_BLOCK Вызванный libmemcached использовать асинхронный ввод-вывод.
MEMCACHED_BEHAVIOR_TCP_NODELAY Включает без задержек сетевых сокетов.
MEMCACHED_BEHAVIOR_HASH Без значения, устанавливает алгоритм хеширования значения по умолчанию для ключей, чтобы использовать MD5. Другие допустимые значения включают MEMCACHED_HASH_DEFAULT, MEMCACHED_HASH_MD5, MEMCACHED_HASH_CRC, MEMCACHED_HASH_FNV1_64, MEMCACHED_HASH_FNV1A_64, MEMCACHED_HASH_FNV1_32, и MEMCACHED_HASH_FNV1A_32.
MEMCACHED_BEHAVIOR_DISTRIBUTION Изменяет метод выбора сервера, используемого, чтобы сохранить данное значение. Метод значения по умолчанию MEMCACHED_DISTRIBUTION_MODULA. Можно включить непротиворечивому хешированию, устанавливая MEMCACHED_DISTRIBUTION_CONSISTENT. MEMCACHED_DISTRIBUTION_CONSISTENT псевдоним для значения MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA.
MEMCACHED_BEHAVIOR_CACHE_LOOKUPS Кэшируйте поиски, сделанные к службе DNS. Это может улучшить производительность, если Вы используете имена вместо IP-адресов для отдельных узлов.
MEMCACHED_BEHAVIOR_SUPPORT_CAS Операции CAS поддержки. По умолчанию это отключается, потому что это налагает потерю производительности.
MEMCACHED_BEHAVIOR_KETAMA Устанавливает распределение значения по умолчанию в MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA и хеш к MEMCACHED_HASH_MD5.
MEMCACHED_BEHAVIOR_POLL_TIMEOUT Измените значение тайм-аута, используемое poll(). Предоставление a signed int указатель для значения тайм-аута.
MEMCACHED_BEHAVIOR_BUFFER_REQUESTS Буферы IO запрашивают вместо них отправляемый. Получить работа, или закрытие соединения заставляет данные быть сброшенными.
MEMCACHED_BEHAVIOR_VERIFY_KEY Силы libmemcached проверять, что указанный ключ допустим.
MEMCACHED_BEHAVIOR_SORT_HOSTS Если установлено, узлы, добавленные к списку сконфигурированных узлов к a memcached_st структура помещается в список узла в сортированном порядке. Это повреждает непротиворечивое хеширование, если то поведение было включено.
MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT В неблокировании режима это изменяет значение тайм-аута во время socketconnection.

15.6.3.3.6. Утилиты Командной строки libmemcached

В дополнение к основному интерфейсу библиотеки C, libmemcached также включает много утилит командной строки, которые могут быть полезными, работая с и отлаживая memcached приложения.

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

Основные инструменты:

  • memcat: Выведите на экран значение для каждого ID, данного на командной строке:

    shell> memcat --servers=localhost hwkeyHello world
  • memcp: Скопируйте содержание файла в кэш, используя имя файла в качестве ключа:

    shell> echo "Hello World" > hwkeyshell> memcp --servers=localhost hwkeyshell> memcat --servers=localhost hwkeyHello world
  • memrm: Удалите элемент из кэша:

    shell> memcat --servers=localhost hwkeyHello worldshell> memrm --servers=localhost hwkeyshell> memcat --servers=localhost hwkey
  • memslap: Протестируйте загрузку на одном или более memcached серверах, моделирование получают/устанавливают и многократные клиентские операции. Например, можно моделировать загрузку 100 клиентов, выполняющих, получают операции:

    shell> memslap --servers=localhost --concurrency=100 --flush --test=getmemslap --servers=localhost --concurrency=100 --flush --test=get	Threads connecting to servers 100	Took 13.571 seconds to read data
  • memflush: Сброс (пустой) содержание memcached кэша.

    shell> memflush --servers=localhost