Files changed (1)
-<p>Specifies whether we should block waiting for new content to be generated, or just serve the old content
-instead. The default behaviour is to serve the old content (<code>cache.blocking=false</code>) since that
+<p>When a request is made for a stale cache entry, it is possible that another thread is already in the process
+of rebuilding that entry. This setting specifies how OSCache handles the subsequent 'non-building' threads. The
+default behaviour (<code>cache.blocking=false</code>) is to serve the old content to subsequent threads until the
+cache entry has been updated. This provides the best performance (at the cost of serving slightly stale data).
+When blocking is enabled, threads will instead block until the new cache entry is ready to be served.
+Once the new entry is put in the cache the blocked threads will be restarted and given the new entry.</p>
+<p>Note that <em>even if blocking is disabled</em>, when there is no stale data available to be served threads
+will block until the data is added to the cache by the thread that is responsible for building the data.</p>