"

2013 FRC Java API

"

com.sun.cldc.jna
Class Pointer

java.lang.Object
  extended by com.sun.squawk.realtime.RawMemoryAccess
      extended by com.sun.squawk.realtime.RawMemoryFloatAccess
          extended by com.sun.cldc.jna.Pointer
Direct Known Subclasses:
VarPointer

public class Pointer
extends RawMemoryFloatAccess

A pointer to native memory, based on RTSJ-like RawMemoryAccesss semantics. Otherise similar to the Memory class in JNA. All pointers have a size, so memory access through a pointer is range-checked. A pointer can either have a dedicated backing buffer of native memory (from malloc or similar), or it may be a "shared" subset of some other Pointer.

Differences from JNA


Field Summary
 
Fields inherited from class com.sun.squawk.realtime.RawMemoryAccess
vbase
 
Constructor Summary
Pointer(Address base, int size)
          Create a pointer that refers to a memory range from [base..base+size).
Pointer(Address base, UWord size)
          Create a pointer that refers to a memory range from [base..base+size).
Pointer(int size)
          Create a pointer and allocate backing native memory of the requestsed size.
Pointer(long base, int size)
          Create a pointer that refers to a memory range from [base..base+size).
 
Method Summary
 Address address()
          Gets the virtual memory location at which the memory region is mapped.
 Pointer align(int byteAlignment)
          Create a new pointer that is a subset of this pointer, but is aligned to byteAlignment
 void clear()
          Zero memory
 void clear(int size)
          Zero the first "size" bytes of memory
static void copyBytes(Pointer src, int srcOffset, Pointer dst, int dstOffset, int len)
          Copy len bytes from src to dst starting at the given offsets.
static Pointer createStringBuffer(String value)
          Create a native buffer containing the C-string version of the String vaue.
 void free()
          Free the backing native memory for this pointer.
 Pointer getPointer(int offset, int size)
          Read a ptr value from memory at offset, and construct a new pointer representing the data stored there...
 int getSize()
          Gets the size of the memory
 String getString(int offset)
          Create a Java string from a C string pointer to by this pointer at offset
 boolean isValid()
           
static String NativeUnsafeGetString(Address cstr)
          Create a Java string from a C string pointer
static Pointer NULL()
           
 void release()
          Free the backing native memory for this pointer if this pointer was created by allocating memory.
 void setPointer(int offset, Pointer ptr)
          Set the word at offset from this pointer to the the address contained in ptr.
 void setString(int offset, String value)
          Copy string value to the location at offset.
 Pointer share(long offset)
          Create a new pointer that is a subset of this pointer, starting from offset
 Pointer share(long offset, long size)
          Create a new pointer that is a subset of this pointer, starting from offset
 String toString()
          Returns a string representation of the object.
 
Methods inherited from class com.sun.squawk.realtime.RawMemoryFloatAccess
getDouble, getDoubles, getFloat, getFloats, setDouble, setDoubles, setFloat, setFloats
 
Methods inherited from class com.sun.squawk.realtime.RawMemoryAccess
checkBounds, checkMultiBounds, checkMultiRead, checkMultiWrite, getAddress, getByte, getBytes, getInt, getInts, getLong, getLongs, getMappedAddress, getShort, getShorts, invalidate, map, map, map, setByte, setBytes, setInt, setInts, setLong, setLongs, setShort, setShorts, size, wasMalloced
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Pointer

public Pointer(int size)
        throws SizeOutOfBoundsException,
               OutOfMemoryError
Create a pointer and allocate backing native memory of the requestsed size. This backing memory can be freed later using free().

Parameters:
size - the number of bytes that can be referenced from this pointer
Throws:
SizeOutOfBoundsException - if the size is negative or too large
OutOfMemoryError - if the backing memory cannot be allocated

Pointer

public Pointer(long base,
               int size)
Create a pointer that refers to a memory range from [base..base+size). This pointer should NOT be freed.

Parameters:
base - the base address of the pointer
size - the number of bytes that can be referenced from this pointer
Throws:
SecurityException - if the memory range intersets the Java heap
OffsetOutOfBoundsException - Thrown if the address is invalid.
SizeOutOfBoundsException - Thrown if the size is negative or extends into an invalid range of memory.

Pointer

public Pointer(Address base,
               UWord size)
Create a pointer that refers to a memory range from [base..base+size). This pointer should NOT be freed.

Parameters:
base - the base address of the pointer
size - the number of bytes that can be referenced from this pointer
Throws:
SecurityException - if the memory range intersets the Java heap
OffsetOutOfBoundsException - Thrown if the address is invalid.
SizeOutOfBoundsException - Thrown if the size is negative or extends into an invalid range of memory.

Pointer

public Pointer(Address base,
               int size)
Create a pointer that refers to a memory range from [base..base+size). This pointer should NOT be freed.

Parameters:
base - the base address of the pointer
size - the number of bytes that can be referenced from this pointer
Throws:
SecurityException - if the memory range intersets the Java heap
OffsetOutOfBoundsException - Thrown if the address is invalid.
SizeOutOfBoundsException - Thrown if the size is negative or extends into an invalid range of memory.
Method Detail

NULL

public static Pointer NULL()

share

public Pointer share(long offset)
Create a new pointer that is a subset of this pointer, starting from offset

Parameters:
offset - offset from this pointer to start the new pointer
Returns:
new pointer

share

public Pointer share(long offset,
                     long size)
Create a new pointer that is a subset of this pointer, starting from offset

Parameters:
offset - offset from this pointer to start the new pointer
size - size of the new pointer
Returns:
new pointer

align

public Pointer align(int byteAlignment)
Create a new pointer that is a subset of this pointer, but is aligned to byteAlignment

Parameters:
byteAlignment -
Returns:
new pointer
Throws:
IllegalArgumentException - if byteAlignment is not a power of 2

toString

public String toString()
Description copied from class: Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Overrides:
toString in class Object
Returns:
a string representation of the object.

address

public final Address address()
Gets the virtual memory location at which the memory region is mapped.

Returns:
The virtual address to which this is mapped (for reference purposes). Same as the base address if virtual memory is not supported.
Throws:
IllegalStateException - Thrown if the raw memory object is not in the mapped state.

getSize

public final int getSize()
Gets the size of the memory

Returns:
the size of the native memory area

clear

public void clear(int size)
Zero the first "size" bytes of memory

Parameters:
size - number of bytes

clear

public void clear()
Zero memory


getPointer

public Pointer getPointer(int offset,
                          int size)
Read a ptr value from memory at offset, and construct a new pointer representing the data stored there...

Parameters:
offset - offset from this pointer that conatins a memory location that is an address.
size - the size that the new pointer should have
Returns:
a new pointer with e

setPointer

public void setPointer(int offset,
                       Pointer ptr)
Set the word at offset from this pointer to the the address contained in ptr.

Parameters:
offset - offset in bytes from this pointer's base to the word to be set.
ptr - the value that will be set

getString

public String getString(int offset)
Create a Java string from a C string pointer to by this pointer at offset

Parameters:
offset - the byte offset of the c string from the base of this pointer
Returns:
a java string

NativeUnsafeGetString

public static String NativeUnsafeGetString(Address cstr)
Create a Java string from a C string pointer

Parameters:
cstr -
Returns:
a java string

setString

public final void setString(int offset,
                            String value)
Copy string value to the location at offset. Convert the data in value to a NULL-terminated C string, converted to native encoding.

Parameters:
offset - the byte offset of the c string from the base of this pointer
value - the string to copy

free

public final void free()
                throws IllegalStateException
Free the backing native memory for this pointer. After freeing the pointer, all accesses to memory through this pointer will throw an exception.

Throws:
IllegalStateException - if free has already been called on this pointer.

release

public final void release()
                   throws IllegalStateException
Free the backing native memory for this pointer if this pointer was created by allocating memory. If this pointer points to a subset of another buffer, or points to a "pinned" object, do nothing. After releasing the pointer, all accesses to memory through this pointer will throw an exception.

Throws:
IllegalStateException - if release has already been called on this pointer.

isValid

public final boolean isValid()
Returns:
false if the memory is the NULL pointer or has been freed.

createStringBuffer

public static Pointer createStringBuffer(String value)
                                  throws OutOfMemoryError
Create a native buffer containing the C-string version of the String vaue. The returned pointer should be freed when not needed.

Parameters:
value - the string to copy
Returns:
Pointer the newly allocated memory
Throws:
OutOfMemoryError - if the underlying memory cannot be allocated

copyBytes

public static void copyBytes(Pointer src,
                             int srcOffset,
                             Pointer dst,
                             int dstOffset,
                             int len)
                      throws OffsetOutOfBoundsException,
                             SizeOutOfBoundsException
Copy len bytes from src to dst starting at the given offsets. Throws exception if the memory ranges specified for src dst dst stray outside the valid ranges for those Pointers.

Parameters:
src - Pointer to the source bytes
srcOffset - offset in bytes to start copying from
dst - Pointer to the destination bytes
dstOffset - offset in bytes to start copying to
len - number of bytes to copy
Throws:
OffsetOutOfBoundsException - Thrown if an offset is negative or greater than the size of the raw memory area. The role of the SizeOutOfBoundsException somewhat overlaps this exception since it is thrown if the offset is within the object but outside the mapped area.
SizeOutOfBoundsException - Thrown if the object is not mapped, or if the requested memory raange falls in an invalid address range.

"

2013 FRC Java API

"

"
For updated information see the Java FRC site
"