add more docs for transactional methods, #67 and #71

Author: burmecia

src/file.rs

@@ -11,7 +11,7 @@ use trans::{TxHandle, TxMgr};
 
 /// A reader for a specific vesion of file content.
 ///
-/// This reader can be obtained by [`version_reader`] function, and it
+/// This reader can be obtained by [`version_reader`] method, and it
 /// implements [`Read`] trait.
 ///
 /// [`version_reader`]: struct.File.html#method.version_reader
@@ -130,7 +130,7 @@ impl Seek for VersionReader {
 /// File content is cached internally for deduplication and will be handled
 /// automatically, thus calling [`flush`] is **not** recommended.
 ///
-/// `File` can be sent to multiple threads, but only thread can modify it at
+/// `File` can be sent to multiple threads, but only one thread can modify it at
 /// a time, which is similar to a `RwLock`.
 ///
 /// `File` is multi-versioned, each time updating its content will create a new
@@ -143,9 +143,10 @@ impl Seek for VersionReader {
 ///   version. Unless [`finish`] was successfully returned, no data will be
 ///   written to the file.
 ///
-///   Internally, a transaction is created when writing to the file and calling
-///   [`finish`] will commit that transaction. Thus, you should not call
-///   [`finish`] in case of any writing failure.
+///   Internally, a transaction is created when writing to the file first time
+///   and calling [`finish`] will commit that transaction. If any errors
+///   happened during [`write`], that transaction will be aborted. Thus, you
+///   should not call [`finish`] after any failed [`write`].
 ///
 ///   ## Examples
 ///
@@ -207,6 +208,20 @@ impl Seek for VersionReader {
 ///   # foo().unwrap();
 ///   ```
 ///
+/// To gurantee atomicity, ZboxFS uses transaction when updating file so the
+/// data either be wholly persisted or nothing has been written.
+///
+/// - For multi-part write, the transaction begins in the first-time [`write`]
+///   and will be committed in [`finish`]. Any failure in [`write`] will abort
+///   the transaction, thus [`finish`] should not be called after that. If error
+///   happened during [`finish`], the transaction will also be aborted.
+/// - For single-part write, [`write_once`] itself is transactional. The
+///   transaction begins and will be committed inside this method.
+///
+/// Keep in mind of those characteristics, especially when writing a large
+/// amount of data to file, because any uncomitted transactions will abort
+/// and data in those transactions won't be persisted.
+///
 /// # Reading
 ///
 /// As `File` can contain multiple versions, [`Read`] operation can be
@@ -450,11 +465,16 @@ impl File {
 
     /// Complete multi-part write to file and create a new version.
     ///
+    /// This method will try to commit the transaction internally, no data will
+    /// be persisted if it failed. Do not call this method if any previous
+    /// [`write`] failed.
+    ///
     /// # Errors
     ///
-    /// Calling this function without writing data before will return
+    /// Calling this method without writing data before will return
     /// [`Error::NotWrite`] error.
     ///
+    /// [`Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
     /// [`Error::NotWrite`]: enum.Error.html
     pub fn finish(&mut self) -> Result<()> {
         self.check_closed()?;
@@ -486,9 +506,11 @@ impl File {
 
     /// Single-part write to file and create a new version.
     ///
-    /// This function provides a convenient way of combining [`Write`] and
+    /// This method provides a convenient way of combining [`Write`] and
     /// [`finish`].
     ///
+    /// This method is atomic.
+    ///
     /// [`Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
     /// [`finish`]: struct.File.html#method.finish
     pub fn write_once(&mut self, buf: &[u8]) -> Result<()> {
@@ -522,10 +544,12 @@ impl File {
     /// then the content will be extended to `size` and have all of the
     /// intermediate data filled in with 0s.
     ///
+    /// This method is atomic.
+    ///
     /// # Errors
     ///
-    /// This function will return an error if the file is not opened for
-    /// writing or not finished writing.
+    /// This method will return an error if the file is not opened for writing
+    /// or not finished writing.
     pub fn set_len(&mut self, len: usize) -> Result<()> {
         self.check_closed()?;
         if self.wtr.is_some() {

src/repo.rs

@@ -801,12 +801,13 @@ impl Repo {
     /// Create a file in read-write mode.
     ///
     /// This method will create a file if it does not exist, and will
-    /// truncate it if it does.
-    ///
-    /// See the [`OpenOptions::open`](struct.OpenOptions.html#method.open)
-    /// method for more details.
+    /// truncate it if it does. See the
+    /// [`OpenOptions::open`](struct.OpenOptions.html#method.open) method for
+    /// more details.
     ///
     /// `path` must be an absolute path.
+    ///
+    /// This method is **not** atomic.
     #[inline]
     pub fn create_file<P: AsRef<Path>>(&mut self, path: P) -> Result<File> {
         OpenOptions::new()
@@ -849,6 +850,8 @@ impl Repo {
     /// Creates a new, empty directory at the specified path.
     ///
     /// `path` must be an absolute path.
+    ///
+    /// This method is atomic.
     #[inline]
     pub fn create_dir<P: AsRef<Path>>(&mut self, path: P) -> Result<()> {
         self.fs
@@ -860,6 +863,9 @@ impl Repo {
     /// are missing.
     ///
     /// `path` must be an absolute path.
+    ///
+    /// This method is **not** atomic in whole, but creating each entry is
+    /// atomic.
     #[inline]
     pub fn create_dir_all<P: AsRef<Path>>(&mut self, path: P) -> Result<()> {
         self.fs.create_dir_all(path.as_ref())
@@ -896,6 +902,8 @@ impl Repo {
     /// `from` and `to` must be absolute paths to regular files.
     ///
     /// If `from` and `to` both point to the same file, this method is no-op.
+    ///
+    /// This method is **not** atomic.
     #[inline]
     pub fn copy<P: AsRef<Path>, Q: AsRef<Path>>(
         &mut self,
@@ -919,6 +927,8 @@ impl Repo {
     ///
     /// If `from` and `to` both point to the same directory, this method is
     /// no-op.
+    ///
+    /// This method is **not** atomic.
     #[inline]
     pub fn copy_dir_all<P: AsRef<Path>, Q: AsRef<Path>>(
         &mut self,
@@ -931,6 +941,8 @@ impl Repo {
     /// Removes a regular file from the repository.
     ///
     /// `path` must be an absolute path.
+    ///
+    /// This method is atomic.
     #[inline]
     pub fn remove_file<P: AsRef<Path>>(&mut self, path: P) -> Result<()> {
         self.fs.remove_file(path.as_ref())
@@ -939,6 +951,8 @@ impl Repo {
     /// Remove an existing empty directory.
     ///
     /// `path` must be an absolute path.
+    ///
+    /// This method is atomic.
     #[inline]
     pub fn remove_dir<P: AsRef<Path>>(&mut self, path: P) -> Result<()> {
         self.fs.remove_dir(path.as_ref())
@@ -948,6 +962,9 @@ impl Repo {
     /// Use carefully!
     ///
     /// `path` must be an absolute path.
+    ///
+    /// This method is **not** atomic in whole, but removing each entry is
+    /// atomic.
     #[inline]
     pub fn remove_dir_all<P: AsRef<Path>>(&mut self, path: P) -> Result<()> {
         self.fs.remove_dir_all(path.as_ref())
@@ -957,6 +974,8 @@ impl Repo {
     /// if `to` already exists.
     ///
     /// `from` and `to` must be absolute paths.
+    ///
+    /// This method is atomic.
     #[inline]
     pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(
         &mut self,