Класс Client

Всё взаимодействие с сервисом Memcache выполняется через экземпляр класса Client.

Класс Client реализован в модуле google.appengine.api.memcache.

Введение

Разработчик может производить все операции с кэшем через объект интерфейса сервиса Memcache.

Для сохранения совместимости кода существующих приложений, работающих с популярной библиотекой memcache, некоторые методы и параметры этого интерфейса намеренно игнорируются. К примеру, Google App Engine будет самостоятельно производить прозрачное для приложения сегментирование данных (sharding), но ее интерфейс также поддерживает задание в качестве параметра key кортежа вида (значение_хэша, строка). В традиционной библиотеке параметр значение_хэша используется механизмом сегментирования данных, поэтому App Engine будет игнорировать его. Для дополнительной информации смотрите раздел Совместимость с Memcached.

Конструктор

class Client()

Клиентский интерфейс, взаимодействующий с сервисом Memcache.

Методы экземпляра

Экземпляр класса Client имеет следующие методы:

set(key, value, time=0, min_compress_len=0)

Установка нового значения для указанного ключа независимо от его старого содержимого.

Параметры:

key
Указанный ключ, которому необходимо присвоить значение. Им может быть строка или кортеж вида (значение_хэша, строка), где значение_хэша, которое обычно используется для сегментирования данных (sharding), в нашем случае игнорируется, так как Google App Engine проводит сегментирование прозрачно от приложения.
value
Требуемое к установке значение.
time
Опциональный параметр time, в котором можно указать время жизни объекта либо в относительном формате в целых секундах от текущего времени, либо как абсолютное в формате Unix. По умолчанию объекты имеют неограниченный срок жизни, поэтому для освобождения памяти некоторые из них могут быть автоматически уничтожены в тот момент, когда она заканчивается. Если указано дробное значение в секундах, оно будет округлено до ближайшего целого.
min_compress_len
Игнорируется для совместимости.
Возвращает значение True если значение успешно установлено, False - в случае ошибки.
set_multi(mapping, time=0, key_prefix='', min_compress_len=0)

Множественная установка значений ключам. Используется для уменьшения влияния сетевых задержек на производительность операций с кэшем.

Параметры:

mapping
Словарь ключей и их значений.
time
Опциональный параметр time, в котором можно указать время жизни объекта либо в относительном формате в целых секундах от текущего времени, либо как абсолютное в формате Unix. По умолчанию объекты имеют неограниченный срок жизни, поэтому для освобождения памяти некоторые из них могут быть автоматически уничтожены в тот момент, когда она заканчивается. Если указано дробное значение в секундах, оно будет округлено до ближайшего целого.
key_prefix
Префикс, добавляемый к названию всех ключей.
min_compress_len
Игнорируется для совместимости.
Возвращает значение списка, содержащего название ключей, которые НЕ БЫЛИ установлены. Если операция целиком выполнена успешно, список будет пуст.
get(key)

Получение значения указанного ключа из оперативного кэша.

Параметры:

key
Ключ, значение которого требуется найти в кэше. Им может быть строка или кортеж вида (значение_хэша, строка), где значение_хэша, которое обычно используется для сегментирования данных (sharding), в нашем случае игнорируется, так как Google App Engine проводит сегментирование прозрачно от приложения.
В случае, если ключ был найден в кэше, возвращает его значение, в противном случае None.
get_multi(keys, key_prefix='')

Получение значений нескольких ключей из оперативного кэша. Является рекомендуемым методом для проведения потоковой загрузки данных из оперативного кэша.

Параметры:

keys
Список ключей, значения которых необходимо получить. В списке могут быть указаны строки или кортежи вида (значение_хэша, строка), где значение_хэша, которое обычно используется для сегментирования данных (sharding), в нашем случае игнорируется, так как Google App Engine проводит сегментирование прозрачно от приложения.
key_prefix
Префикс, добавляемый к названию всех ключей, передаваемых сервису; не включается в результирующий набор.
Возвращаемое значение является словарем ключей и их значений, которые присутствуют в кэше. Даже если был задан параметр key_prefix, он не будет добавлен к результатам, возвращаемым функцией в словаре ключей и их значений.
delete(key, seconds=0)

Удаление ключа из оперативного кэша.

Параметры:

key
Ключ, который необходимо удалить. В списке могут быть указаны строки или кортежи вида (значение_хэша, строка), где значение_хэша, которое обычно используется для сегментирования данных (sharding), в нашем случае игнорируется, так как Google App Engine проводит сегментирование прозрачно от приложения.
seconds
Опциональный параметр, содержащий количество секунд, и указывающий, какая будет произведена задержка перед тем, как можно будет добавить новый объект с тем же ключом при помощи функции 'add'. Значение может быть смещением относительно текущего времени (до 1 месяца) или абсолютным временем в формате Unix. По умолчанию значение - 0, что означает что после удаления новые объекты с таким же ключом могут быть добавлены сразу. Работа операции 'set' не будет зависеть от наличия или отсутствия этого параметра. Если указано дробное значение в секундах, оно будет округлено до ближайшего целого.
Возвращает значения: 0 (DELETE_NETWORK_FAILURE) при возникновении сетевой ошибки, 1 (DELETE_ITEM_MISSING) - если приложение пыталось удалить несуществующий объект и 2 (DELETE_SUCCESSFUL) - если объект был успешно удален. Этот результат можно использовать для логической проверки, так как его значение "ложь" будет всегда соответствовать сетевым проблемам.
delete_multi(keys, seconds=0, key_prefix='')

Множественное удаление ключей из кэша.

Параметры:

keys
Список ключей, которые требуется удалить. В списке могут быть указаны строки или кортежи вида (значение_хэша, строка), где значение_хэша, которое обычно используется для сегментирования данных (sharding), в нашем случае игнорируется, так как Google App Engine проводит сегментирование прозрачно от приложения.
seconds
Опциональный параметр, содержащий количество секунд, и указывающий, какая будет произведена задержка перед тем, как можно будет добавить новый объект с тем же ключом при помощи функции 'add'. Значение может быть смещением относительно текущего времени (до 1 месяца) или абсолютным временем в формате Unix. По умолчанию значение - 0, что означает что после удаления новые объекты с таким же ключом могут быть добавлены сразу. Работа операции 'set' не будет зависеть от наличия или отсутствия этого параметра. Если указано дробное значение в секундах, оно будет округлено до ближайшего целого.
key_prefix
Префикс, добавляемый к названию всех ключей, передаваемых сервису. Смотрите описание функций get_multi() и set_multi()
Возвращает значение True, если все операции были проведены успешно. False - если при удалении одного или нескольких значений произошла ошибка.
add(key, value, time=0, min_compress_len=0)

Устанавливает значение ключу, но только в том случае, если объект уже присутствует в кэше.

Параметры:

key
Указанный ключ, которому необходимо присвоить значение. Им может быть строка или кортеж вида (значение_хэша, строка), где значение_хэша, которое обычно используется для сегментирования данных (sharding), в нашем случае игнорируется, так как Google App Engine проводит сегментирование прозрачно от приложения.
value
Требуемое к установке значение.
time
Опциональный параметр time, в котором можно указать время жизни объекта либо в относительном формате в целых секундах от текущего времени, либо как абсолютное в формате Unix. По умолчанию объекты имеют неограниченный срок жизни, поэтому для освобождения памяти некоторые из них могут быть автоматически уничтожены в тот момент, когда она заканчивается. Если указано дробное значение в секундах, оно будет округлено до ближайшего целого.
min_compress_len
Игнорируется для совместимости.
Возвращает True, если значение успешно добавлено и False - в случае ошибки.
replace(key, value, time=0, min_compress_len=0)

Заменяет значение указанного ключа, кроме тех случаев, когда он не содержится в кэше.

Параметры:

key
Указанный ключ, которому необходимо присвоить значение. Им может быть строка или кортеж вида (значение_хэша, строка), где значение_хэша, которое обычно используется для сегментирования данных (sharding), в нашем случае игнорируется, так как Google App Engine проводит сегментирование прозрачно от приложения.
value
Требуемое к установке значение.
time
Опциональный параметр time, в котором можно указать время жизни объекта либо в относительном формате в целых секундах от текущего времени, либо как абсолютное в формате Unix. По умолчанию объекты имеют неограниченный срок жизни, поэтому для освобождения памяти некоторые из них могут быть автоматически уничтожены в тот момент, когда она заканчивается. Если указано дробное значение в секундах, оно будет округлено до ближайшего целого.
min_compress_len
Игнорируется для совместимости.
Возвращает значение True, если замена была проведена успешно. False - если произошла ошибка или объект отсутствует в кэше.
incr(key, delta=1)

Производит атомарную операцию инкрементирования значения ключа. Внутреннее представление является беззнаковым 64-битным целым числом. Memcache не проверяет переполнение этого значения. Если получившееся значение будет слишком большое, произойдет его обнуление.

Ключ уже должен присутствовать в кэше. Для присвоения первого значения, используйте операцию set() со строковым целым значением. После выполнения операции инкрементирования/декрементирования и запроса значения функцией get(), оно также будет иметь строковое представление.

Параметры:

key
Ключ, который необходимо проинкрементировать. Им может быть строка или кортеж вида (значение_хэша, строка), где значение_хэша, которое обычно используется для сегментирования данных (sharding), в нашем случае игнорируется, так как Google App Engine проводит сегментирование прозрачно от приложения.
delta
Целое положительное значение (типа int или long), которое прибавляется к значению ключа, по-умолчанию 1.
Возвращает новое числовое значение или None, если ключ не присутствовал в кэше или по другой причине.
decr(key, delta=1)

Производит атомарную операцию декрементирования значения ключа. Внутреннее представление является беззнаковым 64-битным целым числом. Memcache не проверяет переполнение этого значения. Если получившееся значение будет слишком большое, произойдет его обнуление.

Ключ уже должен присутствовать в кэше. Для присвоения первого значения, используйте операцию set() со строковым целым значением. После выполнения операции инкрементирования/декрементирования и запроса значения функцией get(), оно также будет иметь строковое представление.

Параметры:

key
Ключ, который необходимо декрементировать. Им может быть строка или кортеж вида (значение_хэша, строка), где значение_хэша, которое обычно используется для сегментирования данных (sharding), в нашем случае игнорируется, так как Google App Engine проводит сегментирование прозрачно от приложения.
delta
Целое положительное значение (типа int или long), которое отнимается от значения ключа, по-умолчанию 1.
Возвращает новое числовое значение или None, если ключ не присутствовал в кэше или операция завершилась неудачно по другой причине.
flush_all()

Производит полную очистку кэша.

Возвращает True при успешном выполнении, False - если сервер вернул ошибку.
get_stats()

Получает статистику по использованию сервиса memcache данным приложением. Статистика может обнуляться в любой момент времени при выполнении плановых операций обслуживания системы. Предоставляется вся доступная информация на момент вызова функции.

Возвращает словарь статистических параметров и их ассоциированных значений. Они могут быть следующими:
hits: Количество извлеченных из кэша объектов, которые в нем находились.
misses: Количество запросов, которые не могли быть выполнены при причине отсутствия значений в кэше.
byte_hits: Общее число байт, переданных при получении запросов. При переполнении сбрасывается в ноль.
items: Количество уникальных пар ключ/значение, находящихся в кэше.
bytes: Общий размер всех объектов в кэше.
oldest_item_age: Определяет число секунд, которые прошли с момента доступа к самому старому объекту. Этот параметр указывает, сколько времени может находиться объект в кэше без проведения обращений к нему. Он _не определяет_ сколько времени прошло с того момента, как был создан объект.

Совместимость с Memcached

Класс Client включает в себя некоторые методы и параметры функций, сохраненные для совместимости с оригинальным интерфейсом Memcached. Так как некоторые из этих параметров не могут быть использованы с сервисом Memcache платформы App Engine, задание им любых значений не произведет никакого эффекта на поведение приложения.

Также следующие методы целиком являются заглушками:

  • disconnect_all()
  • set_servers(...)