Document file close degree

Author: mulimoen

src/handle.rs

@@ -54,15 +54,17 @@ impl Handle {
         self.id
     }
 
+    /// Increment the reference count of the handle
     pub fn incref(&self) {
         if is_valid_user_id(self.id()) {
             h5lock!(H5Iinc_ref(self.id()));
         }
     }
 
-    /// An object should not be decreffed unless it has an
-    /// associated incref
-    pub unsafe fn decref(&self) {
+    /// Decrease the reference count of the handle
+    ///
+    /// This function should only be used if `incref` has been used
+    pub fn decref(&self) {
         h5lock!({
             if self.is_valid_id() {
                 H5Idec_ref(self.id());
@@ -80,7 +82,8 @@ impl Handle {
         is_valid_id(self.id())
     }
 
-    pub(crate) fn refcount(&self) -> u32 {
+    /// Return the reference count of the object
+    pub fn refcount(&self) -> u32 {
         refcount(self.id).unwrap_or(0) as u32
     }
 }

src/hl/object.rs

@@ -99,7 +99,7 @@ pub mod tests {
         }
 
         fn decref(&self) {
-            unsafe { self.0.decref() }
+            self.0.decref()
         }
     }
 
@@ -164,11 +164,19 @@ pub mod tests {
         // We can now take, as we have exactly two handles
         let obj2 = unsafe { std::mem::ManuallyDrop::take(&mut obj2) };
 
-        obj.decref();
         h5lock!({
+            // We must hold a lock here to prevent another thread creating an object
+            // with the same identifier as the one we just owned. Failing to do this
+            // might lead to the wrong object being dropped.
+            obj.decref();
             obj.decref();
+            // We here have to dangling identifiers stored in obj and obj2. As this part
+            // is locked we know some other object is not going to created with these
+            // identifiers
             assert!(!obj.is_valid());
             assert!(!obj2.is_valid());
+            // By manually dropping we don't close some other unrelated objects.
+            // Dropping/closing an invalid object is allowed
             drop(obj);
             drop(obj2);
         });

src/hl/plist/file_access.rs

@@ -1026,6 +1026,11 @@ impl FileAccessBuilder {
         Ok(builder)
     }
 
+    /// Sets the file close degree
+    ///
+    /// If called with `FileCloseDegree::Strong`, the programmer is responsible
+    /// for closing all items before closing the file. Failure to do so might
+    /// invalidate newly created objects.
     pub fn fclose_degree(&mut self, fc_degree: FileCloseDegree) -> &mut Self {
         self.fclose_degree = Some(fc_degree);
         self
@@ -1374,6 +1379,8 @@ impl FileAccessBuilder {
         if let Some(v) = self.chunk_cache {
             h5try!(H5Pset_cache(id, 0, v.nslots as _, v.nbytes as _, v.w0 as _));
         }
+        // The default is to use CLOSE_SEMI or CLOSE_WEAK, depending on VFL driver.
+        // Both of these are unproblematic for our ownership
         if let Some(v) = self.fclose_degree {
             h5try!(H5Pset_fclose_degree(id, v.into()));
         }