Deprecate GuestMemory stopgap "iterator" methods

* Deprecates `with_regions` `with_regions_mut` and `map_and_fold`.
* Update unit tests

Signed-off-by: defunct <[email protected]>

Resolves #133

Author: defunctio

CHANGELOG.md

@@ -1,4 +1,10 @@
 # Changelog
+## [Unreleased]
+
+### Deprecated 
+
+  - [[#133]](https://github.com/rust-vmm/vm-memory/issues/8): Deprecate `GuestMemory::with_regions()`,
+   `GuestMemory::with_regions_mut()`, `GuestMemory::map_and_fold()`
 
 ## [v0.5.0]
 

coverage_config_x86_64.json

@@ -1,5 +1,5 @@
 {
-  "coverage_score": 85.6,
+  "coverage_score": 85.4,
   "exclude_path": "mmap_windows.rs",
   "crate_features": "backend-mmap,backend-atomic"
 }

src/atomic.rs

@@ -143,8 +143,8 @@ impl<M: GuestMemory> GuestMemoryExclusiveGuard<'_, M> {
 mod tests {
     use super::*;
     use crate::{
-        GuestAddress, GuestMemory, GuestMemoryMmap, GuestMemoryRegion, GuestMemoryResult,
-        GuestRegionMmap, GuestUsize, MmapRegion,
+        GuestAddress, GuestMemory, GuestMemoryMmap, GuestMemoryRegion, GuestRegionMmap, GuestUsize,
+        MmapRegion,
     };
 
     type GuestMemoryMmapAtomic = GuestMemoryAtomic<GuestMemoryMmap>;
@@ -161,16 +161,13 @@ mod tests {
         let gm = GuestMemoryMmapAtomic::new(gmm);
         let mem = gm.memory();
 
-        let res: GuestMemoryResult<()> = mem.with_regions(|_, region| {
+        for region in mem.iter() {
             assert_eq!(region.len(), region_size as GuestUsize);
-            Ok(())
-        });
-        assert!(res.is_ok());
-        let res: GuestMemoryResult<()> = mem.with_regions_mut(|_, region| {
+        }
+
+        for region in mem.iter() {
             iterated_regions.push((region.start_addr(), region.len() as usize));
-            Ok(())
-        });
-        assert!(res.is_ok());
+        }
         assert_eq!(regions, iterated_regions);
         assert_eq!(mem.num_regions(), 2);
         assert!(mem.find_region(GuestAddress(0x1000)).is_some());
@@ -182,13 +179,9 @@ mod tests {
             .eq(iterated_regions.iter().copied()));
 
         let mem2 = mem.into_inner();
-        let res: GuestMemoryResult<()> = mem2.with_regions(|_, region| {
+        for region in mem2.iter() {
             assert_eq!(region.len(), region_size as GuestUsize);
-            Ok(())
-        });
-        assert!(res.is_ok());
-        let res: GuestMemoryResult<()> = mem2.with_regions_mut(|_, _| Ok(()));
-        assert!(res.is_ok());
+        }
         assert_eq!(mem2.num_regions(), 2);
         assert!(mem2.find_region(GuestAddress(0x1000)).is_some());
         assert!(mem2.find_region(GuestAddress(0x10000)).is_none());
@@ -199,13 +192,9 @@ mod tests {
             .eq(iterated_regions.iter().copied()));
 
         let mem3 = mem2.memory();
-        let res: GuestMemoryResult<()> = mem3.with_regions(|_, region| {
+        for region in mem3.iter() {
             assert_eq!(region.len(), region_size as GuestUsize);
-            Ok(())
-        });
-        assert!(res.is_ok());
-        let res: GuestMemoryResult<()> = mem3.with_regions_mut(|_, _| Ok(()));
-        assert!(res.is_ok());
+        }
         assert_eq!(mem3.num_regions(), 2);
         assert!(mem3.find_region(GuestAddress(0x1000)).is_some());
         assert!(mem3.find_region(GuestAddress(0x10000)).is_none());

src/guest_memory.rs

@@ -473,6 +473,7 @@ pub trait GuestMemory {
     /// Perform the specified action on each region.
     ///
     /// It only walks children of current region and does not step into sub regions.
+    #[deprecated(since = "0.6.0", note = "Use `.iter()` instead")]
     fn with_regions<F, E>(&self, cb: F) -> std::result::Result<(), E>
     where
         F: Fn(usize, &Self::R) -> std::result::Result<(), E>,
@@ -486,6 +487,7 @@ pub trait GuestMemory {
     /// Perform the specified action on each region mutably.
     ///
     /// It only walks children of current region and does not step into sub regions.
+    #[deprecated(since = "0.6.0", note = "Use `.iter()` instead")]
     fn with_regions_mut<F, E>(&self, mut cb: F) -> std::result::Result<(), E>
     where
         F: FnMut(usize, &Self::R) -> std::result::Result<(), E>,
@@ -554,6 +556,7 @@ pub trait GuestMemory {
     /// assert_eq!(3, total_size)
     /// # }
     /// ```
+    #[deprecated(since = "0.6.0", note = "Use `.iter()` instead")]
     fn map_and_fold<F, G, T>(&self, init: T, mapf: F, foldf: G) -> T
     where
         F: Fn((usize, &Self::R)) -> T,

src/mmap.rs

@@ -1196,16 +1196,14 @@ mod tests {
         ];
         let mut iterated_regions = Vec::new();
         let gm = GuestMemoryMmap::from_ranges(&regions).unwrap();
-        let res: guest_memory::Result<()> = gm.with_regions(|_, region| {
+
+        for region in gm.iter() {
             assert_eq!(region.len(), region_size as GuestUsize);
-            Ok(())
-        });
-        assert!(res.is_ok());
-        let res: guest_memory::Result<()> = gm.with_regions_mut(|_, region| {
+        }
+
+        for region in gm.iter() {
             iterated_regions.push((region.start_addr(), region.len() as usize));
-            Ok(())
-        });
-        assert!(res.is_ok());
+        }
         assert_eq!(regions, iterated_regions);
 
         assert!(regions
@@ -1228,16 +1226,13 @@ mod tests {
         let gm = Arc::new(GuestMemoryMmap::from_ranges(&regions).unwrap());
         let mem = gm.memory();
 
-        let res: guest_memory::Result<()> = mem.with_regions(|_, region| {
+        for region in mem.iter() {
             assert_eq!(region.len(), region_size as GuestUsize);
-            Ok(())
-        });
-        assert!(res.is_ok());
-        let res: guest_memory::Result<()> = mem.with_regions_mut(|_, region| {
+        }
+
+        for region in mem.iter() {
             iterated_regions.push((region.start_addr(), region.len() as usize));
-            Ok(())
-        });
-        assert!(res.is_ok());
+        }
         assert_eq!(regions, iterated_regions);
 
         assert!(regions