Commits

Anonymous committed 00fb348

Improved cache.blocking documentation

Comments (0)

Files changed (1)

docs/configuration.html

 </p>
 
 <h3>cache.blocking</h3>
-<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
-provides the best performance (at the cost of serving slightly stale data).</p>
+<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>
 
 <h3>cache.unlimited.disk</h3>
 <p>Indicates whether the disk cache should be treated as unlimited or not. The default value is