Added cache documentation

git-svn-id: http://code.djangoproject.com/svn/django/trunk@56 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/cache.txt

@@ -0,0 +1,139 @@
+========================
+Django's cache framework
+========================
+
+So, you got slashdotted.  Now what?
+
+Django's cache framework gives you two methods of caching dynamic pages in
+memory or in a database: you can automatically cache the entire page, or you can manually
+cache only the pieces that are difficult to produce.
+
+Setting up the cache
+====================
+
+The cache framework is split into a set of "backends" that provide different
+methods of caching data.  There's a simple single-process memory cache 
+(mostly useful as a fallback), a database-backed cache, and a memcached_
+backend (by far the fastest option if you've got the RAM).
+
+Before using the cache, you'll need to tell Django which cache backend you'd
+like to use; do this by setting the ``CACHE_BACKEND`` in your settings file.
+
+The CACHE_BACKEND setting is a quasi-URI; examples are:
+
+    ==============================  ===========================================
+    CACHE_BACKEND                   Explanation
+    ==============================  ===========================================
+    memcached://127.0.0.1:11211/    A memcached backend; the server is running 
+                                    on localhost port 11211.
+                                    
+    db://tablename/                 A database backend (the db backend uses 
+                                    the same database/username as the rest of
+                                    the CMS, so only a table name is needed.)
+                                    
+    simple:///                      A simple single-process memory cache; you
+                                    probably don't want to use this except for
+                                    testing. Note that this cache backend is 
+                                    NOT threadsafe!
+    ==============================  ===========================================
+
+All caches may take arguments; these are given in query-string style.  Valid
+arguments are:
+
+    timeout         
+        Default timeout, in seconds, to use for the cache.  Defaults
+        to 5 minutes (300 seconds).
+                
+    max_entries     
+        For the simple and database backends, the maximum number of entries
+        allowed in the cache before it is cleaned.  Defaults to 300.
+                
+    cull_percentage 
+        The percentage of entries that are culled when max_entries is reached. 
+        The actual percentage is 1/cull_percentage, so set cull_percentage=3 to
+        cull 1/3 of the entries when max_entries is reached.
+        
+        A value of 0 for cull_percentage means that the entire cache will be
+        dumped when max_entries is reached.  This makes culling *much* faster
+        at the expense of more cache misses.
+                
+For example::
+
+    DB_CACHE = "memcached://127.0.0.1:11211/?timeout=60"
+    DB_CACHE = "db://tablename/?timeout=120&max_entries=500&cull_percentage=4"
+    
+Invalid arguments are silently ignored, as are invalid values of known 
+arguments.
+
+The per-page cache
+==================
+
+Once the cache is set up, the simplest way to use the cache is to simply
+cache entire view functions.  ``django.views.decorators.cache`` defines
+a ``cache_page`` decorator that will automatically cache the view's response
+for you.  Using it couldn't be easier::
+
+    from django.views.decorators.cache import cache_page
+    
+    def slashdot_this(request):
+        ...
+   
+    slashdot_this = cache_page(slashdot_this, 60 * 15):
+
+Or, using Python 2.4's decorator syntax::
+
+    @cache_page(60 * 15)
+    def slashdot_this(request):
+        ...
+
+This will cache the result of that view for 15 minutes (the cache timeout is
+in seconds).
+
+The low-level cache API
+=======================
+
+There are times, however, that caching an entire rendered page doesn't gain
+you very much.  We often find that we only need to cache a list of object IDs
+from an intensive database query, for example.  In cases like these, you
+can use the cache API to store objects in the cache with any level of 
+granularity you like.
+
+The cache API is almost shockingly simple::
+
+    # the cache module exports a cache object that's automatically
+    # created from the CACHE_BACKEND setting
+    >>> from django.core.cache import cache
+    
+    # The basic interface is set(key, value, timeout_seconds) and get(key)
+    >>> cache.set('my_key', 'hello, world!', 30)
+    >>> cache.get('my_key')
+    'hello, world!'
+    
+    # (wait 30 seconds...)
+    >>> cache.get('my_key')
+    None
+    
+    # get can take a default argument
+    >>> cache.get('my_key', 'has_expired')
+    'has_expired'
+    
+    # there's also a get_many interface that only hits the cache once
+    # also, note that the timeout argument is optional and defaults
+    # to what you've given in the settings file.
+    >>> cache.set('a', 1)
+    >>> cache.set('b', 2)
+    >>> cache.set('c', 3)
+    >>> cache.get_many(['a', 'b', 'c'])
+    {'a': 1, 'b': 2, 'c': 3}
+    # get_many returns a dict with all the keys you asked for that
+    # actually exist in the cache (and haven't expired)
+    
+    # there's also a way to explicitly delete keys
+    >>> cache.delete('a')
+    
+Really, that's the entire API!  There's very few restrictions on what you can
+use the cache for; you can store any object in the cache that can be pickled
+safely, although keys must be strings.
+
+.. _memcached: http://www.danga.com/memcached/
+