Permalink
Browse files

MDL-36322 cache: clarified docs for initialise and construct

  • Loading branch information...
1 parent 770eed8 commit 722907c7b0243c0b3060d5358db0d137b5c140f1 Sam Hemelryk committed Jan 30, 2013
Showing with 28 additions and 4 deletions.
  1. +16 −2 cache/classes/store.php
  2. +12 −2 cache/stores/mongodb/lib.php
View
@@ -128,7 +128,16 @@ public static function initialise_test_instance(cache_definition $definition);
/**
* Constructs an instance of the cache store.
*
- * This method should not create connections or perform and processing, it should be used
+ * 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.
@@ -144,7 +153,12 @@ public static function initialise_test_instance(cache_definition $definition);
/**
* Initialises a new instance of the cache store given the definition the instance is to be used for.
*
- * This function should prepare any given connections etc.
+ * 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
*/
@@ -100,7 +100,17 @@ class cachestore_mongodb extends cache_store implements cache_is_configurable {
protected $definitionhash = null;
/**
- * Constructs a new instance of the Mongo store but does not connect to it.
+ * Set to true once this store is ready to be initialised and used.
+ * @var bool
+ */
+ protected $isready = false;
+
+ /**
+ * Constructs a new instance of the Mongo store.
+ *
+ * Noting that this function is not an initialisation. It is used to prepare the store for use.
+ * The store will be initialised when required and will be provided with a cache_definition at that time.
+ *
* @param string $name
* @param array $configuration
*/
@@ -171,7 +181,7 @@ public static function get_supported_modes(array $configuration = array()) {
/**
* Initialises the store instance for use.
*
- * This function is reponsible for making the connection.
+ * Once this has been done the cache is all set to be used.
*
* @param cache_definition $definition
* @throws coding_exception

0 comments on commit 722907c

Please sign in to comment.