Global Cache

GlobalCache interface and its implementations.

class google.cloud.ndb.global_cache.GlobalCache

Bases: object

Abstract base class for a global entity cache.

A global entity cache is shared across contexts, sessions, and possibly even servers. A concrete implementation is available which uses Redis.

Essentially, this class models a simple key/value store where keys and values are arbitrary bytes instances. “Compare and swap”, aka “optimistic transactions” should also be supported.

Concrete implementations can either by synchronous or asynchronous. Asynchronous implementations should return Future instances whose eventual results match the return value described for each method. Because coordinating with the single threaded event model used by NDB can be tricky with remote services, it’s not recommended that casual users write asynchronous implementations, as some specialized knowledge is required.

strict_read

If False, transient errors that occur as part of a entity lookup operation will be logged as warnings but not raised to the application layer. If True, in the event of transient errors, cache operations will be retried a number of times before eventually raising the transient error to the application layer, if it does not resolve after retrying. Setting this to True will cause NDB operations to take longer to complete if there are transient errors in the cache layer.

Type

bool

strict_write

If False, transient errors that occur as part of a put or delete operation will be logged as warnings, but not raised to the application layer. If True, in the event of transient errors, cache operations will be retried a number of times before eventually raising the transient error to the application layer if it does not resolve after retrying. Setting this to False somewhat increases the risk that other clients might read stale data from the cache. Setting this to True will cause NDB operations to take longer to complete if there are transient errors in the cache layer.

Type

bool

abstract clear()

Clear all keys from global cache.

Will be called if there previously was a connection error, to prevent clients from reading potentially stale data from the cache.

abstract compare_and_swap(items, expires=None)

Like set() but using an optimistic transaction.

Only keys whose values haven’t changed since a preceding call to watch() will be changed.

Parameters

• items (Dict[bytes, Union[bytes, None]]) – Mapping of keys to serialized entities.

• expires (Optional[float]) – Number of seconds until value expires.

Returns

A mapping of key to result. A key will have a result of

True if it was changed successfully.

Return type

Dict[bytes, bool]

abstract delete(keys)

Remove entities from the cache.

Parameters

keys (List[bytes]) – The keys to remove.

abstract get(keys)

Retrieve entities from the cache.

Parameters

keys (List[bytes]) – The keys to get.

Returns

Serialized entities, or None,

for each key.

Return type

List[Union[bytes, None]]]

abstract set(items, expires=None)

Store entities in the cache.

Parameters

• items (Dict[bytes, Union[bytes, None]]) – Mapping of keys to serialized entities.

• expires (Optional[float]) – Number of seconds until value expires.

Returns

May return None, or a dict mapping

keys to arbitrary results. If the result for a key is an instance of Exception, the result will be raised as an exception in that key’s future.

Return type

Optional[Dict[bytes, Any]]

abstract set_if_not_exists(items, expires=None)

Stores entities in the cache if and only if keys are not already set.

Parameters

• items (Dict[bytes, Union[bytes, None]]) – Mapping of keys to serialized entities.

• expires (Optional[float]) – Number of seconds until value expires.

Returns

A dict mapping to boolean value that will be

True if that key was set with a new value, and False otherwise.

Return type

Dict[bytes, bool]

transient_errors = ()

Exceptions that should be treated as transient errors in non-strict modes.

Instances of these exceptions, if raised, will be logged as warnings but will not be raised to the application layer, depending on the values of the strict_read and strict_write attributes of the instance.

This should be overridden by subclasses.

abstract unwatch(keys)

End an optimistic transaction for the given keys.

Indicates that value for the key wasn’t found in the database, so there will not be a future call to compare_and_swap(), and we no longer need to watch this key.

Parameters

keys (List[bytes]) – The keys to watch.

abstract watch(items)

Begin an optimistic transaction for the given items.

A future call to compare_and_swap() will only set values for keys whose values haven’t changed since the call to this method. Values are used to check that the watched value matches the expected value for a given key.

Parameters

items (Dict[bytes, bytes]) – The items to watch.

class google.cloud.ndb.global_cache.MemcacheCache(client, strict_read=False, strict_write=True)

Bases: google.cloud.ndb.global_cache.GlobalCache

Memcache implementation of the GlobalCache.

This is a synchronous implementation. The idea is that calls to Memcache should be fast enough not to warrant the added complexity of an asynchronous implementation.

Parameters

• client (pymemcache.Client) – Instance of Memcache client to use.

• strict_read (bool) – If False, connection errors during read operations will be logged with a warning and treated as cache misses, but will not raise an exception in the application, with connection errors during reads being treated as cache misses. If True, in the event of connection errors, cache operations will be retried a number of times before eventually raising the connection error to the application layer, if it does not resolve after retrying. Setting this to True will cause NDB operations to take longer to complete if there are transient errors in the cache layer. Default: False.

• strict_write (bool) – If False, connection errors during write operations will be logged with a warning, but will not raise an exception in the application. If True, connection errors during write will be raised as exceptions in the application. Because write operations involve cache invalidation, setting this to False may allow other clients to retrieve stale data from the cache. If True, in the event of connection errors, cache operations will be retried a number of times before eventually raising the connection error to the application layer, if it does not resolve after retrying. Setting this to True will cause NDB operations to take longer to complete if there are transient errors in the cache layer. Default: True.

exception KeyNotSet(key)

Bases: Exception

clear()

Implements GlobalCache.clear().

compare_and_swap(items, expires=None)

Implements GlobalCache.compare_and_swap().

delete(keys)

Implements GlobalCache.delete().

classmethod from_environment(max_pool_size=4, strict_read=False, strict_write=True)

Generate a pymemcache.Client from an environment variable.

This class method looks for the MEMCACHED_HOSTS environment variable and, if it is set, parses the value as a space delimited list of hostnames, optionally with ports. For example:

“localhost” “localhost:11211” “1.1.1.1:11211 2.2.2.2:11211 3.3.3.3:11211”

Parameters

• max_pool_size (int) – Size of connection pool to be used by client. If set to 0 or 1, connection pooling will not be used. Default: 4

• strict_read (bool) – If False, connection errors during read operations will be logged with a warning and treated as cache misses, but will not raise an exception in the application, with connection errors during reads being treated as cache misses. If True, in the event of connection errors, cache operations will be retried a number of times before eventually raising the connection error to the application layer, if it does not resolve after retrying. Setting this to True will cause NDB operations to take longer to complete if there are transient errors in the cache layer. Default: False.

• strict_write (bool) – If False, connection errors during write operations will be logged with a warning, but will not raise an exception in the application. If True, connection errors during write will be raised as exceptions in the application. Because write operations involve cache invalidation, setting this to False may allow other clients to retrieve stale data from the cache. If True, in the event of connection errors, cache operations will be retried a number of times before eventually raising the connection error to the application layer, if it does not resolve after retrying. Setting this to True will cause NDB operations to take longer to complete if there are transient errors in the cache layer. Default: True.

Returns

A MemcacheCache instance or

None, if MEMCACHED_HOSTS is not set in the environment.

Return type

Optional[MemcacheCache]

get(keys)

Implements GlobalCache.get().

set(items, expires=None)

Implements GlobalCache.set().

set_if_not_exists(items, expires=None)

Implements GlobalCache.set_if_not_exists().

unwatch(keys)

Implements GlobalCache.unwatch().

watch(items)

Implements GlobalCache.watch().

class google.cloud.ndb.global_cache.RedisCache(redis, strict_read=False, strict_write=True)

Bases: google.cloud.ndb.global_cache.GlobalCache

Redis implementation of the GlobalCache.

This is a synchronous implementation. The idea is that calls to Redis should be fast enough not to warrant the added complexity of an asynchronous implementation.

Parameters

• redis (redis.Redis) – Instance of Redis client to use.

• strict_read (bool) – If False, connection errors during read operations will be logged with a warning and treated as cache misses, but will not raise an exception in the application, with connection errors during reads being treated as cache misses. If True, in the event of connection errors, cache operations will be retried a number of times before eventually raising the connection error to the application layer, if it does not resolve after retrying. Setting this to True will cause NDB operations to take longer to complete if there are transient errors in the cache layer. Default: False.

• strict_write (bool) – If False, connection errors during write operations will be logged with a warning, but will not raise an exception in the application. If True, connection errors during write will be raised as exceptions in the application. Because write operations involve cache invalidation, setting this to False may allow other clients to retrieve stale data from the cache. If True, in the event of connection errors, cache operations will be retried a number of times before eventually raising the connection error to the application layer, if it does not resolve after retrying. Setting this to True will cause NDB operations to take longer to complete if there are transient errors in the cache layer. Default: True.

clear()

Implements GlobalCache.clear().

compare_and_swap(items, expires=None)

Implements GlobalCache.compare_and_swap().

delete(keys)

Implements GlobalCache.delete().

classmethod from_environment(strict_read=False, strict_write=True)

Generate a class:RedisCache from an environment variable.

This class method looks for the REDIS_CACHE_URL environment variable and, if it is set, passes its value to Redis.from_url to construct a Redis instance which is then used to instantiate a RedisCache instance.

Parameters

• strict_read (bool) – If False, connection errors during read operations will be logged with a warning and treated as cache misses, but will not raise an exception in the application, with connection errors during reads being treated as cache misses. If True, in the event of connection errors, cache operations will be retried a number of times before eventually raising the connection error to the application layer, if it does not resolve after retrying. Setting this to True will cause NDB operations to take longer to complete if there are transient errors in the cache layer. Default: False.

• strict_write (bool) – If False, connection errors during write operations will be logged with a warning, but will not raise an exception in the application. If True, connection errors during write will be raised as exceptions in the application. Because write operations involve cache invalidation, setting this to False may allow other clients to retrieve stale data from the cache. If True, in the event of connection errors, cache operations will be retried a number of times before eventually raising the connection error to the application layer, if it does not resolve after retrying. Setting this to True will cause NDB operations to take longer to complete if there are transient errors in the cache layer. Default: True.

Returns

A RedisCache instance or

None, if REDIS_CACHE_URL is not set in the environment.

Return type

Optional[RedisCache]

get(keys)

Implements GlobalCache.get().

set(items, expires=None)

Implements GlobalCache.set().

set_if_not_exists(items, expires=None)

Implements GlobalCache.set_if_not_exists().

unwatch(keys)

Implements GlobalCache.watch().

watch(items)

Implements GlobalCache.watch().