svn commit: r768233 - in /commons/sandbox/runtime/trunk/src: main/java/org/apache/commons/runtime/Memory.java main/native/shared/memory.c test/org/apache/commons/runtime/TestMemory.java

[mt...@apache.org]

Author: mturk
Date: Fri Apr 24 09:24:37 2009
New Revision: 768233

URL: http://svn.apache.org/viewvc?rev=768233&view=rev
Log:
Add null Pointer Memory.malloc

Modified:
    commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Memory.java
    commons/sandbox/runtime/trunk/src/main/native/shared/memory.c
    commons/sandbox/runtime/trunk/src/test/org/apache/commons/runtime/TestMemory.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=768233&r1=768232&r2=768233&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 Apr 24 09:24:37 2009
@@ -32,6 +32,70 @@
         // No Instance
     }
 
+    private static native Pointer nullp0();
+
+    /**
+     * Create a new {@code null Pointer}.
+     *
+     * <p>
+     * Creating new {@code null} pointers make sense only for
+     * using that object as a reference for methods that
+     * require a {@code Pointer} whose size is unknown at the
+     * time of the call. The method will usually fill the pointer
+     * with the valid memory block area. A typical usage of such
+     * a {code Pointer} can be explained as this:
+     * <pre>
+     *
+     * void *pointer;
+     *
+     * int method(void **pointer, int size)
+     * {
+     *     *pointer = malloc(size + something);
+     *     return something;
+     * }
+     *
+     *     ...
+     *
+     *     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
+     * {@code pointer} was declared.
+     * </p>
+     * <p>
+     * Typical usage in Java code would be as follows:
+     * <pre>
+     *
+     *     Pointer ptr = Memory.malloc();
+     *
+     *     DirectByteBuffer b = DirectByteBuffer.allocate(ptr, size);
+     *
+     *     ...
+     *
+     *     ptr.free();
+     *
+     * </pre>
+     * The newly created {@code DirectyByteBuffer} holds the memory
+     * area pointed by {@code Pointer} object and {@code Pointer}
+     * object holds a native pointer to a physical memory area location.
+     * When done the memory should be released by calling
+     * {@code ptr.free()}.
+     * </p>
+     *
+     * @return {@code null} pointer.
+     * @throws OutOfMemoryError if memory cannot be allocated.
+     */
+    public static Pointer malloc()
+        throws OutOfMemoryError
+    {
+        Pointer p = nullp0();
+        if (p == null)
+            throw new OutOfMemoryError("Memory alloc failed");
+        return p;
+    }
+
+
     /**
      * Allocates {@code size} bytes and returns a {@link Pointer}
      * to the allocated memory. The memory is not cleared.

Modified: commons/sandbox/runtime/trunk/src/main/native/shared/memory.c
URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/native/shared/memory.c?rev=768233&r1=768232&r2=768233&view=diff
==============================================================================
--- commons/sandbox/runtime/trunk/src/main/native/shared/memory.c (original)
+++ commons/sandbox/runtime/trunk/src/main/native/shared/memory.c Fri Apr 24 09:24:37 2009
@@ -247,6 +247,12 @@
     }
 }
 
+ACR_JNI_EXPORT_DECLARE(jobject, Memory, nullp0)(ACR_JNISTDARGS)
+{
+    UNREFERENCED_O;
+    return ACR_PointerCreate(_E, NULL, 0, ptr_cleanup);
+}
+
 ACR_JNI_EXPORT_DECLARE(jobject, Memory, malloc)(ACR_JNISTDARGS, jlong siz)
 {
     jobject ptr = NULL;

Modified: commons/sandbox/runtime/trunk/src/test/org/apache/commons/runtime/TestMemory.java
URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/test/org/apache/commons/runtime/TestMemory.java?rev=768233&r1=768232&r2=768233&view=diff
==============================================================================
--- commons/sandbox/runtime/trunk/src/test/org/apache/commons/runtime/TestMemory.java (original)
+++ commons/sandbox/runtime/trunk/src/test/org/apache/commons/runtime/TestMemory.java Fri Apr 24 09:24:37 2009
@@ -41,6 +41,22 @@
     }
 
 
+
+    public void testNull()
+        throws Throwable
+    {
+        Pointer p = Memory.malloc();
+        assertNotNull("Pointer", p);
+        assertTrue("Not null", p.IsNull());
+        try {
+            p.free();
+            fail("Not RuntimeException");
+        } catch (RuntimeException ex) {
+            // calling free() in null Pointer
+            // throws RuntimeException
+        }
+    }
+
     public void testMalloc()
         throws Throwable
     {
@@ -185,7 +201,7 @@
         p.free();
     }
 
-    public void testNull()
+    public void testPointerNull()
         throws Throwable
     {
         assertTrue("Not null", Pointer.NULL.IsNull());