[rvm-commits] code: RVM-867 : Improve comments in org.mmtk.utility.Allocator.

[<jik...@li...>]

details:   http://hg.code.sourceforge.net/p/jikesrvm/code/rev/0fd4fcfe8dd6
changeset: 10871:0fd4fcfe8dd6
user:      Erik Brangs <eri...@gm...>
date:      Fri Aug 29 13:41:27 2014 +0200
description:
RVM-867 : Improve comments in org.mmtk.utility.Allocator.

The comments in the class still need to be updated to use consistent terminology. Some comments still refer to "particles" which are no longer visible as concept in the code base (except for a comment in BumpAllocator).


diffstat:

 MMTk/src/org/mmtk/utility/alloc/Allocator.java |  14 ++++++++++++--
 1 files changed, 12 insertions(+), 2 deletions(-)

diffs (45 lines):

diff --git a/MMTk/src/org/mmtk/utility/alloc/Allocator.java b/MMTk/src/org/mmtk/utility/alloc/Allocator.java
--- a/MMTk/src/org/mmtk/utility/alloc/Allocator.java
+++ b/MMTk/src/org/mmtk/utility/alloc/Allocator.java
@@ -38,7 +38,10 @@
  *
  * Failing to handle this properly will lead to very hard to trace bugs
  * where the allocation that caused a GC or allocations immediately following
- * GC are run incorrectly.
+ * GC are run incorrectly.<p>
+ *
+ * TODO the comments in this class need to be rephrased from using the
+ * particle terminology to alignments.
  */
 @Uninterruptible
 public abstract class Allocator {
@@ -83,6 +86,8 @@
    * @param alignment The requested alignment
    * @param offset The offset from the alignment
    * @param knownAlignment The statically known minimum alignment.
+   * @param fillAlignmentGap whether to fill up holes in the alignment
+   *  with the alignment value ({@link Constants#ALIGNMENT_VALUE})
    * @return The aligned up address.
    */
   @Inline
@@ -186,6 +191,8 @@
    *
    * @param size The number of bytes (not aligned).
    * @param alignment The requested alignment (some factor of 2).
+   * @return the minimum size (in bytes) that's necessary to guarantee allocation
+   *  at the given alignment
    */
   @Inline
   public static int getMaximumAlignedSize(int size, int alignment) {
@@ -200,7 +207,10 @@
    * @param alignment The requested alignment (some factor of 2).
    * @param knownAlignment The known minimum alignment. Specifically for use in
    * allocators that enforce greater than particle alignment. It is a <b>precondition</b>
-   * that size is aligned to knownAlignment, and that knownAlignment &gt;= MIN_ALGINMENT.
+   * that size is aligned to knownAlignment, and that knownAlignment &gt;=
+   * {@link Constants#MIN_ALIGNMENT}.
+   * @return the minimum size (in bytes) that's necessary to guarantee allocation
+   *  at the given alignment
    */
   @Inline
   public static int getMaximumAlignedSize(int size, int alignment, int knownAlignment) {