evennia.utils.idmapper package

The idmapper holds the main database caching mechanism.

Submodules

evennia.utils.idmapper.manager module

IDmapper extension to the default manager.

class evennia.utils.idmapper.manager.SharedMemoryManager

Bases: django.db.models.manager.Manager

get(*args, **kwargs)

Data entity lookup.

evennia.utils.idmapper.models module

Django ID mapper

Modified for Evennia by making sure that no model references leave caching unexpectedly (no use of WeakRefs).

Also adds cache_size() for monitoring the size of the cache.

class evennia.utils.idmapper.models.SharedMemoryModel(*args, **kwargs)

Bases: django.db.models.base.Model

Base class for idmapped objects. Inherit from this.

class Meta

Bases: object

abstract = False

classmethod _flush_cached_by_key(key, force=True)

Remove the cached reference.

classmethod _get_cache_key(args, kwargs)

This method is used by the caching subsystem to infer the PK value from the constructor arguments. It is used to decide if an instance has to be built or is already in the cache.

_is_deleted = False

_meta = <Options for SharedMemoryModel>

at_idmapper_flush()

This is called when the idmapper cache is flushed and allows customized actions when this happens.

Returns

If True, flush this object as normal. If

False, don’t flush and expect this object to handle the flushing on its own.

Return type

do_flush (bool)

classmethod cache_instance(instance, new=False)

Method to store an instance in the cache.

Parameters

• instance (Class instance) – the instance to cache.

• new (bool, optional) – this is the first time this instance is cached (i.e. this is not an update operation like after a db save).

delete(*args, **kwargs)

Delete the object, clearing cache.

classmethod flush_cached_instance(instance, force=True)

Method to flush an instance from the cache. The instance will always be flushed from the cache, since this is most likely called from delete(), and we want to make sure we don’t cache dead objects.

flush_from_cache(force=False)

Flush this instance from the instance cache. Use force to override the result of at_idmapper_flush() for the object.

classmethod flush_instance_cache(force=False)

This will clean safe objects from the cache. Use force keyword to remove all objects, safe or not.

classmethod get_all_cached_instances()

Return the objects so far cached by idmapper for this class.

classmethod get_cached_instance(id)

Method to retrieve a cached instance by pk value. Returns None when not found (which will always be the case when caching is disabled for this class). Please note that the lookup will be done even when instance caching is disabled.

objects

path = 'evennia.utils.idmapper.models.SharedMemoryModel'

save(*args, **kwargs)

Central database save operation.

Notes

Arguments as per Django documentation. Calls self.at_<fieldname>_postsave(new) (this is a wrapper set by oobhandler: self._oob_at_<fieldname>_postsave())

typename = 'SharedMemoryModelBase'

class evennia.utils.idmapper.models.SharedMemoryModelBase

Bases: django.db.models.base.ModelBase

_prepare()

Prepare the cache, making sure that proxies of the same db base share the same cache.

class evennia.utils.idmapper.models.WeakSharedMemoryModel(*args, **kwargs)

Bases: evennia.utils.idmapper.models.SharedMemoryModel

Uses a WeakValue dictionary for caching instead of a regular one

class Meta

Bases: object

abstract = False

_is_deleted = False

_meta = <Options for WeakSharedMemoryModel>

path = 'evennia.utils.idmapper.models.WeakSharedMemoryModel'

typename = 'WeakSharedMemoryModelBase'

class evennia.utils.idmapper.models.WeakSharedMemoryModelBase

Bases: evennia.utils.idmapper.models.SharedMemoryModelBase

Uses a WeakValue dictionary for caching instead of a regular one.

_prepare()

Prepare the cache, making sure that proxies of the same db base share the same cache.

evennia.utils.idmapper.models._DA()

Implement delattr(self, name).

evennia.utils.idmapper.models._GA()

Return getattr(self, name).

evennia.utils.idmapper.models._SA()

Implement setattr(self, name, value).

evennia.utils.idmapper.models.cache_size(mb=True)

Calculate statistics about the cache.

Note: we cannot get reliable memory statistics from the cache - whereas we could do getsizof each object in cache, the result is highly imprecise and for a large number of objects the result is many times larger than the actual memory usage of the entire server; Python is clearly reusing memory behind the scenes that we cannot catch in an easy way here. Ideas are appreciated. /Griatch

Returns

total_num, …}

Return type

total_num, {objclass

evennia.utils.idmapper.models.conditional_flush(max_rmem, force=False)

Flush the cache if the estimated memory usage exceeds max_rmem.

The flusher has a timeout to avoid flushing over and over in particular situations (this means that for some setups the memory usage will exceed the requirement and a server with more memory is probably required for the given game).

Parameters

• max_rmem (int) – memory-usage estimation-treshold after which cache is flushed.

• force (bool, optional) – forces a flush, regardless of timeout. Defaults to False.

evennia.utils.idmapper.models.flush_cache(**kwargs)

Flush idmapper cache. When doing so the cache will fire the at_idmapper_flush hook to allow the object to optionally handle its own flushing.

Uses a signal so we make sure to catch cascades.

evennia.utils.idmapper.models.flush_cached_instance(sender, instance, **kwargs)

Flush the idmapper cache only for a given instance.

evennia.utils.idmapper.models.update_cached_instance(sender, instance, **kwargs)

Re-cache the given instance in the idmapper cache.

evennia.utils.idmapper.tests module

class evennia.utils.idmapper.tests.Article(id, name, category, category2)

Bases: evennia.utils.idmapper.models.SharedMemoryModel

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

_is_deleted = False

_meta = <Options for Article>

category

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

category2

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

category2_id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

category_id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

name

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

path = 'evennia.utils.idmapper.tests.Article'

typename = 'SharedMemoryModelBase'

class evennia.utils.idmapper.tests.Category(id, name)

Bases: evennia.utils.idmapper.models.SharedMemoryModel

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

_is_deleted = False

_meta = <Options for Category>

article_set

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

name

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

path = 'evennia.utils.idmapper.tests.Category'

regulararticle_set

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

typename = 'SharedMemoryModelBase'

class evennia.utils.idmapper.tests.RegularArticle(id, name, category, category2)

Bases: django.db.models.base.Model

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

_meta = <Options for RegularArticle>

category

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

category2

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

category2_id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

category_id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

name

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>

class evennia.utils.idmapper.tests.RegularCategory(id, name)

Bases: django.db.models.base.Model

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

_meta = <Options for RegularCategory>

article_set

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

name

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>

regulararticle_set

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

class evennia.utils.idmapper.tests.SharedMemorysTest(methodName='runTest')

Bases: django.test.testcases.TestCase

setUp()

Hook method for setting up the test fixture before exercising it.

testMixedReferences()

testObjectDeletion()

testRegularReferences()

testSharedMemoryReferences()