Issue #2541432 by Wim Leers: Follow-up for #2231595: Document why...

Issue #2541432 by Wim Leers: Follow-up for #2231595: Document why ChainedFastBackend cannot use BackendChain

core/core.api.php

@@ -569,6 +569,9 @@
  *  $settings['cache']['default'] = 'cache.custom';
  * @endcode
  *
+ * Finally, you can chain multiple cache backends together, see
+ * \Drupal\Core\Cache\ChainedFastBackend and \Drupal\Core\Cache\BackendChain.
+ *
  * @see https://www.drupal.org/node/1884796
  * @}
  */

core/lib/Drupal/Core/Cache/BackendChain.php

@@ -20,6 +20,8 @@
  * to ensure fast retrieval on the next request. On cache sets and deletes, both
  * backends will be invoked to ensure consistency.
  *
+ * @see \Drupal\Core\Cache\ChainedFastBackend
+ *
  * @ingroup cache
  */
 

core/lib/Drupal/Core/Cache/ChainedFastBackend.php

@@ -39,6 +39,15 @@
  * Because this backend will mark all the cache entries in a bin as out-dated
  * for each write to a bin, it is best suited to bins with fewer changes.
  *
+ * Note that this is designed specifically for combining a fast inconsistent
+ * cache backend with a slower consistent cache back-end. To still function
+ * correctly, it needs to do a consistency check (see the "last write timestamp"
+ * logic). This contrasts with \Drupal\Core\Cache\BackendChain, which assumes
+ * both chained cache backends are consistent, thus a consistency check being
+ * pointless.
+ *
+ * @see \Drupal\Core\Cache\BackendChain
+ *
  * @ingroup cache
  */
 class ChainedFastBackend implements CacheBackendInterface, CacheTagsInvalidatorInterface {