add documentation on caching

config/magpie.ini

@@ -28,7 +28,7 @@ magpie.max_restart = 5
 magpie.secret = seekrit
 magpie.push_phoenix = true
 
-# caching settings for specific sections/functions
+# caching settings refer to the Performance section in the documentation
 cache.regions = adapter
 # cache.type = memory
 # cache.adapter.expire = 5

docs/index.rst

@@ -12,6 +12,7 @@ Package information
 
    usage
    installation
+   performance
    contributing
    authors
    history

docs/performance.rst

@@ -0,0 +1,25 @@
+===========
+Performance
+===========
+
+Requesting permissions for a specific user and service can be demanding if a lot of
+requests are done rapidly. PostgreSQL and sqlalchemy are usually fast enough, but
+when more than a couple requests per second are needed, some solutions are possible to
+improve the performance of these requests.
+
+We can take advantage of the fact that permission are not susceptible to change often
+and cache the results of these permission queries.
+
+While not activated by default, it's possible to cache the access control lists (ACLs)
+for all services, and give it an expiration timeout::
+
+  # example Paste Deploy configuration
+  cache.regions = adapter
+  cache.type = memory
+  cache.adapter.expire = 5  # seconds
+
+For a particular request that queries a user's ACL
+for a specific service, the response will be cached for 5 seconds. The consequence of this
+caching is that any permission change will take 5 seconds to be effective. Depending on the
+use case, this can be perfectly acceptable and the performance improvement is not negligible.
+You should test and profile for your particular environment.