src/backup.rs: add documentation about ChunkStore locking

[proxmox-backup.git] / src / backup.rs

diff --git a/src/backup.rs b/src/backup.rs
index 27a3fd284ba96a38e6fda431ed3c2289d1bd7acc..cb9fabf7d744fbfea32dcf58efc1827dd5743013 100644 (file)
--- a/src/backup.rs
+++ b/src/backup.rs
@@ -10,6 +10,49 @@
 //! `DynamicIndex*` format is able to deal with dynamic chunk sizes,
 //! whereas the `FixedIndex*` format is an optimization to store a
 //! list of equal sized chunks.
+//!
+//! # ChunkStore Locking
+//!
+//! We need to be able to restart the proxmox-backup service daemons,
+//! so that we can update the software without rebooting the host. But
+//! such restarts must not abort running backup jobs, so we need to
+//! keep the old service running until those jobs are finished. This
+//! implies that we need some kink of locking for the
+//! ChunkStore. Please note that it is perfectly valid to have
+//! multiple parallel ChunkStore writers, even when they write the
+//! same chunk (because the chunk would have the same name and the
+//! same data). The only real problem is garbage collection, because
+//! we need to avoid deleting chunks which are still referenced.
+//!
+//! * Read Index Files:
+//!
+//!   Acquire shared lock for .idx files.
+//!
+//!
+//! * Delete Index Files:
+//!
+//!   Acquire exclusive lock for .idx files. This makes sure that we do
+//!   not delete index files while they are still in use.
+//!
+//!
+//! * Create Index Files:
+//!
+//!   Acquire shared lock for ChunkStore.
+//!
+//!   Note: We create temporary (.tmp) file, then do an atomic rename ...
+//!
+//!
+//! * Garbage Collect:
+//!
+//!   Acquire exclusive lock for ChunkStore.
+//!
+//!
+//! * Server Restart
+//!
+//!   Try to abort running garbage collection to release exclusive
+//!   ChunkStore lock asap. Start new service with existing listening
+//!   socket.
+//!
 
 mod chunk_stat;
 pub use chunk_stat::*;