# HG changeset patch
# User Mads Kiilerich <madski@unity3d.com>
# Date 1364410550 -3600
# Node ID cf65b2c1b69d687ce08e45c7a2dbdaff5fae6de6
# Parent  05006e3e286b12ab598941737725413ea2395a5e
invalidation: some documentation and refactoring, second round

diff -r 05006e3e286b -r cf65b2c1b69d rhodecode/model/db.py
--- a/rhodecode/model/db.py	Thu Apr 04 15:55:53 2013 +0200
+++ b/rhodecode/model/db.py	Wed Mar 27 19:55:50 2013 +0100
@@ -1147,7 +1147,7 @@
 
     def set_invalidate(self):
         """
-        set a cache for invalidation for this instance
+        Mark caches of this repo as invalid.
         """
         CacheInvalidation.set_invalidate(repo_name=self.repo_name)
 
@@ -1636,14 +1636,15 @@
     cache_id = Column("cache_id", Integer(), nullable=False, unique=True, default=None, primary_key=True)
     # cache_key as created by _get_cache_key
     cache_key = Column("cache_key", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)
-    # cache_args is usually a repo_name, possibly with _README/_RSS/_ATOM suffix
+    # cache_args is a repo_name
     cache_args = Column("cache_args", String(255, convert_unicode=False, assert_unicode=None), nullable=True, unique=None, default=None)
-    # instance sets cache_active True when it is caching, other instances set cache_active to False to invalidate
+    # instance sets cache_active True when it is caching,
+    # other instances set cache_active to False to indicate that this cache is invalid
     cache_active = Column("cache_active", Boolean(), nullable=True, unique=None, default=False)
 
-    def __init__(self, cache_key, cache_args=''):
+    def __init__(self, cache_key, repo_name=''):
         self.cache_key = cache_key
-        self.cache_args = cache_args
+        self.cache_args = repo_name
         self.cache_active = False
 
     def __unicode__(self):
@@ -1664,20 +1665,20 @@
     def _get_cache_key(cls, key):
         """
         Wrapper for generating a unique cache key for this instance and "key".
+        key must / will start with a repo_name which will be stored in .cache_args .
         """
         import rhodecode
         prefix = rhodecode.CONFIG.get('instance_id', '')
         return "%s%s" % (prefix, key)
 
     @classmethod
-    def _get_or_create_inv_obj(cls, key, repo_name, commit=True):
+    def _get_or_create_inv_obj(cls, key, repo_name):
         inv_obj = Session().query(cls).filter(cls.cache_key == key).scalar()
         if not inv_obj:
             try:
                 inv_obj = CacheInvalidation(key, repo_name)
                 Session().add(inv_obj)
-                if commit:
-                    Session().commit()
+                Session().commit()
             except Exception:
                 log.error(traceback.format_exc())
                 Session().rollback()
@@ -1686,11 +1687,8 @@
     @classmethod
     def invalidate(cls, key):
         """
-        Returns Invalidation object if this given key should be invalidated
-        None otherwise. `cache_active = False` means that this cache
-        state is not valid and needs to be invalidated
-
-        :param key:
+        Returns Invalidation object if the local cache with the given key is invalid,
+        None otherwise.
         """
         repo_name = key
         repo_name = remove_suffix(repo_name, '_README')
@@ -1698,10 +1696,12 @@
         repo_name = remove_suffix(repo_name, '_ATOM')
 
         cache_key = cls._get_cache_key(key)
-        inv = cls._get_or_create_inv_obj(cache_key, repo_name)
+        inv_obj = cls._get_or_create_inv_obj(cache_key, repo_name)
 
-        if inv and not inv.cache_active:
-            return inv
+        if inv_obj and not inv_obj.cache_active:
+            # `cache_active = False` means that this cache
+            # no longer is valid
+            return inv_obj
 
     @classmethod
     def set_invalidate(cls, key=None, repo_name=None):
@@ -1734,13 +1734,11 @@
         return invalidated_keys
 
     @classmethod
-    def set_valid(cls, key):
+    def set_valid(cls, cache_key):
         """
         Mark this cache key as active and currently cached
-
-        :param key:
         """
-        inv_obj = cls.query().filter(cls.cache_key == key).scalar()
+        inv_obj = cls.query().filter(cls.cache_key == cache_key).scalar()
         inv_obj.cache_active = True
         Session().add(inv_obj)
         Session().commit()
diff -r 05006e3e286b -r cf65b2c1b69d rhodecode/model/scm.py
--- a/rhodecode/model/scm.py	Thu Apr 04 15:55:53 2013 +0200
+++ b/rhodecode/model/scm.py	Wed Mar 27 19:55:50 2013 +0100
@@ -297,10 +297,9 @@
 
     def mark_for_invalidation(self, repo_name):
         """
-        Puts cache invalidation task into db for
-        further global cache invalidation
+        Mark caches of this repo invalid in the database.
 
-        :param repo_name: this repo that should invalidation take place
+        :param repo_name: the repo for which caches should be marked invalid
         """
         invalidated_keys = CacheInvalidation.set_invalidate(repo_name=repo_name)
         repo = Repository.get_by_repo_name(repo_name)