[sheepdog] [PATCH 3/9] Doc. "Sheepdog Advanced" add chapter "cache"

[Valerio Pachera]

Signed-off-by: Valerio Pachera <sirio81 at gmail.com>
---
 doc/cache.rst |   82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 doc/cache.rst

diff --git a/doc/cache.rst b/doc/cache.rst
new file mode 100644
index 0000000..a5f457e
--- /dev/null
+++ b/doc/cache.rst
@@ -0,0 +1,82 @@
+Cache
+=====
+
+Concepts
+********
+
+    * The use of cache always implies risks (general rule).
+    * There's not only one cache type.
+    * You don't have to use it, sheepdog will work anyway.
+    * If you need more I/O performance, evaluate what's better for your environment.
+
+Cache Layers
+************
+
+If you wish to test the speed of your PC hard disk you may run
+
+::
+
+    dd if=/dev/zero of=/tmp/test bs=1M count=128
+
+| If you read something crazy like **1,1 GB/s**, it doesn't mean you hard disk is that fast!
+| Simply the OS has been writing data in RAM.
+| This is the first cache we meet.
+| To skip it, add the option *'oflag=direct'* to dd, then you see something different, e.g. **74 MB/s**.
+| Believe me, you disk is not that fast either.
+| The OS didn't write in RAM, but hard disks have their own cache.  ???????????????  <==============================
+| In case of power loss, your data may get lost even after dd has finished writing!
+| To skip also hdd cache, use option *'oflag=sync'*.
+| Now you see something ugly like **15,6 MB/s**.
+| Here we have the two extremes: writing in ram and writing on the bare metal.
+
+Sheepdog Cache
+**************
+
+| We have analogous way to inform sheep daemon which cache to enable.
+| By default, it uses the safest way (sync).
+| This will "assure" data consistency even if all the hosts power off at the same time.
+
+| To enable disk cache usage (like in normal pc/server), you have to start Sheep with option **'-n'**.
+| This will increase your cluster writing speed.
+
+::
+
+    sheep -n /mnt/sheep/dsk01
+
+| By default, sheep uses "ram" cache for writing objects.
+| You can disable that by *-D*.
+| This option doesn't affect 'object cache'. (See next chapter).
+
+Sheepdog Object Cache
+*********************
+
+This kind of cache is relative to sheepdog only.
+As you know, sheepdog writes n copies for each object.
+Sheepdog consider a write operation done when all n copies has been written, then it elaborates the second request and so on.
+Using Object Cache, sheepdog will write data on a single disk of the host (where the guest is running) and will not wait for n copies to be written on the other nodes.
+It will do it later on.
+
+| Option *-w* will enable Object Cache.
+| You need to provide its size.
+| Optionally      ?????????  <===========   you can use *directio* to skip RAM cache (suggested if using ssd)
+
+
+::
+
+    sheep -w size=20000,directio /mnt/sheep/dsk01
+
+Considerations
+**************
+
+If you use option '-n':
+    * you may not gain so much from Object Cache.
+    * If a single host goes down, it's not a problem for the cluster / vdi consistency.
+    * You may loose latest written data in case of cluster power loss.
+
+If you use Object Cache:
+    * If the guest was writing data and the host get disconnected from the cluster, these data are on the cache of the off line node.
+      **You need to restart the guest on the same host to avoid losing the latest written data.**
+    * If you restart the guest on a different host, the latest data will be **missing**.
+    * If you restore the node that went off (and the guest is running on another one), absolutely ???????? <==============
+ **delete** the vdi cache **without** flushing it, ??????????? <=================
+or your vdi will get corrupted!
-- 
1.7.10.4