Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// Moodle is free software: you can redistribute it and/or modify

// it under the terms of the GNU General Public License as published by

// the Free Software Foundation, either version 3 of the License, or

// (at your option) any later version.

//

// Moodle is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

// GNU General Public License for more details.

//

// You should have received a copy of the GNU General Public License

// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**

 * Cache store - base class

 *

 * This file is part of Moodle's cache API, affectionately called MUC.

 * It contains the components that are required in order to use caching.

 *

 * @package    core

 * @category   cache

 * @copyright  2012 Sam Hemelryk

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

defined('MOODLE_INTERNAL') || die();

/**

 * Cache store interface.

 *

 * This interface defines the static methods that must be implemented by every cache store plugin.

 * To ensure plugins implement this class the abstract cache_store class implements this interface.

 *

 * @package    core

 * @category   cache

 * @copyright  2012 Sam Hemelryk

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

interface cache_store_interface {

    /**

     * Static method to check if the store requirements are met.

     *

     * @return bool True if the stores software/hardware requirements have been met and it can be used. False otherwise.

     */

    public static function are_requirements_met();

    /**

     * Static method to check if a store is usable with the given mode.

     *

     * @param int $mode One of cache_store::MODE_*

     */

    public static function is_supported_mode($mode);

    /**

     * Returns the supported features as a binary flag.

     *

     * @param array $configuration The configuration of a store to consider specifically.

     * @return int The supported features.

     */

    public static function get_supported_features(array $configuration = array());

    /**

     * Returns the supported modes as a binary flag.

     *

     * @param array $configuration The configuration of a store to consider specifically.

     * @return int The supported modes.

     */

    public static function get_supported_modes(array $configuration = array());

    /**

     * Generates an instance of the cache store that can be used for testing.

     *

     * Returns an instance of the cache store, or false if one cannot be created.

     *

     * @param cache_definition $definition

     * @return cache_store|false

     */

    public static function initialise_test_instance(cache_definition $definition);

    /**

     * Generates the appropriate configuration required for unit testing.

     *

     * @return array Array of unit test configuration data to be used by initialise().

     */

    public static function unit_test_configuration();

}

/**

 * Abstract cache store class.

 *

 * All cache store plugins must extend this base class.

 * It lays down the foundation for what is required of a cache store plugin.

 *

 * @since Moodle 2.4

 * @package    core

 * @category   cache

 * @copyright  2012 Sam Hemelryk

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

abstract class cache_store implements cache_store_interface {

    // Constants for features a cache store can support

    /**

     * Supports multi-part keys

     */

    const SUPPORTS_MULTIPLE_IDENTIFIERS = 1;

    /**

     * Ensures data remains in the cache once set.

     */

    const SUPPORTS_DATA_GUARANTEE = 2;

    /**

     * Supports a native ttl system.

     */

    const SUPPORTS_NATIVE_TTL = 4;

    /**

     * The cache is searchable by key.

     */

    const IS_SEARCHABLE = 8;

    /**

     * The cache store dereferences objects.

     *

     * 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

    /**

     * Application caches. These are shared caches.

     */

    const MODE_APPLICATION = 1;

    /**

     * Session caches. Just access to the PHP session.

     */

    const MODE_SESSION = 2;

    /**

     * Request caches. Static caches really.

     */

    const MODE_REQUEST = 4;

    /**

     * Static caches.

     */

    const STATIC_ACCEL = '** static accel. **';

    /**

     * Returned from get_last_io_bytes if this cache store doesn't support counting bytes read/sent.

     */

    const IO_BYTES_NOT_SUPPORTED = -1;

    /**

     * Constructs an instance of the cache store.

     *

     * The constructor should be responsible for creating anything needed by the store that is not

     * specific to a definition.

     * Tasks such as opening a connection to check it is available are best done here.

     * Tasks that are definition specific such as creating a storage area for the definition data

     * or creating key tables and indexs are best done within the initialise method.

     *

     * Once a store has been constructed the cache API will check it is ready to be intialised with

     * a definition by called $this->is_ready().

     * If the setup of the store failed (connection could not be established for example) then

     * that method should return false so that the store instance is not selected for use.

     *

     * @param string $name The name of the cache store

     * @param array $configuration The configuration for this store instance.

     */

    abstract public function __construct($name, array $configuration = array());

    /**

     * Returns the name of this store instance.

     * @return string

     */

    abstract public function my_name();

    /**

     * Initialises a new instance of the cache store given the definition the instance is to be used for.

     *

     * This function should be used to run any definition specific setup the store instance requires.

     * Tasks such as creating storage areas, or creating indexes are best done here.

     *

     * Its important to note that the initialise method is expected to always succeed.

     * If there are setup tasks that may fail they should be done within the __construct method

     * and should they fail is_ready should return false.

     *

     * @param cache_definition $definition

     */

    abstract public function initialise(cache_definition $definition);

    /**

     * Returns true if this cache store instance has been initialised.

     * @return bool

     */

    abstract public function is_initialised();

    /**

     * Returns true if this cache store instance is ready to use.

     * @return bool

     */

    public function is_ready() {

        return forward_static_call(array($this, 'are_requirements_met'));

    }

    /**

     * Retrieves an item from the cache store given its key.

     *

     * @param string $key The key to retrieve

     * @return mixed The data that was associated with the key, or false if the key did not exist.

     */

    abstract public function get($key);

    /**

     * Retrieves several items from the cache store in a single transaction.

     *

     * If not all of the items are available in the cache then the data value for those that are missing will be set to false.

     *

     * @param array $keys The array of keys to retrieve

     * @return array An array of items from the cache. There will be an item for each key, those that were not in the store will

     *      be set to false.

     */

    abstract public function get_many($keys);

    /**

     * Sets an item in the cache given its key and data value.

     *

     * @param string $key The key to use.

     * @param mixed $data The data to set.

     * @return bool True if the operation was a success false otherwise.

     */

    abstract public function set($key, $data);

    /**

     * Sets many items in the cache in a single transaction.

     *

     * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two

     *      keys, 'key' and 'value'.

     * @return int The number of items successfully set. It is up to the developer to check this matches the number of items

     *      sent ... if they care that is.

     */

    abstract public function set_many(array $keyvaluearray);

    /**

     * Deletes an item from the cache store.

     *

     * @param string $key The key to delete.

     * @return bool Returns true if the operation was a success, false otherwise.

     */

    abstract public function delete($key);

    /**

     * Deletes several keys from the cache in a single action.

     *

     * @param array $keys The keys to delete

     * @return int The number of items successfully deleted.

     */

    abstract public function delete_many(array $keys);

    /**

     * Purges the cache deleting all items within it.

     *

     * @return boolean True on success. False otherwise.

     */

    abstract public function purge();

    /**

     * @deprecated since 2.5

     * @see \cache_store::instance_deleted()

     */

    public function cleanup() {

        throw new coding_exception('cache_store::cleanup() can not be used anymore.' .

            ' Please use cache_store::instance_deleted() instead.');

    }

    /**

     * Performs any necessary operation when the store instance has been created.

     *

     * @since Moodle 2.5

     */

    public function instance_created() {

        // By default, do nothing.

    }

    /**

     * Performs any necessary operation when the store instance is being deleted.

     *

     * This method may be called before the store has been initialised.

     *

     * @since Moodle 2.5

     * @see cleanup()

     */

    public function instance_deleted() {

        if (method_exists($this, 'cleanup')) {

            // There used to be a legacy function called cleanup, it was renamed to instance delete.

            // To be removed in 2.6.

            $this->cleanup();

        }

    }

    /**

     * Returns true if the user can add an instance of the store plugin.

     *

     * @return bool

     */

    public static function can_add_instance() {

        return true;

    }

    /**

     * Returns true if the store instance guarantees data.

     *

     * @return bool

     */

    public function supports_data_guarantee() {

        return $this::get_supported_features() & self::SUPPORTS_DATA_GUARANTEE;

    }

    /**

     * Returns true if the store instance supports multiple identifiers.

     *

     * @return bool

     */

    public function supports_multiple_identifiers() {

        return $this::get_supported_features() & self::SUPPORTS_MULTIPLE_IDENTIFIERS;

    }

    /**

     * Returns true if the store instance supports native ttl.

     *

     * @return bool

     */

    public function supports_native_ttl() {

        return $this::get_supported_features() & self::SUPPORTS_NATIVE_TTL;

    }

    /**

     * Returns true if the store instance is searchable.

     *

     * @return bool

     */

    public function is_searchable() {

        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.

     *

     * This method is used so that a cache store needs only be constructed once.

     * Future requests for an instance of the store will be given a cloned instance.

     *

     * If you are writing a cache store that isn't compatible with the clone operation

     * you can override this method to handle any situations you want before cloning.

     *

     * @param array $details An array containing the details of the store from the cache config.

     * @return cache_store

     */

    public function create_clone(array $details = array()) {

        // By default we just run clone.

        // Any stores that have an issue with this will need to override the create_clone method.

        return clone($this);

    }

    /**

     * Can be overridden to return any warnings this store instance should make to the admin.

     *

     * This should be used to notify things like configuration conflicts etc.

     * The warnings returned here will be displayed on the cache configuration screen.

     *

     * @return string[] An array of warning strings from the store instance.

     */

    public function get_warnings() {

        return array();

    }

    /**

     * Estimates the storage size used within this cache if the given value is stored with the

     * given key.

     *

     * This function is not exactly accurate; it does not necessarily take into account all the

     * overheads involved. It is only intended to give a good idea of the relative size of

     * different caches.

     *

     * The default implementation serializes both key and value and sums the lengths (as a rough

     * estimate which is probably good enough for everything unless the cache offers compression).

     *

     * @param mixed $key Key

     * @param mixed $value Value

     * @return int Size in bytes

     */

    public function estimate_stored_size($key, $value): int {

        return strlen(serialize($key)) + strlen(serialize($value));

    }

    /**

     * Gets the amount of memory/storage currently used by this cache store if known.

     *

     * This value should be obtained quickly from the store itself, if available.

     *

     * This is the total memory usage of the entire store, not for ther specific cache in question.

     *

     * Where not supported (default), will always return null.

     *

     * @return int|null Amount of memory used in bytes or null

     */

    public function store_total_size(): ?int {

        return null;

    }

    /**

     * Gets the amount of memory used by this specific cache within the store, if known.

     *

     * This function may be slow and should not be called in normal usage, only for administration

     * pages. The value is usually an estimate, and may not be available at all.

     *

     * When estimating, a number of sample items will be used for the estimate. If set to 50

     * (default), then this function will retrieve 50 random items and use that to estimate the

     * total size.

     *

     * The return value has the following fields:

     * - supported (true if any other values are completed)

     * - items (number of items)

     * - mean (mean size of one item in bytes)

     * - sd (standard deviation of item size in bytes, based on sample)

     * - margin (95% confidence margin for mean - will be 0 if exactly computed)

     *

     * @param int $samplekeys Number of samples to use

     * @return stdClass Object with information about the store size

     */

    public function cache_size_details(int $samplekeys = 50): stdClass {

        $result = (object)[

            'supported' => false,

            'items' => 0,

            'mean' => 0,

            'sd' => 0,

            'margin' => 0

        ];

        // If this cache isn't searchable, we don't know the answer.

        if (!$this->is_searchable()) {

            return $result;

        }

        $result->supported = true;

        // Get all the keys for the cache.

        $keys = $this->find_all();

        $result->items = count($keys);

        // Don't do anything else if there are no items.

        if ($result->items === 0) {

            return $result;

        }

        // Select N random keys.

        $exact = false;

        if ($result->items <= $samplekeys) {

            $samples = $keys;

            $exact = true;

        } else {

            $indexes = array_rand($keys, $samplekeys);

            $samples = [];

            foreach ($indexes as $index) {

                $samples[] = $keys[$index];

            }

        }

        // Get the random items from cache and estimate the size of each.

        $sizes = [];

        foreach ($samples as $samplekey) {

            $value = $this->get($samplekey);

            $sizes[] = $this->estimate_stored_size($samplekey, $value);

        }

        $number = count($sizes);

        // Calculate the mean and standard deviation.

        $result->mean = array_sum($sizes) / $number;

        $squarediff = 0;

        foreach ($sizes as $size) {

            $squarediff += ($size - $result->mean) ** 2;

        }

        $squarediff /= $number;

        $result->sd = sqrt($squarediff);

        // If it's not exact, also calculate the confidence interval.

        if (!$exact) {

            // 95% confidence has a Z value of 1.96.

            $result->margin = (1.96 * $result->sd) / sqrt($number);

        }

        return $result;

    }

    /**

     * Returns true if this cache store instance is both suitable for testing, and ready for testing.

     *

     * Cache stores that support being used as the default store for unit and acceptance testing should

     * override this function and return true if there requirements have been met.

     *

     * @return bool

     */

    public static function ready_to_be_used_for_testing() {

        return false;

    }

    /**

     * Gets the number of bytes read from or written to cache as a result of the last action.

     *

     * This includes calls to the functions get(), get_many(), set(), and set_many(). The number

     * is reset by calling any of these functions.

     *

     * This should be the actual number of bytes of the value read from or written to cache,

     * giving an impression of the network or other load. It will not be exactly the same amount

     * as netowrk traffic because of protocol overhead, key text, etc.

     *

     * If not supported, returns IO_BYTES_NOT_SUPPORTED.

     *

     * @return int Bytes read (or 0 if none/not supported)

     * @since Moodle 4.0

     */

    public function get_last_io_bytes(): int {

        return self::IO_BYTES_NOT_SUPPORTED;

    }

}