oslo_cache.backends package¶
Submodules¶
oslo_cache.backends.dictionary module¶
dogpile.cache backend that uses dictionary for storage
-
class
oslo_cache.backends.dictionary.
DictCacheBackend
(arguments)¶ Bases:
dogpile.cache.api.CacheBackend
A DictCacheBackend based on dictionary.
Arguments accepted in the arguments dictionary:
- Parameters
expiration_time (real) – interval in seconds to indicate maximum time-to-live value for each key in DictCacheBackend. Default expiration_time value is 0, that means that all keys have infinite time-to-live value.
-
delete
(key)¶ Deletes the value associated with the key if it exists.
- Parameters
key – dictionary key
-
delete_multi
(keys)¶ Deletes the value associated with each key in list if it exists.
- Parameters
keys – list of dictionary keys
-
get
(key)¶ Retrieves the value for a key.
- Parameters
key – dictionary key
- Returns
value for a key or
oslo_cache.core.NO_VALUE
for nonexistent or expired keys.
-
get_multi
(keys)¶ Retrieves the value for a list of keys.
-
set
(key, value)¶ Sets the value for a key.
Expunges expired keys during each set.
- Parameters
key – dictionary key
value – value associated with the key
-
set_multi
(mapping)¶ Set multiple values in the cache. Expunges expired keys during each set.
- Parameters
mapping – dictionary with key/value pairs
oslo_cache.backends.etcd3gw module¶
dogpile.cache backend that uses etcd 3.x for storage
-
class
oslo_cache.backends.etcd3gw.
Etcd3gwCacheBackend
(arguments)¶ Bases:
dogpile.cache.api.CacheBackend
-
DEFAULT_HOST
= 'localhost'¶ Default hostname used when none is provided.
-
DEFAULT_PORT
= 2379¶ Default port used if none provided (4001 or 2379 are the common ones).
-
DEFAULT_TIMEOUT
= 30¶ Default socket/lock/member/leader timeout used when none is provided.
-
delete
(key)¶ Delete a value from the cache.
- Parameters
key – String key that was passed to the
CacheRegion.delete()
method, which will also be processed by the “key mangling” function if one was present.
The behavior here should be idempotent, that is, can be called any number of times regardless of whether or not the key exists.
-
delete_multi
(keys)¶ Delete multiple values from the cache.
- Parameters
keys – sequence of string keys that was passed to the
CacheRegion.delete_multi()
method, which will also be processed by the “key mangling” function if one was present.
The behavior here should be idempotent, that is, can be called any number of times regardless of whether or not the key exists.
New in version 0.5.0.
-
get
(key)¶ Retrieve an optionally serialized value from the cache.
- Parameters
key – String key that was passed to the
CacheRegion.get()
method, which will also be processed by the “key mangling” function if one was present.- Returns
the Python object that corresponds to what was established via the
CacheBackend.set()
method, or theNO_VALUE
constant if not present.
If a serializer is in use, this method will only be called if the
CacheBackend.get_serialized()
method is not overridden.
-
get_multi
(keys)¶ Retrieves the value for a list of keys.
-
set
(key, value)¶ Set an optionally serialized value in the cache.
- Parameters
key – String key that was passed to the
CacheRegion.set()
method, which will also be processed by the “key mangling” function if one was present.value – The optionally serialized
CachedValue
object. May be an instance ofCachedValue
or a bytes object depending on if a serializer is in use with the region and if theCacheBackend.set_serialized()
method is not overridden.
See also
CacheBackend.set_serialized()
-
set_multi
(mapping)¶ Set multiple values in the cache.
- Parameters
mapping – a dict in which the key will be whatever was passed to the
CacheRegion.set_multi()
method, processed by the “key mangling” function, if any.
When implementing a new
CacheBackend
or cutomizing viaProxyBackend
, be aware that when this method is invoked byRegion.get_or_create_multi()
, themapping
values are the same ones returned to the upstream caller. If the subclass alters the values in any way, it must not do so ‘in-place’ on themapping
dict – that will have the undesirable effect of modifying the returned values as well.If a serializer is in use, this method will only be called if the
CacheBackend.set_serialized_multi()
method is not overridden.New in version 0.5.0.
-
oslo_cache.backends.memcache_pool module¶
oslo_cache.backends.mongo module¶
-
class
oslo_cache.backends.mongo.
MongoCacheBackend
(arguments)¶ Bases:
dogpile.cache.api.CacheBackend
A MongoDB based caching backend implementing dogpile backend APIs.
Arguments accepted in the arguments dictionary:
- Parameters
db_hosts – string (required), hostname or IP address of the MongoDB server instance. This can be a single MongoDB connection URI, or a list of MongoDB connection URIs.
db_name – string (required), the name of the database to be used.
cache_collection – string (required), the name of collection to store cached data. Note: Different collection name can be provided if there is need to create separate container (i.e. collection) for cache data. So region configuration is done per collection.
Following are optional parameters for MongoDB backend configuration,
- Parameters
username – string, the name of the user to authenticate.
password – string, the password of the user to authenticate.
max_pool_size – integer, the maximum number of connections that the pool will open simultaneously. By default the pool size is 10.
w –
integer, write acknowledgement for MongoDB client
If not provided, then no default is set on MongoDB and then write acknowledgement behavior occurs as per MongoDB default. This parameter name is same as what is used in MongoDB docs. This value is specified at collection level so its applicable to cache_collection db write operations.
If this is a replica set, write operations will block until they have been replicated to the specified number or tagged set of servers. Setting w=0 disables write acknowledgement and all other write concern options.
read_preference – string, the read preference mode for MongoDB client Expected value is
primary
,primaryPreferred
,secondary
,secondaryPreferred
, ornearest
. This read_preference is specified at collection level so its applicable to cache_collection db read operations.use_replica – boolean, flag to indicate if replica client to be used. Default is False. replicaset_name value is required if True.
replicaset_name – string, name of replica set. Becomes required if use_replica is True
son_manipulator –
string, name of class with module name which implements MongoDB SONManipulator. Default manipulator used is
BaseTransform
.This manipulator is added per database. In multiple cache configurations, the manipulator name should be same if same database name
db_name
is used in those configurations.SONManipulator is used to manipulate custom data types as they are saved or retrieved from MongoDB. Custom impl is only needed if cached data is custom class and needs transformations when saving or reading from db. If dogpile cached value contains built-in data types, then BaseTransform class is sufficient as it already handles dogpile CachedValue class transformation.
mongo_ttl_seconds –
integer, interval in seconds to indicate maximum time-to-live value. If value is greater than 0, then its assumed that cache_collection needs to be TTL type (has index at ‘doc_date’ field). By default, the value is -1 and its disabled. Reference: <http://docs.mongodb.org/manual/tutorial/expire-data/>
Note
This parameter is different from Dogpile own expiration_time, which is the number of seconds after which Dogpile will consider the value to be expired. When Dogpile considers a value to be expired, it continues to use the value until generation of a new value is complete, when using CacheRegion.get_or_create(). Therefore, if you are setting mongo_ttl_seconds, you will want to make sure it is greater than expiration_time by at least enough seconds for new values to be generated, else the value would not be available during a regeneration, forcing all threads to wait for a regeneration each time a value expires.
ssl – boolean, If True, create the connection to the server using SSL. Default is False. Client SSL connection parameters depends on server side SSL setup. For further reference on SSL configuration: <http://docs.mongodb.org/manual/tutorial/configure-ssl/>
ssl_keyfile – string, the private keyfile used to identify the local connection against mongod. If included with the certfile then only the ssl_certfile is needed. Used only when ssl is True.
ssl_certfile – string, the certificate file used to identify the local connection against mongod. Used only when ssl is True.
ssl_ca_certs – string, the ca_certs file contains a set of concatenated ‘certification authority’ certificates, which are used to validate certificates passed from the other end of the connection. Used only when ssl is True.
ssl_cert_reqs – string, the parameter cert_reqs specifies whether a certificate is required from the other side of the connection, and whether it will be validated if provided. It must be one of the three values
ssl.CERT_NONE
(certificates ignored),ssl.CERT_OPTIONAL
(not required, but validated if provided), orssl.CERT_REQUIRED
(required and validated). If the value of this parameter is notssl.CERT_NONE
, then the ssl_ca_certs parameter must point to a file of CA certificates. Used only when ssl is True.
Rest of arguments are passed to mongo calls for read, write and remove. So related options can be specified to pass to these operations.
Further details of various supported arguments can be referred from <http://api.mongodb.org/python/current/api/pymongo/>
-
client
¶ Initializes MongoDB connection and collection defaults.
This initialization is done only once and performed as part of lazy inclusion of MongoDB dependency i.e. add imports only if related backend is used.
- Returns
MongoApi
instance
-
delete
(key)¶ Delete a value from the cache.
- Parameters
key – String key that was passed to the
CacheRegion.delete()
method, which will also be processed by the “key mangling” function if one was present.
The behavior here should be idempotent, that is, can be called any number of times regardless of whether or not the key exists.
-
delete_multi
(keys)¶ Delete multiple values from the cache.
- Parameters
keys – sequence of string keys that was passed to the
CacheRegion.delete_multi()
method, which will also be processed by the “key mangling” function if one was present.
The behavior here should be idempotent, that is, can be called any number of times regardless of whether or not the key exists.
New in version 0.5.0.
-
get
(key)¶ Retrieves the value for a key.
- Parameters
key – key to be retrieved.
- Returns
value for a key or
oslo_cache.core.NO_VALUE
for nonexistent or expired keys.
-
get_multi
(keys)¶ Return multiple values from the cache, based on the given keys.
- Parameters
keys – sequence of keys to be retrieved.
- Returns
returns values (or
oslo_cache.core.NO_VALUE
) as a list matching the keys given.
-
set
(key, value)¶ Set an optionally serialized value in the cache.
- Parameters
key – String key that was passed to the
CacheRegion.set()
method, which will also be processed by the “key mangling” function if one was present.value – The optionally serialized
CachedValue
object. May be an instance ofCachedValue
or a bytes object depending on if a serializer is in use with the region and if theCacheBackend.set_serialized()
method is not overridden.
See also
CacheBackend.set_serialized()
-
set_multi
(mapping)¶ Set multiple values in the cache.
- Parameters
mapping – a dict in which the key will be whatever was passed to the
CacheRegion.set_multi()
method, processed by the “key mangling” function, if any.
When implementing a new
CacheBackend
or cutomizing viaProxyBackend
, be aware that when this method is invoked byRegion.get_or_create_multi()
, themapping
values are the same ones returned to the upstream caller. If the subclass alters the values in any way, it must not do so ‘in-place’ on themapping
dict – that will have the undesirable effect of modifying the returned values as well.If a serializer is in use, this method will only be called if the
CacheBackend.set_serialized_multi()
method is not overridden.New in version 0.5.0.