From b2159f2d3f79c401c6c04c9d689fc86bbb29effc Mon Sep 17 00:00:00 2001
From: Russell Smith <mr-russ@smith2001.net>
Date: Tue, 23 Feb 2016 13:22:48 +1100
Subject: [PATCH] MDL-53208 caching: Enable dereferencing as a feature.

If the cache does all the dereferencing when it stores and loads
the objects, then the cache loaders don't need to do that work.
This is true of all caches that use something other than PHP's memory
to store their results.
---
 cache/classes/store.php        | 17 +++++++++++++++++
 cache/stores/file/lib.php      |  3 ++-
 cache/stores/memcache/lib.php  |  2 +-
 cache/stores/memcached/lib.php |  2 +-
 cache/stores/mongodb/lib.php   |  2 +-
 cache/upgrade.txt              |  6 ++++++
 6 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/cache/classes/store.php b/cache/classes/store.php
index 2c4b09915ad..3a039630cc6 100644
--- a/cache/classes/store.php
+++ b/cache/classes/store.php
@@ -126,6 +126,14 @@ abstract class cache_store implements cache_store_interface {
      */
     const IS_SEARCHABLE = 8;
 
+    /**
+     * The cache store dereferences objects.@global
+     *
+     * When set, loaders will assume that all data coming from this store has already had all references
+     * resolved.  So even for complex object structures it will not try to remove references again.
+     */
+    const DEREFERENCES_OBJECTS = 16;
+
     // Constants for the modes of a cache store
 
     /**
@@ -334,6 +342,15 @@ abstract class cache_store implements cache_store_interface {
         return in_array('cache_is_searchable', class_implements($this));
     }
 
+    /**
+     * Returns true if the store automatically dereferences objects.
+     *
+     * @return bool
+     */
+    public function supports_dereferencing_objects() {
+        return $this::get_supported_features() & self::DEREFERENCES_OBJECTS;
+    }
+
     /**
      * Creates a clone of this store instance ready to be initialised.
      *
diff --git a/cache/stores/file/lib.php b/cache/stores/file/lib.php
index e044c91609b..67a6642a641 100644
--- a/cache/stores/file/lib.php
+++ b/cache/stores/file/lib.php
@@ -211,7 +211,8 @@ class cachestore_file extends cache_store implements cache_is_key_aware, cache_i
     public static function get_supported_features(array $configuration = array()) {
         $supported = self::SUPPORTS_DATA_GUARANTEE +
                      self::SUPPORTS_NATIVE_TTL +
-                     self::IS_SEARCHABLE;
+                     self::IS_SEARCHABLE +
+                     self::DEREFERENCES_OBJECTS;
         return $supported;
     }
 
diff --git a/cache/stores/memcache/lib.php b/cache/stores/memcache/lib.php
index 77efd211312..e4ead7fe3bb 100644
--- a/cache/stores/memcache/lib.php
+++ b/cache/stores/memcache/lib.php
@@ -271,7 +271,7 @@ class cachestore_memcache extends cache_store implements cache_is_configurable {
      * @return int
      */
     public static function get_supported_features(array $configuration = array()) {
-        return self::SUPPORTS_NATIVE_TTL;
+        return self::SUPPORTS_NATIVE_TTL + self::DEREFERENCES_OBJECTS;
     }
 
     /**
diff --git a/cache/stores/memcached/lib.php b/cache/stores/memcached/lib.php
index 0ed66239cdc..5e8250d1633 100644
--- a/cache/stores/memcached/lib.php
+++ b/cache/stores/memcached/lib.php
@@ -258,7 +258,7 @@ class cachestore_memcached extends cache_store implements cache_is_configurable
      * @return int
      */
     public static function get_supported_features(array $configuration = array()) {
-        return self::SUPPORTS_NATIVE_TTL;
+        return self::SUPPORTS_NATIVE_TTL + self::DEREFERENCES_OBJECTS;
     }
 
     /**
diff --git a/cache/stores/mongodb/lib.php b/cache/stores/mongodb/lib.php
index 7ea787dd11f..641b05165a3 100644
--- a/cache/stores/mongodb/lib.php
+++ b/cache/stores/mongodb/lib.php
@@ -175,7 +175,7 @@ class cachestore_mongodb extends cache_store implements cache_is_configurable {
      * @return int
      */
     public static function get_supported_features(array $configuration = array()) {
-        $supports = self::SUPPORTS_DATA_GUARANTEE;
+        $supports = self::SUPPORTS_DATA_GUARANTEE + self::DEREFERENCES_OBJECTS;
         if (array_key_exists('extendedmode', $configuration) && $configuration['extendedmode']) {
             $supports += self::SUPPORTS_MULTIPLE_IDENTIFIERS;
         }
diff --git a/cache/upgrade.txt b/cache/upgrade.txt
index 1c1b13342b8..0b4cbb941fc 100644
--- a/cache/upgrade.txt
+++ b/cache/upgrade.txt
@@ -1,6 +1,12 @@
 This files describes API changes in /cache/stores/* - cache store plugins.
 Information provided here is intended especially for developers.
 
+=== 3.1 ===
+* Cache stores has a new feature DEREFERENCES_OBJECTS.
+  This allows the cache loader to decide if it needs to handle dereferencing or whether the data
+  coming directly to it has already had references resolved.
+  - see supports_dereferencing_objects in store.php.
+
 === 2.9 ===
 * Cache data source aggregation functionality has been removed. This functionality was found to be broken and unused.
   It was decided that rather than fixing it it should be removed.