summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/caching.rst
diff options
context:
space:
mode:
authorAndrew <browner12@gmail.com>2014-02-11 09:55:48 +0100
committerAndrew <browner12@gmail.com>2014-02-11 09:55:48 +0100
commitb6d8b962e44202a74c9b9321a4a53f61a753fccf (patch)
tree2d3c533a55964a0d124f7cd6bb1d3d98c7b84056 /user_guide_src/source/libraries/caching.rst
parent41713aaa665189dd0a191c333c73c4a7b9f37c78 (diff)
parent29e12641a1bb952f493462db6757ae12c7da1f2c (diff)
Merge branch 'develop' into patch-1
Conflicts: system/libraries/Calendar.php
Diffstat (limited to 'user_guide_src/source/libraries/caching.rst')
-rw-r--r--user_guide_src/source/libraries/caching.rst184
1 files changed, 97 insertions, 87 deletions
diff --git a/user_guide_src/source/libraries/caching.rst b/user_guide_src/source/libraries/caching.rst
index 3f7dc2dd9..caece1aee 100644
--- a/user_guide_src/source/libraries/caching.rst
+++ b/user_guide_src/source/libraries/caching.rst
@@ -7,7 +7,12 @@ fast and dynamic caching. All but file-based caching require specific
server requirements, and a Fatal Exception will be thrown if server
requirements are not met.
-.. contents:: Table of Contents
+.. contents::
+ :local:
+
+.. raw:: html
+
+ <div class="custom-index container"></div>
*************
Example Usage
@@ -20,16 +25,16 @@ available in the hosting environment.
::
$this->load->driver('cache', array('adapter' => 'apc', 'backup' => 'file'));
-
+
if ( ! $foo = $this->cache->get('foo'))
{
echo 'Saving to the cache!<br />';
$foo = 'foobarbaz!';
-
+
// Save into the cache for 5 minutes
$this->cache->save('foo', $foo, 300);
}
-
+
echo $foo;
You can also prefix cache item names via the **key_prefix** setting, which is useful
@@ -43,28 +48,24 @@ to avoid collisions when you're running multiple applications on the same enviro
$this->cache->get('foo'); // Will get the cache entry named 'my_foo'
-******************
-Function Reference
-******************
+***************
+Class Reference
+***************
-.. php:class:: CI_Cache
+.. class:: CI_Cache
-is_supported()
-==============
+ .. method:: is_supported($driver)
- .. php:method:: is_supported ( $driver )
+ :param string $driver: the name of the caching driver
+ :returns: TRUE if supported, FALSE if not
+ :rtype: bool
- This function is automatically called when accessing drivers via
- $this->cache->get(). However, if the individual drivers are used, make
- sure to call this function to ensure the driver is supported in the
+ This method is automatically called when accessing drivers via
+ ``$this->cache->get()``. However, if the individual drivers are used,
+ make sure to call this method to ensure the driver is supported in the
hosting environment.
-
- :param string $driver: the name of the caching driver
- :returns: TRUE if supported, FALSE if not
- :rtype: Boolean
-
::
-
+
if ($this->cache->apc->is_supported()
{
if ($data = $this->cache->apc->get('my_cache'))
@@ -73,103 +74,112 @@ is_supported()
}
}
+ .. method:: get($id)
-get()
-=====
-
- .. php:method:: get ( $id )
-
- This function will attempt to fetch an item from the cache store. If the
- item does not exist, the function will return FALSE.
+ :param string $id: Cache item name
+ :returns: Item value or FALSE if not found
+ :rtype: mixed
- :param string $id: name of cached item
- :returns: The item if it exists, FALSE if it does not
- :rtype: Mixed
-
+ This method will attempt to fetch an item from the cache store. If the
+ item does not exist, the method will return FALSE.
::
$foo = $this->cache->get('my_cached_item');
+ .. method:: save($id, $data[, $ttl = 60[, $raw = FALSE]])
-save()
-======
-
- .. php:method:: save ( $id , $data [, $ttl])
-
- This function will save an item to the cache store. If saving fails, the
- function will return FALSE.
-
- :param string $id: name of the cached item
- :param mixed $data: the data to save
- :param int $ttl: Time To Live, in seconds (default 60)
- :returns: TRUE on success, FALSE on failure
- :rtype: Boolean
+ :param string $id: Cache item name
+ :param mixed $data: the data to save
+ :param int $ttl: Time To Live, in seconds (default 60)
+ :param bool $raw: Whether to store the raw value
+ :returns: TRUE on success, FALSE on failure
+ :rtype: string
+ This method will save an item to the cache store. If saving fails, the
+ method will return FALSE.
::
$this->cache->save('cache_item_id', 'data_to_cache');
-
-delete()
-========
- .. php:method:: delete ( $id )
-
- This function will delete a specific item from the cache store. If item
- deletion fails, the function will return FALSE.
+ .. note:: The ``$raw`` parameter is only utilized by APC and Memcache,
+ in order to allow usage of ``increment()`` and ``decrement()``.
- :param string $id: name of cached item
- :returns: TRUE if deleted, FALSE if the deletion fails
- :rtype: Boolean
-
+ .. method:: delete($id)
+
+ :param string $id: name of cached item
+ :returns: TRUE on success, FALSE on failure
+ :rtype: bool
+
+ This method will delete a specific item from the cache store. If item
+ deletion fails, the method will return FALSE.
::
$this->cache->delete('cache_item_id');
-clean()
-=======
+ .. method:: increment($id[, $offset = 1])
- .. php:method:: clean ( )
-
- This function will 'clean' the entire cache. If the deletion of the
- cache files fails, the function will return FALSE.
+ :param string $id: Cache ID
+ :param int $offset: Step/value to add
+ :returns: New value on success, FALSE on failure
+ :rtype: mixed
- :returns: TRUE if deleted, FALSE if the deletion fails
- :rtype: Boolean
-
+ Performs atomic incrementation of a raw stored value.
::
- $this->cache->clean();
+ // 'iterator' has a value of 2
+
+ $this->cache->increment('iterator'); // 'iterator' is now 3
-cache_info()
-============
+ $this->cache->increment('iterator', 3); // 'iterator' is now 6
- .. php:method:: cache_info ( )
+ .. method:: decrement($id[, $offset = 1])
- This function will return information on the entire cache.
+ :param string $id: Cache ID
+ :param int $offset: Step/value to reduce by
+ :returns: New value on success, FALSE on failure
+ :rtype: mixed
- :returns: information on the entire cache
- :rtype: Mixed
-
+ Performs atomic decrementation of a raw stored value.
+ ::
+
+ // 'iterator' has a value of 6
+
+ $this->cache->decrement('iterator'); // 'iterator' is now 5
+
+ $this->cache->decrement('iterator', 2); // 'iterator' is now 3
+
+ .. method:: clean()
+
+ :returns: TRUE on success, FALSE on failure
+ :rtype: bool
+
+ This method will 'clean' the entire cache. If the deletion of the
+ cache files fails, the method will return FALSE.
+ ::
+
+ $this->cache->clean();
+
+ .. method:: cache_info()
+
+ :returns: Information on the entire cache database
+ :rtype: mixed
+
+ This method will return information on the entire cache.
::
var_dump($this->cache->cache_info());
-
+
.. note:: The information returned and the structure of the data is dependent
on which adapter is being used.
-
-get_metadata()
-==============
+ .. method:: get_metadata($id)
- .. php:method:: get_metadata ( $id )
-
- This function will return detailed information on a specific item in the
+ :param string $id: Cache item name
+ :returns: Metadata for the cached item
+ :rtype: mixed
+
+ This method will return detailed information on a specific item in the
cache.
-
- :param string $id: name of cached item
- :returns: metadadta for the cached item
- :rtype: Mixed
-
::
var_dump($this->cache->get_metadata('my_cached_item'));
@@ -184,7 +194,7 @@ Drivers
Alternative PHP Cache (APC) Caching
===================================
-All of the functions listed above can be accessed without passing a
+All of the methods listed above can be accessed without passing a
specific adapter to the driver loader as follows::
$this->load->driver('cache');
@@ -201,7 +211,7 @@ allows for pieces of view files to be cached. Use this with care, and
make sure to benchmark your application, as a point can come where disk
I/O will negate positive gains by caching.
-All of the functions listed above can be accessed without passing a
+All of the methods listed above can be accessed without passing a
specific adapter to the driver loader as follows::
$this->load->driver('cache');
@@ -227,7 +237,7 @@ WinCache Caching
Under Windows, you can also utilize the WinCache driver.
-All of the functions listed above can be accessed without passing a
+All of the methods listed above can be accessed without passing a
specific adapter to the driver loader as follows::
$this->load->driver('cache');