Mike Bayer avatar Mike Bayer committed 42e7df1

- some doc updates and fixes

Comments (0)

Files changed (3)

docs/build/usage.rst

 caching.   
 
 With a caching system in mind, dogpile.cache provides an interface to a particular Python API
-targeted at that system.  In this document, we'll illustrate Memcached usage 
-using the `pylibmc <http://pypi.python.org/pypi/pylibmc>`_ backend, which is a high performing 
-Python library for Memcached.  It can be compared to the `python-memcached <http://pypi.python.org/pypi/python-memcached>`_
-client, which is also an excellent product.  Pylibmc is written against Memcached's native API
-so is markedly faster, though might be considered to have rougher edges.   The API is actually a bit 
-more verbose to allow for correct multithreaded usage.
+targeted at that system.  
 
 A dogpile.cache configuration consists of the following components:
 
     def load_user_info(user_id):
         return some_database.lookup_user_by_id(user_id)
 
+.. sidebar:: pylibmc
+
+    In this section, we're illustrating Memcached usage 
+    using the `pylibmc <http://pypi.python.org/pypi/pylibmc>`_ backend, which is a high performing 
+    Python library for Memcached.  It can be compared to the `python-memcached <http://pypi.python.org/pypi/python-memcached>`_
+    client, which is also an excellent product.  Pylibmc is written against Memcached's native API
+    so is markedly faster, though might be considered to have rougher edges.   The API is actually a bit 
+    more verbose to allow for correct multithreaded usage.
+
+
 Above, we create a :class:`.CacheRegion` using the :func:`.make_region` function, then
 apply the backend configuration via the :meth:`.CacheRegion.configure` method, which returns the 
 region.  The name of the backend is the only argument required by :meth:`.CacheRegion.configure`

dogpile/cache/api.py

         Different backends may want to provide various
         kinds of "mutex" objects, such as those which
         link to lock files, distributed mutexes,
-        memcached semaphores, timers, etc.  Whatever
+        memcached semaphores, etc.  Whatever
         kind of system is best suited for the scope
         and behavior of the caching backend.
         
+        A mutex that takes the key into account will
+        allow multiple regenerate operations across
+        keys to proceed simultaneously, while a mutex
+        that does not will serialize regenerate operations
+        to just one at a time across all keys in the region.
+        The latter approach, or a variant that involves
+        a modulus of the given key's hash value, 
+        can be used as a means of throttling the total
+        number of value recreation operations that may
+        proceed at one time.
+        
         """
         return None
 

dogpile/cache/region.py

      return a new function that generates the key based on 
      the given arguments.  Such as::
 
-        def my_key_generator(fn):
-            namespace = fn.__name__
+        def my_key_generator(namespace, fn):
+            fname = fn.__name__
             def generate_key(*arg):
-                return namespace + "_".join(str(s) for s in arg)
+                return namespace + "_" + fname + "_".join(str(s) for s in arg)
             return generate_key
 
 
                 "filename":"file.dbm"
             }
         )
+     
+     The ``namespace`` is that passed to 
+     :meth:`.CacheRegion.cache_on_arguments`.  It's not consulted
+     outside this function, so in fact can be of any form.
+     For example, it can be passed as a tuple, used to specify 
+     arguments to pluck from \**kw::
+     
+        def my_key_generator(namespace, fn):
+            def generate_key(*arg, **kw):
+                return ":".join(
+                        [kw[k] for k in namespace] + 
+                        [str(x) for x in arg]
+                    )
+        
+     Where the decorator might be used as::
+     
+        @my_region.cache_on_arguments(namespace=('x', 'y'))
+        def my_function(a, b, **kw):
+            return my_data()
 
     :param key_mangler: Function which will be used on all incoming
      keys before passing to the backend.  Defaults to ``None``,
      which coerces keys into a SHA1
      hash, so that the string length is fixed.  To
      disable all key mangling, set to ``False``.
-    :param lock_generator: Function which, given a cache key,
-     returns a mutexing object.
     
     """
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.