Fix formatting and broken links in documentation (#577)

k-sareen · web-flow · commit ce82a7d9a5a1 · 2022-04-29T14:00:00.000+12:00
diff --git a/src/util/alloc/allocator.rs b/src/util/alloc/allocator.rs
@@ -118,7 +118,7 @@ pub trait Allocator<VM: VMBinding>: Downcast {
     /// Return the [`VMThread`] associated with this allocator instance.
     fn get_tls(&self) -> VMThread;
 
-    /// Return the [`Space`] instance associated with this allocator instance.
+    /// Return the [`Space`](src/policy/space/Space) instance associated with this allocator instance.
     fn get_space(&self) -> &'static dyn Space<VM>;
 
     /// Return the [`Plan`] instance that this allocator instance is associated with.
@@ -129,9 +129,9 @@ pub trait Allocator<VM: VMBinding>: Downcast {
     fn does_thread_local_allocation(&self) -> bool;
 
     /// Return at which granularity the allocator acquires memory from the global space and use
-    /// them as thread local buffer. For example, the [`BumpAllocator`] acquires memory at 32KB
+    /// them as thread local buffer. For example, the [`BumpAllocator`](crate::util::alloc::BumpAllocator) acquires memory at 32KB
     /// blocks. Depending on the actual size for the current object, they always acquire memory of
-    /// N*32KB (N>=1). Thus the [`BumpAllocator`] returns 32KB for this method.  Only allocators
+    /// N*32KB (N>=1). Thus the [`BumpAllocator`](crate::util::alloc::BumpAllocator) returns 32KB for this method.  Only allocators
     /// that do thread local allocation need to implement this method.
     fn get_thread_local_buffer_granularity(&self) -> usize {
         assert!(self.does_thread_local_allocation(), "An allocator that does not thread local allocation does not have a buffer granularity.");
@@ -140,15 +140,15 @@ pub trait Allocator<VM: VMBinding>: Downcast {
 
     /// An allocation attempt. The implementation of this function depends on the allocator used.
     /// If an allocator supports thread local allocations, then the allocation will be serviced
-    /// from its TLAB, otherwise it will default to using the slowpath, i.e. [`alloc_slow`].
+    /// from its TLAB, otherwise it will default to using the slowpath, i.e. [`alloc_slow`](Allocator::alloc_slow).
     ///
     /// Note that in the case where the VM is out of memory, we invoke
     /// [`Collection::out_of_memory`] to inform the binding and then return a null pointer back to
     /// it. We have no assumptions on whether the VM will continue executing or abort immediately.
     ///
     /// An allocator needs to make sure the object reference for the returned address is in the same
     /// chunk as the returned address (so the side metadata and the SFT for an object reference is valid).
-    /// See [`crate::util::alloc::object_ref_guard`].
+    /// See [`crate::util::alloc::object_ref_guard`](util/alloc/object_ref_guard).
     ///
     /// Arguments:
     /// * `size`: the allocation size in bytes.
@@ -170,9 +170,9 @@ pub trait Allocator<VM: VMBinding>: Downcast {
 
     /// Slowpath allocation attempt. This function executes the actual slowpath allocation.  A
     /// slowpath allocation in MMTk attempts to allocate the object using the per-allocator
-    /// definition of [`alloc_slow_once`]. This function also accounts for increasing the
+    /// definition of [`alloc_slow_once`](Allocator::alloc_slow_once). This function also accounts for increasing the
     /// allocation bytes in order to support stress testing. In case precise stress testing is
-    /// being used, the [`alloc_slow_once_precise_stress`] function is used instead.
+    /// being used, the [`alloc_slow_once_precise_stress`](Allocator::alloc_slow_once_precise_stress) function is used instead.
     ///
     /// Note that in the case where the VM is out of memory, we invoke
     /// [`Collection::out_of_memory`] with a [`AllocationError::HeapOutOfMemory`] error to inform
@@ -194,6 +194,7 @@ pub trait Allocator<VM: VMBinding>: Downcast {
         // Information about the previous collection.
         let mut emergency_collection = false;
         let mut previous_result_zero = false;
+
         loop {
             // Try to allocate using the slow path
             let result = if is_mutator && stress_test && plan.is_precise_stress() {
@@ -224,13 +225,7 @@ pub trait Allocator<VM: VMBinding>: Downcast {
                     plan.allocation_success.store(true, Ordering::SeqCst);
                 }
 
-                // When a GC occurs, the resultant address provided by `acquire()` is 0x0.
-                // Hence, another iteration of this loop occurs. In such a case, the second
-                // iteration tries to allocate again, and if is successful, then the allocation
-                // bytes are updated. However, this leads to double counting of the allocation:
-                // (i) by the original alloc_slow_inline(); and (ii) by the alloc_slow_inline()
-                // called by acquire(). In order to not double count the allocation, we only
-                // update allocation bytes if the previous result wasn't 0x0.
+                // Only update the allocation bytes if we haven't failed a previous allocation in this loop
                 if stress_test && self.get_plan().is_initialized() && !previous_result_zero {
                     let allocated_size =
                         if plan.is_precise_stress() || !self.does_thread_local_allocation() {
@@ -302,7 +297,7 @@ pub trait Allocator<VM: VMBinding>: Downcast {
         }
     }
 
-    /// Single slow path allocation attempt. This is called by [`alloc_slow_inline`]. The
+    /// Single slow path allocation attempt. This is called by [`alloc_slow_inline`](Allocator::alloc_slow_inline). The
     /// implementation of this function depends on the allocator used. Generally, if an allocator
     /// supports thread local allocations, it will try to allocate more TLAB space here. If it
     /// doesn't, then (generally) the allocator simply allocates enough space for the current
diff --git a/src/util/alloc/bumpallocator.rs b/src/util/alloc/bumpallocator.rs
@@ -16,10 +16,15 @@ const BLOCK_MASK: usize = BLOCK_SIZE - 1;
 
 #[repr(C)]
 pub struct BumpAllocator<VM: VMBinding> {
+    /// [`VMThread`] associated with this allocator instance
     pub tls: VMThread,
+    /// Current cursor for bump pointer
     cursor: Address,
+    /// Limit for bump pointer
     limit: Address,
+    /// [`Space`](src/policy/space/Space) instance associated with this allocator instance.
     space: &'static dyn Space<VM>,
+    /// [`Plan`] instance that this allocator instance is associated with.
     plan: &'static dyn Plan<VM = VM>,
 }
 
@@ -44,12 +49,15 @@ impl<VM: VMBinding> Allocator<VM> for BumpAllocator<VM> {
     fn get_space(&self) -> &'static dyn Space<VM> {
         self.space
     }
+
     fn get_plan(&self) -> &'static dyn Plan<VM = VM> {
         self.plan
     }
+
     fn does_thread_local_allocation(&self) -> bool {
         true
     }
+
     fn get_thread_local_buffer_granularity(&self) -> usize {
         BLOCK_SIZE
     }
@@ -81,11 +89,14 @@ impl<VM: VMBinding> Allocator<VM> for BumpAllocator<VM> {
         self.acquire_block(size, align, offset, false)
     }
 
-    // Slow path for allocation if the precise stress test has been enabled.
-    // It works by manipulating the limit to be below the cursor always.
-    // Performs three kinds of allocations: (i) if the hard limit has been met;
-    // (ii) the bump pointer semantics from the fastpath; and (iii) if the stress
-    // factor has been crossed.
+    /// Slow path for allocation if precise stress testing has been enabled.
+    /// It works by manipulating the limit to be always below the cursor.
+    /// Can have three different cases:
+    ///  - acquires a new block if the hard limit has been met;
+    ///  - allocates an object using the bump pointer semantics from the
+    ///    fastpath if there is sufficient space; and
+    ///  - does not allocate an object but forces a poll for GC if the stress
+    ///    factor has been crossed.
     fn alloc_slow_once_precise_stress(
         &mut self,
         size: usize,
diff --git a/src/util/alloc/immix_allocator.rs b/src/util/alloc/immix_allocator.rs
@@ -18,7 +18,9 @@ pub struct ImmixAllocator<VM: VMBinding> {
     cursor: Address,
     /// Limit for bump pointer
     limit: Address,
+    /// [`Space`](src/policy/space/Space) instance associated with this allocator instance.
     space: &'static ImmixSpace<VM>,
+    /// [`Plan`] instance that this allocator instance is associated with.
     plan: &'static dyn Plan<VM = VM>,
     /// *unused*
     hot: bool,
@@ -207,7 +209,7 @@ impl<VM: VMBinding> ImmixAllocator<VM> {
         self.space
     }
 
-    /// Large-object (larger than a line) bump alloaction.
+    /// Large-object (larger than a line) bump allocation.
     fn overflow_alloc(&mut self, size: usize, align: usize, offset: isize) -> Address {
         trace!("{:?}: overflow_alloc", self.tls);
         let start = align_allocation_no_fill::<VM>(self.large_cursor, align, offset);
@@ -293,7 +295,12 @@ impl<VM: VMBinding> ImmixAllocator<VM> {
         match self.immix_space().get_clean_block(self.tls, self.copy) {
             None => Address::ZERO,
             Some(block) => {
-                trace!("{:?}: Acquired a new block {:?}", self.tls, block);
+                trace!(
+                    "{:?}: Acquired a new block {:?} -> {:?}",
+                    self.tls,
+                    block.start(),
+                    block.end()
+                );
                 if self.request_for_large {
                     self.large_cursor = block.start();
                     self.large_limit = adjust_thread_local_buffer_limit::<VM>(block.end());
@@ -306,54 +313,65 @@ impl<VM: VMBinding> ImmixAllocator<VM> {
         }
     }
 
-    /// Set fake limits for the bump allocation for stress tests. The fake limit is the remaining thread local buffer size,
-    /// which should be always smaller than the bump cursor.
-    /// This method may be reentrant. We need to check before setting the values.
+    /// Set fake limits for the bump allocation for stress tests. The fake limit is the remaining
+    /// thread local buffer size, which should be always smaller than the bump cursor. This method
+    /// may be reentrant. We need to check before setting the values.
     fn set_limit_for_stress(&mut self) {
         if self.cursor < self.limit {
+            let old_limit = self.limit;
             let new_limit = unsafe { Address::from_usize(self.limit - self.cursor) };
             self.limit = new_limit;
             trace!(
-                "{:?}: set_limit_for_stress. normal {} -> {}",
+                "{:?}: set_limit_for_stress. normal c {} l {} -> {}",
                 self.tls,
-                self.limit,
-                new_limit
+                self.cursor,
+                old_limit,
+                new_limit,
             );
         }
+
         if self.large_cursor < self.large_limit {
+            let old_lg_limit = self.large_limit;
             let new_lg_limit = unsafe { Address::from_usize(self.large_limit - self.large_cursor) };
             self.large_limit = new_lg_limit;
             trace!(
-                "{:?}: set_limit_for_stress. large {} -> {}",
+                "{:?}: set_limit_for_stress. large c {} l {} -> {}",
                 self.tls,
-                self.large_limit,
-                new_lg_limit
+                self.large_cursor,
+                old_lg_limit,
+                new_lg_limit,
             );
         }
     }
 
-    /// Restore the real limits for the bump allocation so we can do a properly thread local allocation.
-    /// The fake limit is the remaining thread local buffer size, and we restore the actual limit from the size and the cursor.
-    /// This method may be reentrant. We need to check before setting the values.
+    /// Restore the real limits for the bump allocation so we can properly do a thread local
+    /// allocation. The fake limit is the remaining thread local buffer size, and we restore the
+    /// actual limit from the size and the cursor. This method may be reentrant. We need to check
+    /// before setting the values.
     fn restore_limit_for_stress(&mut self) {
         if self.limit < self.cursor {
+            let old_limit = self.limit;
             let new_limit = self.cursor + self.limit.as_usize();
             self.limit = new_limit;
             trace!(
-                "{:?}: restore_limit_for_stress. normal {} -> {}",
+                "{:?}: restore_limit_for_stress. normal c {} l {} -> {}",
                 self.tls,
-                self.limit,
-                new_limit
+                self.cursor,
+                old_limit,
+                new_limit,
             );
         }
+
         if self.large_limit < self.large_cursor {
+            let old_lg_limit = self.large_limit;
             let new_lg_limit = self.large_cursor + self.large_limit.as_usize();
             self.large_limit = new_lg_limit;
             trace!(
-                "{:?}: restore_limit_for_stress. large {} -> {}",
+                "{:?}: restore_limit_for_stress. large c {} l {} -> {}",
                 self.tls,
-                self.large_limit,
-                new_lg_limit
+                self.large_cursor,
+                old_lg_limit,
+                new_lg_limit,
             );
         }
     }
diff --git a/src/util/alloc/large_object_allocator.rs b/src/util/alloc/large_object_allocator.rs
@@ -8,8 +8,11 @@ use crate::vm::VMBinding;
 
 #[repr(C)]
 pub struct LargeObjectAllocator<VM: VMBinding> {
+    /// [`VMThread`] associated with this allocator instance
     pub tls: VMThread,
+    /// [`Space`](src/policy/space/Space) instance associated with this allocator instance.
     space: &'static LargeObjectSpace<VM>,
+    /// [`Plan`] instance that this allocator instance is associated with.
     plan: &'static dyn Plan<VM = VM>,
 }
 
diff --git a/src/util/alloc/malloc_allocator.rs b/src/util/alloc/malloc_allocator.rs
@@ -9,18 +9,23 @@ use crate::Plan;
 
 #[repr(C)]
 pub struct MallocAllocator<VM: VMBinding> {
+    /// [`VMThread`] associated with this allocator instance
     pub tls: VMThread,
+    /// [`Space`](src/policy/space/Space) instance associated with this allocator instance.
     space: &'static MallocSpace<VM>,
+    /// [`Plan`] instance that this allocator instance is associated with.
     plan: &'static dyn Plan<VM = VM>,
 }
 
 impl<VM: VMBinding> Allocator<VM> for MallocAllocator<VM> {
     fn get_space(&self) -> &'static dyn Space<VM> {
         self.space as &'static dyn Space<VM>
     }
+
     fn get_plan(&self) -> &'static dyn Plan<VM = VM> {
         self.plan
     }
+
     fn alloc(&mut self, size: usize, align: usize, offset: isize) -> Address {
         self.alloc_slow(size, align, offset)
     }
diff --git a/src/util/alloc/markcompact_allocator.rs b/src/util/alloc/markcompact_allocator.rs
@@ -66,11 +66,14 @@ impl<VM: VMBinding> Allocator<VM> for MarkCompactAllocator<VM> {
         self.bump_allocator.alloc_slow_once(size, align, offset)
     }
 
-    // Slow path for allocation if the precise stress test has been enabled.
-    // It works by manipulating the limit to be below the cursor always.
-    // Performs three kinds of allocations: (i) if the hard limit has been met;
-    // (ii) the bump pointer semantics from the fastpath; and (iii) if the stress
-    // factor has been crossed.
+    /// Slow path for allocation if precise stress testing has been enabled.
+    /// It works by manipulating the limit to be always below the cursor.
+    /// Can have three different cases:
+    ///  - acquires a new block if the hard limit has been met;
+    ///  - allocates an object using the bump pointer semantics from the
+    ///    fastpath if there is sufficient space; and
+    ///  - does not allocate an object but forces a poll for GC if the stress
+    ///    factor has been crossed.
     fn alloc_slow_once_precise_stress(
         &mut self,
         size: usize,

Original file line number	Diff line number	Diff line change
`@@ -9,18 +9,23 @@ use crate::Plan;`
`9`	`9`
`10`	`10`	`#[repr(C)]`
`11`	`11`	`pub struct MallocAllocator<VM: VMBinding> {`
	`12`	+ /// [`VMThread`] associated with this allocator instance
`12`	`13`	`pub tls: VMThread,`
	`14`	+ /// [`Space`](src/policy/space/Space) instance associated with this allocator instance.
`13`	`15`	`space: &'static MallocSpace<VM>,`
	`16`	+ /// [`Plan`] instance that this allocator instance is associated with.
`14`	`17`	`plan: &'static dyn Plan<VM = VM>,`
`15`	`18`	`}`
`16`	`19`
`17`	`20`	`impl<VM: VMBinding> Allocator<VM> for MallocAllocator<VM> {`
`18`	`21`	`fn get_space(&self) -> &'static dyn Space<VM> {`
`19`	`22`	`self.space as &'static dyn Space<VM>`
`20`	`23`	`}`
	`24`	`+`
`21`	`25`	`fn get_plan(&self) -> &'static dyn Plan<VM = VM> {`
`22`	`26`	`self.plan`
`23`	`27`	`}`
	`28`	`+`
`24`	`29`	`fn alloc(&mut self, size: usize, align: usize, offset: isize) -> Address {`
`25`	`30`	`self.alloc_slow(size, align, offset)`
`26`	`31`	`}`