deprecate GuestMemory::try_access()

Deprecate 'GuestMemory::try_access()` in favor of the external iterator
provided by `GuestMemory::get_slices()`. Rewrite all internal usages of
`try_access()` in terms of `get_slices()`.

Signed-off-by: Patrick Roy <[email protected]>

Author: roypat

CHANGELOG.md

@@ -39,6 +39,10 @@
 
 - \[[#339](https://github.com/rust-vmm/vm-memory/pull/339)\] Fix `Bytes::read()` and `Bytes::write()` not to ignore `try_access()`'s `count` parameter
 
+### Deprecated
+
+- \[[#349](https://github.com/rust-vmm/vm-memory/pull/349)\] Deprecate `GuestMemory::try_access()`. Use `GuestMemory::get_slices()` instead.
+
 ## \[v0.16.1\]
 
 ### Added

src/bitmap/mod.rs

@@ -288,16 +288,10 @@ pub(crate) mod tests {
 
         // Finally, let's invoke the generic tests for `Bytes`.
         let check_range_closure = |m: &M, start: usize, len: usize, clean: bool| -> bool {
-            let mut check_result = true;
-            m.try_access(len, GuestAddress(start as u64), |_, size, reg_addr, reg| {
-                if !check_range(&reg.bitmap(), reg_addr.0 as usize, size, clean) {
-                    check_result = false;
-                }
-                Ok(size)
+            m.get_slices(GuestAddress(start as u64), len).all(|r| {
+                let slice = r.unwrap();
+                check_range(slice.bitmap(), 0, slice.len(), clean)
             })
-            .unwrap();
-
-            check_result
         };
 
         test_bytes(

src/guest_memory.rs

@@ -355,10 +355,10 @@ pub trait GuestMemory {
 
     /// Check whether the range [base, base + len) is valid.
     fn check_range(&self, base: GuestAddress, len: usize) -> bool {
-        match self.try_access(len, base, |_, count, _, _| -> Result<usize> { Ok(count) }) {
-            Ok(count) => count == len,
-            _ => false,
-        }
+        self.get_slices(base, len)
+            .map(|r| r.map(|slice| slice.len()).unwrap_or(0))
+            .sum::<usize>()
+            == len
     }
 
     /// Returns the address plus the offset if it is present within the memory of the guest.
@@ -376,6 +376,10 @@ pub trait GuestMemory {
     /// - the error code returned by the callback 'f'
     /// - the size of the already handled data when encountering the first hole
     /// - the size of the already handled data when the whole range has been handled
+    #[deprecated(
+        since = "0.17.0",
+        note = "supplemented by external iterator `get_slices()`"
+    )]
     fn try_access<F>(&self, count: usize, addr: GuestAddress, mut f: F) -> Result<usize>
     where
         F: FnMut(usize, usize, MemoryRegionAddress, &Self::R) -> Result<usize>,
@@ -527,6 +531,14 @@ impl<'a, M: GuestMemory + ?Sized> GuestMemorySliceIterator<'a, M> {
 
         Some(region.get_slice(start, len as usize))
     }
+
+    /// Adapts this [`GuestMemorySliceIterator`] to return `None` (e.g. gracefully terminate)
+    /// instead of `Err(Error::InvalidGuestAddress)` when iteration hits an invalid [`GuestAddress`].
+    pub fn partial(self) -> impl Iterator<Item = Result<VolatileSlice<'a, MS<'a, M>>>> {
+        self.enumerate()
+            .filter(|(i, r)| !(*i > 0 && matches!(r, Err(Error::InvalidGuestAddress(_)))))
+            .map(|(_, r)| r)
+    }
 }
 
 impl<'a, M: GuestMemory + ?Sized> Iterator for GuestMemorySliceIterator<'a, M> {
@@ -556,23 +568,15 @@ impl<T: GuestMemory + ?Sized> Bytes<GuestAddress> for T {
     type E = Error;
 
     fn write(&self, buf: &[u8], addr: GuestAddress) -> Result<usize> {
-        self.try_access(
-            buf.len(),
-            addr,
-            |offset, count, caddr, region| -> Result<usize> {
-                region.write(&buf[offset..(offset + count)], caddr)
-            },
-        )
+        self.get_slices(addr, buf.len())
+            .partial()
+            .try_fold(0, |acc, slice| Ok(acc + slice?.write(&buf[acc..], 0)?))
     }
 
     fn read(&self, buf: &mut [u8], addr: GuestAddress) -> Result<usize> {
-        self.try_access(
-            buf.len(),
-            addr,
-            |offset, count, caddr, region| -> Result<usize> {
-                region.read(&mut buf[offset..(offset + count)], caddr)
-            },
-        )
+        self.get_slices(addr, buf.len())
+            .partial()
+            .try_fold(0, |acc, slice| Ok(acc + slice?.read(&mut buf[acc..], 0)?))
     }
 
     /// # Examples
@@ -636,9 +640,12 @@ impl<T: GuestMemory + ?Sized> Bytes<GuestAddress> for T {
     where
         F: ReadVolatile,
     {
-        self.try_access(count, addr, |_, len, caddr, region| -> Result<usize> {
-            region.read_volatile_from(caddr, src, len)
-        })
+        self.get_slices(addr, count)
+            .partial()
+            .try_fold(0, |acc, r| {
+                let slice = r?;
+                Ok(acc + slice.read_volatile_from(0, src, slice.len())?)
+            })
     }
 
     fn read_exact_volatile_from<F>(
@@ -664,11 +671,15 @@ impl<T: GuestMemory + ?Sized> Bytes<GuestAddress> for T {
     where
         F: WriteVolatile,
     {
-        self.try_access(count, addr, |_, len, caddr, region| -> Result<usize> {
-            // For a non-RAM region, reading could have side effects, so we
-            // must use write_all().
-            region.write_all_volatile_to(caddr, dst, len).map(|()| len)
-        })
+        self.get_slices(addr, count)
+            .partial()
+            .try_fold(0, |acc, r| {
+                let slice = r?;
+                // For a non-RAM region, reading could have side effects, so we
+                // must use write_all().
+                slice.write_all_volatile_to(0, dst, slice.len())?;
+                Ok(acc + slice.len())
+            })
     }
 
     fn write_all_volatile_to<F>(&self, addr: GuestAddress, dst: &mut F, count: usize) -> Result<()>