Pointer (JavaCPP 1.5.5 API)

java.lang.Object
- org.bytedeco.javacpp.Pointer

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

BooleanPointer, BoolPointer, BytePointer, CharPointer, CLongPointer, DoublePointer, FloatPointer, FunctionPointer, IntPointer, LongPointer, PointerPointer, ShortPointer, SizeTPointer
```
@Properties(inherit=javacpp.class)
public class Pointer
extends Object
implements AutoCloseable
```
All peer classes to native types must be descended from Pointer, the topmost class. It can be thought as mapping the native C++ void*, which can point to any struct, class, or union. All Pointer classes get parsed by Generator to produce proper wrapping JNI code, but this base class also provides functionality to access native array elements as well as utility methods and classes to let users benefit not only from from garbage collection, but also the try-with-resources statement, since it implements the AutoCloseable interface.
It is also possible to use a PointerScope to keep track of a group of Pointer objects, and have them deallocated in a transparent but deterministic manner.
For examples of subclasses, please refer to the following:

Author:

Samuel Audet

See Also:

BytePointer, ShortPointer, IntPointer, LongPointer, FloatPointer, DoublePointer, CharPointer, PointerPointer, BoolPointer, CLongPointer, SizeTPointer

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`Pointer.CustomDeallocator` A `Pointer.Deallocator` that calls, during garbage collection, a method with signature `static void deallocate()` from the Pointer object passed to the constructor and that accepts it as argument.
`protected static interface`	`Pointer.Deallocator` The interface to implement to produce a Deallocator usable by Pointer.
`(package private) static class`	`Pointer.DeallocatorReference` A subclass of `PhantomReference` that also acts as a linked list to keep their references alive until they get garbage collected.
`(package private) static class`	`Pointer.DeallocatorThread`
`protected static class`	`Pointer.NativeDeallocator` A `Pointer.Deallocator` that calls, during garbage collection, a native function.
`(package private) static class`	`Pointer.ProxyDeallocator` A `Pointer.Deallocator` that keeps and uses a strong reference to a Buffer or another Pointer.
`protected static interface`	`Pointer.ReferenceCounter`

Field Summary

Fields
Modifier and Type	Field and Description
`protected long`	`address` The native address of this Pointer, which can be an array.
`protected long`	`capacity` The number of elements contained in this native array, or 0 if unknown.
`private Pointer.Deallocator`	`deallocator` The deallocator associated with this Pointer that should be called on garbage collection.
`(package private) static Thread`	`deallocatorThread`
`protected long`	`limit` The index of the first element that should not be accessed, or 0 if unknown.
`private static Logger`	`logger`
`(package private) static long`	`maxBytes` Maximum amount of memory registered with live deallocators before forcing call to `System.gc()`.
`(package private) static long`	`maxPhysicalBytes` Maximum amount of memory reported by `physicalBytes()` before forcing call to `System.gc()`.
`(package private) static int`	`maxRetries` Maximum number of times to call `System.gc()` before giving up with `OutOfMemoryError`.
`protected long`	`position` The index of the element of a native array that should be accessed.
`private static ReferenceQueue<Pointer>`	`referenceQueue` The `ReferenceQueue` used by `Pointer.DeallocatorReference`.

Constructor Summary

Constructors
Constructor and Description
`Pointer()` Default constructor that does nothing.
`Pointer(Buffer b)` Copies the address, position, limit, and capacity of a direct NIO `Buffer`.
`Pointer(Pointer p)` Copies the address, position, limit, and capacity of another Pointer.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`long`	`address()` Returns `address`.
`private void`	`allocate(Buffer b)`
`Buffer`	`asBuffer()` Same as `asByteBuffer()`, but can be overridden to return subclasses of Buffer.
`ByteBuffer`	`asByteBuffer()` Returns a ByteBuffer covering the memory space from this.position to this.limit.
`private ByteBuffer`	`asDirectBuffer()`
`static long`	`availablePhysicalBytes()` Returns the amount of physical memory that is free according to the operating system, or 0 if unknown.
`static Pointer`	`calloc(long n, long size)`
`long`	`capacity()` Returns `capacity`.
`<P extends Pointer> P`	`capacity(long capacity)` Sets the capacity and returns this.
`void`	`close()` Calls `releaseReference()`.
`void`	`deallocate()` Calls `deallocate(true)`.
`void`	`deallocate(boolean deallocate)` Explicitly manages native memory without waiting after the garbage collector.
`static void`	`deallocateReferences()` Clears, deallocates, and removes all garbage collected objects from the `referenceQueue`.
`protected Pointer.Deallocator`	`deallocator()` Returns `deallocator`.
`protected <P extends Pointer> P`	`deallocator(Pointer.Deallocator deallocator)` Sets the deallocator and returns this.
`boolean`	`equals(Object obj)` Checks for equality with argument.
`<P extends Pointer> P`	`fill(int b)` Calls in effect `memset(address + position, b, length)`, where `length = sizeof() * (limit - position)`.
`static String`	`formatBytes(long bytes)` Truncates and formats the number of bytes to a human readable string ending with "T", "G", "M", or "K" (as multiples of 1024).
`static void`	`free(Pointer p)`
`<P extends Pointer> P`	`getPointer()` Returns `getPointer(0)`.
`<P extends Pointer> P`	`getPointer(Class<P> cls)` Returns `getPointer(cls, 0)`.
`<P extends Pointer> P`	`getPointer(Class<P> cls, long i)` Returns `new P(this).position(position + i)`.
`<P extends Pointer> P`	`getPointer(long i)` Returns `new Pointer(this).position((position + i) * sizeof()).capacity(capacity * sizeof()).limit(limit * sizeof())`.
`int`	`hashCode()` Returns `(int)address`.
`(package private) void`	`init(long allocatedAddress, long allocatedCapacity, long ownerAddress, long deallocatorAddress)` Called by native libraries to initialize the object fields.
`boolean`	`isNull()` Returns `address == 0`.
`static boolean`	`isNull(Pointer p)` Returns `p == null \|\| p.address == 0`.
`long`	`limit()` Returns `limit`.
`<P extends Pointer> P`	`limit(long limit)` Sets the limit and returns this.
`static Pointer`	`malloc(long size)`
`static long`	`maxBytes()` Returns `maxBytes`, the maximum amount of memory allowed to be tracked.
`static long`	`maxPhysicalBytes()` Returns `maxPhysicalBytes`, the maximum amount of physical memory that should be used.
`static Pointer`	`memchr(Pointer p, int ch, long size)`
`static int`	`memcmp(Pointer p1, Pointer p2, long size)`
`static Pointer`	`memcpy(Pointer dst, Pointer src, long size)`
`static Pointer`	`memmove(Pointer dst, Pointer src, long size)`
`static Pointer`	`memset(Pointer dst, int ch, long size)`
`static int`	`offsetof(Class<? extends Pointer> type, String member)` Returns `Loader.offsetof(type, member)`.
`int`	`offsetof(String member)` Returns `Loader.offsetof(getClass(), member)` or -1 on error.
`static long`	`parseBytes(String string, long relativeMultiple)` Returns the amount of bytes for a number possibly ending with "%", "t", "g", m", or "k" (as multiples of 1024).
`static long`	`physicalBytes()` Returns the amount of physical memory currently used by the whole process, or 0 if unknown.
`long`	`position()` Returns `position`.
`<P extends Pointer> P`	`position(long position)` Sets the position and returns this.
`<P extends Pointer> P`	`put(Pointer p)` Calls in effect `memcpy(this.address + this.position, p.address + p.position, length)`, where `length = sizeof(p) * (p.limit - p.position)`.
`static Pointer`	`realloc(Pointer p, long size)`
`int`	`referenceCount()` Returns `Pointer.ReferenceCounter.count()` or -1 if no deallocator has been set.
`boolean`	`releaseReference()` Calls `Pointer.ReferenceCounter.release()`, decrementing the reference count by 1, in turn deallocating this Pointer when the count drops to 0.
`<P extends Pointer> P`	`retainReference()` Calls `Pointer.ReferenceCounter.retain()`, incrementing the reference count by 1.
`void`	`setNull()` Sets `address` to 0.
`int`	`sizeof()` Returns 1 for Pointer or BytePointer else `Loader.sizeof(getClass())` or -1 on error.
`static int`	`sizeof(Class<? extends Pointer> type)` Returns `Loader.sizeof(type)`.
`String`	`toString()` Returns a `String` representation of `address`, `position`, `limit`, `capacity`, and `deallocator`.
`static long`	`totalBytes()` Returns `totalBytes()`, current amount of memory tracked by deallocators.
`static long`	`totalCount()` Returns `totalCount()`, current number of pointers tracked by deallocators.
`static long`	`totalPhysicalBytes()` Returns the amount of physical memory installed according to the operating system, or 0 if unknown.
`private static boolean`	`trimMemory()` Makes sure to return freed memory to the system, as required by Linux, at least.
`protected static <P extends Pointer> P`	`withDeallocator(P p)` A utility method to register easily a `Pointer.CustomDeallocator` with a Pointer.
`<P extends Pointer> P`	`zero()` Returns `fill(0)`.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
 - logger
```
private static final Logger logger
```
 - referenceQueue
```
private static final ReferenceQueue<Pointer> referenceQueue
```
 The ReferenceQueue used by Pointer.DeallocatorReference. Initialized to null if the "org.bytedeco.javacpp.noPointerGC" system property is "true".
 - deallocatorThread
```
static final Thread deallocatorThread
```
 - maxBytes
```
static final long maxBytes
```
 Maximum amount of memory registered with live deallocators before forcing call to System.gc(). Set via "org.bytedeco.javacpp.maxBytes" system property, defaults to Runtime.maxMemory(). The value is parsed with parseBytes(String, long) where relativeMultiple = Runtime.maxMemory(). We can use a value of 0 or less to prevent any explicit call to the garbage collector.
 - maxPhysicalBytes
```
static final long maxPhysicalBytes
```
 Maximum amount of memory reported by physicalBytes() before forcing call to System.gc(). Set via "org.bytedeco.javacpp.maxPhysicalBytes" system property, defaults to maxBytes > 0 ? maxBytes + Runtime.maxMemory() : 0. If maxBytes is also not set, this is equivalent to a default of 2 * Runtime.maxMemory(). The value is parsed with parseBytes(String, long) where relativeMultiple = Runtime.maxMemory(). We can use a value of 0 or less to prevent any explicit call to the garbage collector.
 - maxRetries
```
static final int maxRetries
```
 Maximum number of times to call System.gc() before giving up with OutOfMemoryError. Set via "org.bytedeco.javacpp.maxRetries" system property, defaults to 10, where each retry is followed by a call to Thread.sleep(100) and Pointer.trimMemory().
 - address
```
protected long address
```
 The native address of this Pointer, which can be an array.
 - position
```
protected long position
```
 The index of the element of a native array that should be accessed.
 - limit
```
protected long limit
```
 The index of the first element that should not be accessed, or 0 if unknown.
 - capacity
```
protected long capacity
```
 The number of elements contained in this native array, or 0 if unknown.
 - deallocator
```
private Pointer.Deallocator deallocator
```
 The deallocator associated with this Pointer that should be called on garbage collection.
- Constructor Detail
 - Pointer
```
public Pointer()
```
 Default constructor that does nothing.
 - Pointer
```
public Pointer(Pointer p)
```
 Copies the address, position, limit, and capacity of another Pointer. Also keeps a reference to it to prevent its memory from getting deallocated.
 This copy constructor basically acts as a reinterpret_cast, at least on plain old data (POD) struct, so we need to be careful with it.
 
 Parameters:
 
 p - the other Pointer to reference
 - Pointer
```
public Pointer(Buffer b)
```
 Copies the address, position, limit, and capacity of a direct NIO Buffer. Also keeps a reference to it to prevent its memory from getting deallocated.
 
 Parameters:
 
 b - the Buffer object to reference
- Method Detail
 - allocate
```
private void allocate(Buffer b)
```
 - init
```
void init(long allocatedAddress,
 long allocatedCapacity,
 long ownerAddress,
 long deallocatorAddress)
```
 Called by native libraries to initialize the object fields.
 
 Parameters:
 
 allocatedAddress - the new address value of allocated native memory
 
 allocatedCapacity - the amount of elements allocated (initial limit and capacity)
 
 deallocatorAddress - the pointer to the native deallocation function
 
 See Also:
 
 Pointer.NativeDeallocator
 - withDeallocator
```
protected static  P withDeallocator(P p)
```
 A utility method to register easily a Pointer.CustomDeallocator with a Pointer.
 
 Parameters:
 
 p - the Pointer with which to register the deallocator
 
 Returns:
 
 the Pointer
 - formatBytes
```
public static String formatBytes(long bytes)
```
 Truncates and formats the number of bytes to a human readable string ending with "T", "G", "M", or "K" (as multiples of 1024).
 - parseBytes
```
public static long parseBytes(String string,
 long relativeMultiple)
 throws NumberFormatException
```
 Returns the amount of bytes for a number possibly ending with "%", "t", "g", m", or "k" (as multiples of 1024). May also be suffixed with an optional "b", where all letters are case-insensitive.
 
 Parameters:
 
 string - to parse
 
 relativeMultiple - to use in the case of "%", which is divided by 100
 
 Returns:
 
 the amount of bytes
 
 Throws:
 
 NumberFormatException
 - deallocateReferences
```
public static void deallocateReferences()
```
 Clears, deallocates, and removes all garbage collected objects from the referenceQueue.
 - maxBytes
```
public static long maxBytes()
```
 Returns maxBytes, the maximum amount of memory allowed to be tracked.
 - totalBytes
```
public static long totalBytes()
```
 Returns totalBytes(), current amount of memory tracked by deallocators.
 - totalCount
```
public static long totalCount()
```
 Returns totalCount(), current number of pointers tracked by deallocators.
 - maxPhysicalBytes
```
public static long maxPhysicalBytes()
```
 Returns maxPhysicalBytes, the maximum amount of physical memory that should be used.
 - trimMemory
```
@Name(value="JavaCPP_trimMemory")
private static boolean trimMemory()
```
 Makes sure to return freed memory to the system, as required by Linux, at least.
 - physicalBytes
```
@Name(value="JavaCPP_physicalBytes")
public static long physicalBytes()
```
 Returns the amount of physical memory currently used by the whole process, or 0 if unknown. Also known as "resident set size" (Linux, Mac OS X, etc) or "working set size" (Windows).
 - totalPhysicalBytes
```
@Name(value="JavaCPP_totalPhysicalBytes")
public static long totalPhysicalBytes()
```
 Returns the amount of physical memory installed according to the operating system, or 0 if unknown. It should not be possible for physicalBytes() to go over this value.
 - availablePhysicalBytes
```
@Name(value="JavaCPP_availablePhysicalBytes")
public static long availablePhysicalBytes()
```
 Returns the amount of physical memory that is free according to the operating system, or 0 if unknown.
 - isNull
```
public static boolean isNull(Pointer p)
```
 Returns p == null || p.address == 0.
 - isNull
```
public boolean isNull()
```
 Returns address == 0.
 - setNull
```
public void setNull()
```
 Sets address to 0.
 - address
```
public long address()
```
 Returns address.
 - position
```
public long position()
```
 Returns position.
 - position
```
public  P position(long position)
```
 Sets the position and returns this. That makes the array.position(i) statement sort of equivalent to the array[i] statement in C++.
 
 Parameters:
 
 position - the new position
 
 Returns:
 
 this
 - limit
```
public long limit()
```
 Returns limit.
 - limit
```
public  P limit(long limit)
```
 Sets the limit and returns this. Used to limit the size of an operation on this object.
 
 Parameters:
 
 limit - the new limit
 
 Returns:
 
 this
 - capacity
```
public long capacity()
```
 Returns capacity.
 - capacity
```
public  P capacity(long capacity)
```
 Sets the capacity and returns this. Should not be called more than once after allocation.
 
 Parameters:
 
 capacity - the new capacity
 
 Returns:
 
 this
 - deallocator
```
protected Pointer.Deallocator deallocator()
```
 Returns deallocator.
 - deallocator
```
protected  P deallocator(Pointer.Deallocator deallocator)
```
 Sets the deallocator and returns this. Also clears current deallocator if not null. That is, it deallocates previously allocated memory. Should not be called more than once after allocation.
 
 Parameters:
 
 deallocator - the new deallocator
 
 Returns:
 
 this
 - close
```
public void close()
```
 Calls releaseReference().
 
 Specified by:
 
 close in interface AutoCloseable
 - deallocate
```
public void deallocate()
```
 Calls deallocate(true).
 - deallocate
```
public void deallocate(boolean deallocate)
```
 Explicitly manages native memory without waiting after the garbage collector. Has no effect if no deallocator was previously set with deallocator(Deallocator).
 
 Parameters:
 
 deallocate - if true, deallocates, else does not, but disables garbage collection
 - retainReference
```
public  P retainReference()
```
 Calls Pointer.ReferenceCounter.retain(), incrementing the reference count by 1. Has no effect if no deallocator was previously set with deallocator(Deallocator).
 
 Returns:
 
 this
 - releaseReference
```
public boolean releaseReference()
```
 Calls Pointer.ReferenceCounter.release(), decrementing the reference count by 1, in turn deallocating this Pointer when the count drops to 0. Has no effect if no deallocator was previously set with deallocator(Deallocator).
 
 Returns:
 
 true when the count drops to 0 and deallocation has occurred
 - referenceCount
```
public int referenceCount()
```
 Returns Pointer.ReferenceCounter.count() or -1 if no deallocator has been set.
 - offsetof
```
public static int offsetof(Class<? extends Pointer> type,
 String member)
```
 Returns Loader.offsetof(type, member).
 - offsetof
```
public int offsetof(String member)
```
 Returns Loader.offsetof(getClass(), member) or -1 on error.
 - sizeof
```
public static int sizeof(Class<? extends Pointer> type)
```
 Returns Loader.sizeof(type).
 - sizeof
```
public int sizeof()
```
 Returns 1 for Pointer or BytePointer else Loader.sizeof(getClass()) or -1 on error.
 - asDirectBuffer
```
private ByteBuffer asDirectBuffer()
```
 - asByteBuffer
```
public ByteBuffer asByteBuffer()
```
 Returns a ByteBuffer covering the memory space from this.position to this.limit. If limit == 0, it uses position + 1 instead. The way the methods were designed allows constructs such as this.position(13).limit(42).asByteBuffer().
 
 Returns:
 
 the direct NIO ByteBuffer created
 - asBuffer
```
public Buffer asBuffer()
```
 Same as asByteBuffer(), but can be overridden to return subclasses of Buffer.
 
 Returns:
 
 asByteBuffer()
 
 See Also:
 
 BytePointer.asBuffer(), ShortPointer.asBuffer(), IntPointer.asBuffer(), LongPointer.asBuffer(), FloatPointer.asBuffer(), DoublePointer.asBuffer(), CharPointer.asBuffer()
 - malloc
```
public static Pointer malloc(long size)
```
 - calloc
```
public static Pointer calloc(long n,
 long size)
```
 - realloc
```
public static Pointer realloc(Pointer p,
 long size)
```
 - free
```
public static void free(Pointer p)
```
 - memchr
```
public static Pointer memchr(Pointer p,
 int ch,
 long size)
```
 - memcmp
```
public static int memcmp(Pointer p1,
 Pointer p2,
 long size)
```
 - memcpy
```
public static Pointer memcpy(Pointer dst,
 Pointer src,
 long size)
```
 - memmove
```
public static Pointer memmove(Pointer dst,
 Pointer src,
 long size)
```
 - memset
```
public static Pointer memset(Pointer dst,
 int ch,
 long size)
```
 - getPointer
```
public  P getPointer()
```
 Returns getPointer(0).
 - getPointer
```
public  P getPointer(long i)
```
 Returns new Pointer(this).position((position + i) * sizeof()).capacity(capacity * sizeof()).limit(limit * sizeof()).
 - getPointer
```
public  P getPointer(Class cls)
```
 Returns getPointer(cls, 0).
 - getPointer
```
public  P getPointer(Class cls,
 long i)
```
 Returns new P(this).position(position + i). Throws RuntimeException if constructor is missing.
 - put
```
public  P put(Pointer p)
```
 Calls in effect memcpy(this.address + this.position, p.address + p.position, length), where length = sizeof(p) * (p.limit - p.position). If limit == 0, it uses position + 1 instead. The way the methods were designed allows constructs such as this.position(0).put(p.position(13).limit(42)).
 
 Parameters:
 
 p - the Pointer from which to copy memory
 
 Returns:
 
 this
 - fill
```
public  P fill(int b)
```
 Calls in effect memset(address + position, b, length), where length = sizeof() * (limit - position). If limit == 0, it uses position + 1 instead. The way the methods were designed allows constructs such as this.position(0).limit(13).fill(42);
 
 Parameters:
 
 b - the byte value to fill the memory with
 
 Returns:
 
 this
 - zero
```
public  P zero()
```
 Returns fill(0).
 - equals
```
public boolean equals(Object obj)
```
 Checks for equality with argument. Defines obj to be equal if (obj == null && this.address == 0) || (obj.address == this.address && obj.position == this.position), and the classes are the same, unless one of them in Pointer itself.
 
 Overrides:
 
 equals in class Object
 
 Parameters:
 
 obj - the object to compare this Pointer to
 
 Returns:
 
 true if obj is equal
 - hashCode
```
public int hashCode()
```
 Returns (int)address.
 
 Overrides:
 
 hashCode in class Object
 - toString
```
public String toString()
```
 Returns a String representation of address, position, limit, capacity, and deallocator.
 
 Overrides:
 
 toString in class Object

Class Pointer

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

logger

referenceQueue

deallocatorThread

maxBytes

maxPhysicalBytes

maxRetries

address

position

limit

capacity

deallocator

Constructor Detail

Pointer

Pointer

Pointer

Method Detail

allocate

init

withDeallocator

formatBytes

parseBytes

deallocateReferences

maxBytes

totalBytes

totalCount

maxPhysicalBytes

trimMemory

physicalBytes

totalPhysicalBytes

availablePhysicalBytes

isNull

isNull

setNull

address

position

position

limit

limit

capacity

capacity

deallocator

deallocator

close

deallocate

deallocate

retainReference

releaseReference

referenceCount

offsetof

offsetof

sizeof

sizeof

asDirectBuffer

asByteBuffer

asBuffer

malloc

calloc

realloc

free

memchr

memcmp

memcpy

memmove

memset

getPointer

getPointer

getPointer

getPointer

put

fill

zero

equals

hashCode