X-Git-Url: https://git.nihav.org/?a=blobdiff_plain;f=nihav-core%2Fsrc%2Frefs.rs;h=e4cde3a369f7c114c7d7d1daffb8de81f7bd8c7f;hb=5f031d75f99167db3aca5e0bb25c06c487deb236;hp=de1c4fc3b5f7809120bdce7b0e93a82105892287;hpb=e243ceb4d694cc08767ad70027bb6963f4cefea3;p=nihav.git

diff --git a/nihav-core/src/refs.rs b/nihav-core/src/refs.rs
index de1c4fc..e4cde3a 100644
--- a/nihav-core/src/refs.rs
+++ b/nihav-core/src/refs.rs
@@ -1,3 +1,24 @@
+//! Reference-counted buffer data type.
+//!
+//! NihAV requires some reference-counted type especially for frame buffer pools.
+//! `Arc` does not allow mutability with several references present, `RwLock` does not work reliably in a single thread mode (at least for me) so I ended up NIHing something.
+//!
+//! Currently it does not prevent code from reading the data that is being written to.
+//! Maybe in the future this will be replaced by something better and using more standard components.
+//!
+//! Also it contains `unsafe{}` so I should not write in Rust at all.
+//!
+//! # Examples
+//!
+//! ```
+//! use nihav_core::refs::NABufferRef;
+//!
+//! let vec = vec![42u8; 16];
+//! let vec_ref = NABufferRef::new(vec);
+//! let vec_ref2 = vec_ref.clone();
+//! let ref_count = vec_ref.get_num_refs(); // should be 2
+//! println!("vector element 4 is {}", vec_ref[4]); // should print the fourth vector element
+//! ```
 use std::ops::{Deref, DerefMut};
 use std::convert::AsRef;
 use std::sync::atomic::*;
@@ -18,7 +39,7 @@ impl<T> NABufferData<T> {
         obj.refs.fetch_add(1, Ordering::SeqCst);
     }
     fn dec_refs(obj: &mut Self) -> bool {
-        obj.refs.fetch_sub(1, Ordering::SeqCst) == 0
+        obj.refs.fetch_sub(1, Ordering::SeqCst) == 1
     }
     fn get_num_refs(obj: &Self) -> usize {
         obj.refs.load(Ordering::Relaxed)
@@ -31,21 +52,28 @@ impl<T> NABufferData<T> {
     }
 }
 
+/// Reference-counted buffer reference.
 pub struct NABufferRef<T> {
     ptr: *mut NABufferData<T>,
 }
 
+unsafe impl<T> Sync for NABufferRef<T> {}
+unsafe impl<T> Send for NABufferRef<T> {}
+
 impl<T> NABufferRef<T> {
+    /// Constructs a new instance of `NABufferRef`.
     pub fn new(val: T) -> Self {
         let bdata = NABufferData::new(val);
         let nbox: Box<_> = Box::new(bdata);
         Self { ptr: Box::into_raw(nbox) }
     }
+    /// Reports the number of references for the current instance.
     pub fn get_num_refs(&self) -> usize {
         unsafe {
             NABufferData::get_num_refs(self.ptr.as_mut().unwrap())
         }
     }
+    /// Returns a mutable pointer to the underlying data if possible.
     pub fn as_mut(&mut self) -> Option<&mut T> {
         unsafe {
             NABufferData::get_write_ptr(self.ptr.as_mut().unwrap())
@@ -83,7 +111,8 @@ impl<T> Drop for NABufferRef<T> {
     fn drop(&mut self) {
         unsafe {
             if NABufferData::dec_refs(self.ptr.as_mut().unwrap()) {
-                std::ptr::drop_in_place(self.ptr);
+                let data = Box::from_raw(self.ptr);
+                std::mem::drop(data);
             }
         }
     }