com.sun.cldc.jna
Class Pointer

java.lang.Object
  com.sun.squawk.realtime.RawMemoryAccess
      com.sun.squawk.realtime.RawMemoryFloatAccess
          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

• The backing native memory is not automically freed by finalization - No finalization in cldc.
• No getIntArray(), etc methods
  Use explicit "buf = new int[size]; geInts(offset, buf. size);" (from RTSJ)
• No read() methods, use getInts(), etc. instead (from RTSJ)
• No write() methods, use setInts(), etc. instead (from RTSJ)
• No getPointerArray() method - we need to specifiy a size for each Pointer
• No getChar(), setChar() or read or write of chars methods. (from RTSJ)
• No getByteBuffer() method - no NIO in cldc
• Some offsets are of type int instead of long (this is "Microedition", after all)
• Exception types may be different
• no support for native wide strings

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.