Polish shared buffers

This documents their purpose and in the process modifies the signature
of `ptr_eq` to check if images of different layouts share an underlying
buffer. Previously you'd have to discover they all can decay to `Bytes`
layout and clone when they are held by reference.

Author: 197g

texel/src/buf.rs

@@ -1443,6 +1443,34 @@ impl<P> Clone for AtomicSliceRef<'_, P> {
 
 impl<P> Copy for AtomicSliceRef<'_, P> {}
 
+impl<P> AtomicRef<'_, P> {
+    /// Modify the value stored in the reference.
+    ///
+    /// Note that this does *not* promise to be atomic in the whole value, just that it atomically
+    /// modifies the underlying buffer elements. The bytes of the value may be torn if another
+    /// write happens concurrently to the same element.
+    ///
+    /// However, it is guaranteed that the contents of any other non-aliased value in the buffer is
+    /// not modified even if they share the same atomic unit.
+    pub fn store(self, value: P) {
+        self.texel.store_atomic(self, value);
+    }
+
+    /// Retrieve a value stored in the reference.
+    ///
+    /// Note that this does *not* promise to be atomic in the whole value, just that it atomically
+    /// reads from the underlying buffer. The bytes of the value may be torn if another write
+    /// happens concurrently to the same element.
+    ///
+    /// If no such write occurs concurrently, when all writes are ordered-before or ordered-after
+    /// this load then the value is correct. This needs only hold to writes accessing the bytes
+    /// making up _this value_. Even if another values shares atomic units with this value their
+    /// writes are guaranteed to never modify the bits of this value.
+    pub fn load(self) -> P {
+        self.texel.load_atomic(self)
+    }
+}
+
 impl<P> Clone for AtomicRef<'_, P> {
     fn clone(&self) -> Self {
         AtomicRef { ..*self }

texel/src/image/atomic.rs

@@ -23,6 +23,24 @@ use crate::{BufferReuseError, Texel, TexelBuffer};
 /// on other threads. While the implementation prevents any unsound *data races* there is no
 /// specific meaning to any of its outcomes unless the caller ensure synchronization in some other
 /// manner.
+///
+/// # Examples
+///
+/// As a type with shared ownership over the underling buffer, this type can be cloned very
+/// cheaply. Such duplicates refer to the same buffer, making changes in one visible to the other.
+///
+/// ```
+/// use image_texel::{image::AtomicImage, layout::Matrix};
+/// let matrix = Matrix::<u8>::width_and_height(400, 400).unwrap();
+/// let image: AtomicImage<_> = AtomicImage::new(matrix);
+///
+/// let another_reference = image.clone();
+/// assert!(AtomicImage::ptr_eq(&image, &another_reference));
+///
+/// another_reference.as_slice().index_one(0).store(0xff);
+/// let value = image.as_slice().index_one(0).load();
+/// assert_eq!(value, 0xff);
+/// ```
 #[derive(Clone)]
 pub struct AtomicImage<Layout = Bytes> {
     pub(super) inner: RawImage<AtomicBuffer, Layout>,
@@ -227,7 +245,10 @@ impl<L> AtomicImage<L> {
     }
 
     /// Check if two images refer to the same buffer.
-    pub fn ptr_eq(&self, other: &Self) -> bool {
+    ///
+    /// Note that two buffers can use different layout types to describe their share of the data or
+    /// even to refer to the same data in different ways.
+    pub fn ptr_eq<O>(&self, other: &AtomicImage<O>) -> bool {
         AtomicBuffer::ptr_eq(self.inner.get(), other.inner.get())
     }
 

texel/src/image/cell.rs

@@ -13,6 +13,24 @@ use core::cell::Cell;
 /// This is a unsynchronized, shared equivalent to [`Image`][`crate::image::Image`]. That is the
 /// buffer of bytes of this container is shared between clones of this value but can not be sent
 /// between threads. In particular the same buffer may be owned and viewed with different layouts.
+///
+/// # Examples
+///
+/// As a type with shared ownership over the underling buffer, this type can be cloned very
+/// cheaply. Such duplicates refer to the same buffer, making changes in one visible to the other.
+///
+/// ```
+/// use image_texel::{image::CellImage, layout::Matrix};
+/// let matrix = Matrix::<u8>::width_and_height(400, 400).unwrap();
+/// let image: CellImage<_> = CellImage::new(matrix);
+///
+/// let another_reference = image.clone();
+/// assert!(CellImage::ptr_eq(&image, &another_reference));
+///
+/// another_reference.as_slice().as_slice_of_cells()[0].set(0xff);
+/// let value = image.as_slice().as_slice_of_cells()[0].get();
+/// assert_eq!(value, 0xff);
+/// ```
 #[derive(Clone, PartialEq, Eq)]
 pub struct CellImage<Layout = Bytes> {
     pub(super) inner: RawImage<CellBuffer, Layout>,
@@ -219,7 +237,10 @@ impl<L> CellImage<L> {
     }
 
     /// Check if two images refer to the same buffer.
-    pub fn ptr_eq(&self, other: &Self) -> bool {
+    ///
+    /// Note that two buffers can use different layout types to describe their share of the data or
+    /// even to refer to the same data in different ways.
+    pub fn ptr_eq<O>(&self, other: &CellImage<O>) -> bool {
         CellBuffer::ptr_eq(self.inner.get(), other.inner.get())
     }