From 8c889da407e8f99469d68d6781fe7e1db5390813 Mon Sep 17 00:00:00 2001
From: ocelot-inc <pgulutzan@ocelot.ca>
Date: Sun, 17 Jan 2016 12:00:00 -0700
Subject: [PATCH] Fixes gh-902 Document snapshotting implementation in Data
persistence chapter
---
doc/sphinx/book/box/admin.rst | 12 ++++++++++--
doc/sphinx/book/box/index.rst | 23 ++++++++++-------------
2 files changed, 20 insertions(+), 15 deletions(-)
diff --git a/doc/sphinx/book/box/admin.rst b/doc/sphinx/book/box/admin.rst
index 6c34f90cba..746152dd74 100644
--- a/doc/sphinx/book/box/admin.rst
+++ b/doc/sphinx/book/box/admin.rst
@@ -14,15 +14,23 @@ A reference description also follows below:
preserve consistency of the primary key, used to iterate over tuples, a
copy-on-write technique is employed. If the master process changes part
of a primary key, the corresponding process page is split, and the snapshot
- process obtains an old copy of the page. Since a snapshot is written
+ process obtains an old copy of the page.
+ In effect, the snapshot process uses multi-version concurrency control
+ in order to avoid copying changes which are superseded while it is running.
+
+ Since a snapshot is written
sequentially, one can expect a very high write performance (averaging to
80MB/second on modern disks), which means an average database instance gets
- saved in a matter of minutes. Note, that as long as there are any changes to
+ saved in a matter of minutes. Note: as long as there are any changes to
the parent index memory through concurrent updates, there are going to be
page splits, and therefore one needs to have some extra free memory to run
this command. 10% of :confval:`slab_alloc_arena` is, on average, sufficient.
This statement waits until a snapshot is taken and returns operation result.
+ Although box.snapshot() does not cause a fork, there is a separate fiber
+ which may produce snapshots at regular intervals -- see the discussion of
+ the :ref:`snapshot daemon <book-cfg-snapshot_daemon>`.
+
**Example:**
.. code-block:: tarantoolsession
diff --git a/doc/sphinx/book/box/index.rst b/doc/sphinx/book/box/index.rst
index ab136f5831..a7092bf03a 100644
--- a/doc/sphinx/book/box/index.rst
+++ b/doc/sphinx/book/box/index.rst
@@ -371,23 +371,20 @@ and on the right are comments.
Hex dump of WAL file Comment
-------------------- -------
58 4c 4f 47 0a File header: "XLOG\n"
- 30 2e 31 32 0a 0a File header: "0.12\n\n" = version
- ... (not shown = inserted tuples for LSN and system spaces)
+ 30 2e 31 32 0a File header: "0.12\n" = version
+ ... (not shown = more header + tuples for system spaces)
d5 ba 0b ab Magic row marker always = 0xab0bbad5 if version 0.12
19 00 Length, not including length of header, = 25 bytes
ce 16 a4 38 6f Record header: previous crc32, current crc32,
a7 cc 73 7f 00 00 66 39
84 msgpack code meaning "Map of 4 elements" follows
- 00 02 02 01 the 4 elements, including 0x02 which is IPROTO_INSERT
- 03 04 04 additional information
- cb 41 d4 e2 2f 62 fd d5 d4 msgpack code meaning "Double" follows, for next 8 bytes
+ 00 02 element#1: tag=request type, value=0x02=IPROTO_INSERT
+ 02 01 element#2: tag=server id, value=0x01
+ 03 04 element#3: tag=lsn, value=0x04
+ 04 cb 41 d4 e2 2f 62 fd d5 d4 element#4: tag=timestamp, value=an 8-byte "Double"
82 msgpack code meaning "map of 2 elements" follows
- 10 IPROTO_SPACE_ID which is #defined as 16 (hex 10)
- cd msgpack code meaning 2-digit number follows
- 02 00 the id of "tester" which is 512, it's biggest byte first
- 21 Flags = IPROTO_TUPLE which is #defined as hex 21
- 91 msgpack code meaning "1-element fixed array" follows
- 01 Tuple: field[1] value = 1
+ 10 cd 02 00 element#1: tag=space id, value=512, big byte first
+ 21 91 01 element#2: tag=tuple, value=1-element fixed array={1}
Tarantool processes requests atomically: a change is either accepted and recorded
in the WAL, or discarded completely. Let's clarify how this happens, using the
@@ -395,7 +392,7 @@ REPLACE request as an example:
1. The server attempts to locate the original tuple by primary key. If found, a
reference to the tuple is retained for later use.
-2. The new tuple is then validated. If for example it does not contain an
+2. The new tuple is validated. If for example it does not contain an
indexed field, or it has an indexed field whose type does not match the type
according to the index definition, the change is aborted.
3. The new tuple replaces the old tuple in all existing indexes.
@@ -412,7 +409,7 @@ REPLACE request as an example:
One advantage of the described algorithm is that complete request pipelining is
achieved, even for requests on the same value of the primary key. As a result,
-database performance doesn't degrade even if all requests touch upon the same
+database performance doesn't degrade even if all requests refer to the same
key in the same space.
The transaction processor thread communicates with the WAL writer thread using
--
GitLab