svn commit: r790818 - /commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Memory.java

[Mladen Turk-3]

Author: mturk
Date: Fri Jul  3 07:49:49 2009
New Revision: 790818

URL: http://svn.apache.org/viewvc?rev=790818&view=rev
Log:
Update javadocs

Modified:
    commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Memory.java

Modified: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Memory.java
URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Memory.java?rev=790818&r1=790817&r2=790818&view=diff
==============================================================================
--- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Memory.java (original)
+++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Memory.java Fri Jul  3 07:49:49 2009
@@ -28,7 +28,7 @@
 {
 
     /**
-     * Default pointer alignment.
+     * Default memory alignment.
      */
     public static final int DEFAULT_ALIGNMENT = 8;
 
@@ -94,7 +94,7 @@
      * method(&pointer, 16);
      * ...
      * free(pointer);
-     *
+     *
      * </pre>
      * The example code uses {@code by-reference} concept to fill in
      * the provided {@code pointer} with the value unknown at the time
@@ -162,13 +162,19 @@
         throws OutOfMemoryError, RuntimeException;
     /**
      * Change the size of memory block pointed by {@code ptr}.
+     * <p>
+     * If the Pointer was created using {@code slice} the
+     * method will throw {@code RuntimeException} because the
+     * sliced memory points to the shared memory segment and
+     * cannot be reallocated.
+     * </p>
      *
      * @param ptr Pointer which size to change..
      * @param size The new size of the memory block.
      *
      * @throws OutOfMemoryError if memory cannot be allocated.
      * @throws IllegalArgumentException if the size is less then {@code 1}.
-     * @throws RuntimeException if the {@src} point to an invalid address.
+     * @throws RuntimeException if the {@code ptr} points to an invalid address.
      */
     public static void realloc(Pointer ptr, long size)
         throws OutOfMemoryError, IllegalArgumentException, RuntimeException
@@ -184,7 +190,14 @@
     /**
      * Creates a new {@link Pointer} object whose content is a shared
      * subsequence of a {@code src} memory address.
-     *
+     * <p>
+     * Sliced memory cannot be reallocated. Calling {@link #realloc(Pointer, long) realloc}
+     * will throw an {@code RuntimeException} if such attempt is made.
+     * </p>
+     * <p>
+     * Calling {@link Pointer#free() Pointer.free()} has no effect on sliced
+     * memory pointer.
+     * </p>
      * @param src {@code Pointer} whose content to use.
      * @param offset offset from the {@code src} memory address.
      * @param size size of the destination memory.
@@ -804,7 +817,7 @@
                                      long dstPos, int length)
         throws IndexOutOfBoundsException;
     /**
-     * Copy the array pointed by {@code src} to the memory area
+     * Copy the array pointed by {@code src} to the memory area
      * pointed by {@code dst} pointer.
      *
      * @param src source {@code array}.
@@ -837,7 +850,7 @@
                                      long dstPos, int length)
         throws IndexOutOfBoundsException;
     /**
-     * Copy the array pointed by {@code src} to the memory area
+     * Copy the array pointed by {@code src} to the memory area
      * pointed by {@code dst} pointer.
      *
      * @param src source {@code array}.
@@ -870,7 +883,7 @@
                                      long dstPos, int length)
         throws IndexOutOfBoundsException;
     /**
-     * Copy the array pointed by {@code src} to the memory area
+     * Copy the array pointed by {@code src} to the memory area
      * pointed by {@code dst} pointer.
      *
      * @param src source {@code array}.
@@ -903,7 +916,7 @@
                                      long dstPos, int length)
         throws IndexOutOfBoundsException;
     /**
-     * Copy the array pointed by {@code src} to the memory area
+     * Copy the array pointed by {@code src} to the memory area
      * pointed by {@code dst} pointer.
      *
      * @param src source {@code array}.
@@ -936,7 +949,7 @@
                                      long dstPos, int length)
         throws IndexOutOfBoundsException;
     /**
-     * Copy the array pointed by {@code src} to the memory area
+     * Copy the array pointed by {@code src} to the memory area
      * pointed by {@code dst} pointer.
      *
      * @param src source {@code array}.
@@ -969,7 +982,7 @@
                                      long dstPos, int length)
         throws IndexOutOfBoundsException;
     /**
-     * Copy the array pointed by {@code src} to the memory area
+     * Copy the array pointed by {@code src} to the memory area
      * pointed by {@code dst} pointer.
      *
      * @param src source {@code array}.
@@ -1002,7 +1015,7 @@
                                      long dstPos, int length)
         throws IndexOutOfBoundsException;
     /**
-     * Copy the array pointed by {@code src} to the memory area
+     * Copy the array pointed by {@code src} to the memory area
      * pointed by {@code dst} pointer.
      *
      * @param src source {@code array}.