/*!
\page	oess_1__snapshots	oess_1: Механизм snapshot-ов

\section oess_1__snapshots__intro	Введение

Trace-файлы в ObjESSty предназначены для двух основных целей: для восстановления
БД после сбоя и для предоставления возможности on-line репликации БД. В
последнем случае достаточно организовать репликацию trace-файлов с помощью
таких инструментов, как rsync или unison. Такая on-line репликация возможна,
т.к. trace-файлы являются append-only файлами (т.е. информация всегда
дописывается в конец файла и однажды записанная в trace-файл информация никогда
не изменяется), что позволяет считывать информацию из trace-файла в то время,
когда новая информация дописывается в конец trace-файла.

Однако, trace-файлы в ObjESSty обладают одним существенным недостатком --
они очень большие. Поэтому trace-файлы не выгодно использовать для создания
backup-копий БД. Вообщем-то можно хранить все trace-файлы от момента создания
БД и затем по ним восстанавливать БД. Но, во-первых, эта информация будет
иметь очень большой объем. И, во-вторых, будет требовать много времени на
восстановление значения БД.

Для преодоления указанных проблем ObjESSty поддерживает механизм snapshot-ов.
Snapshot -- это файл, который является точной копией основного файла БД на
некоторый момент времени. Особенность snapshot-ов в том, что они строятся
обратным воспроизведением trace-файлов, а не копированием основного файла
БД (который в этот момент может модифицироваться). При этом snapshot делает
не актуальными (не нужными, устаревшими) все trace-файлы, которые использовались
для построения snapshot-а. Поэтому при обратном воспроизведении trace-файлов
(для восстановления БД или создания очередного snapshot-а) автоматически
учитывается существование snapshot-ов и, если есть snapshot, то используется
именно он, а все trace-файлы, которые вошли в этот snapshot, игнорируются.

\section	oess_1__snapshots__numbering	Нумерация snapshot-ов

Snapshot-ы имеют имена \<db\>.\<XXXXXXXX\>.snapshot, где \a db -- это
физическое имя БД, а \a XXXXXXXX -- шестнадцатиричный номер snapshot-а.
Например: made_calls.00000001.snapshot, made_calls.0000000f.snapshot.

Номера snapshot-ов, так же, как номера trace-файлов имеют важное значение.
Как и у trace-файлов, номера snapshot-ов возрастают, но не обязательно
последовательно. Номер snapshot-а указывает, какие trace-файлы полностью
вошли в данный snapshot. Т.е., если snapshot имеет номер 4, то это означает,
что в snapshot вошли trace-файлы с номерами 1, 2, 3 и 4 (включительно).
Поэтому по номеру snapshot-а легко определить какие trace-файлы являются
устаревшими -- это все trace-файлы, чьи номера меньше или равны номеру
snapshot-а. Более того, snapshot с большим номером содержит в себе
все snapshot-ы с меньшими номерами.

\subsection oess_1__snapshots__numbering__actual_snapshot	Актуальный snapshot

При построении очередного snapshot-а в него автоматически включается содержимое
всех предыдущих snapshot-ов. Поэтому в ObjESSty существует понятие
\b актуального snapshot-а: это snapshot с максимальным номером. Именно он будет
использоваться при при последующем обратном воспроизведении (как для
восстановления БД, так и для создания нового snapshot-а). Все остальные
snapshot-ы с меньшими номерами т.о. являются не актуальными (устаревшими).
Соответственно, после формирования нового snapshot-а он становится новым
актуальным snapshot-ом, а предыдущий актуальный snapshot переходит в разряд
не актуальных.

\section oess_1__snapshot__used_trace Какие trace-файлы используются для построения snapshot-ов

Текущим trace-файлом является trace-файл с максимальным номером. Для
построения snapshot-a используются все trace-файлы, короме текущего и тех,
кто уже содержится в текущем актуальном snapshot-е. Например, если существует
только текущий trace-файл, то snapshot построен не будет. Если существует
текущий trace-файл и несколько предшествующих ему trace-файлов, то для
построения snapshot-а будут использоваться все предшествующие текущему
trace-файлы. Если кроме текущего trace-файла и предшестующих ему trace-файлов
есть актуальный snapshot, то для построения нового актуального snapshot-а
будут использоваться trace-файлы с номерами от Ns+1 (где Ns -- это номер
актуального snapshot-а) до Nt-1 (где Nt -- это номер текущего trace-файла).
Если же Ns+1==Nt, то snapshot не может быть построен.

\section oess_1__snapshot__building	Построение snapshot-ов

Для построения snapshot-а используется утилита oess_trace_replay с указанным
ключем --snapshot. Например, для того, чтобы построить новый актуальный
snapshot-файл для БД \c db/made_calls нужно дать команду:
\verbatim
oess_trace_replay --db db/made_calls --snapshot
\endverbatim
Будет создан новый актуальный snapshot (если это возможно), но не будет
удалено ни одного trace-файла или snapshot-а. Для того, чтобы сразу удалить
все неактульные trace-файлы и snapshot-ы нужно указать ключ --remove-unused:
\verbatim
oess_trace_replay --db db/made_calls --snapshot --remove-unused
\endverbatim
*/
