public class Pointer extends Object implements AutoCloseable
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.
For examples of subclasses, please refer to the following:
BytePointer
,
ShortPointer
,
IntPointer
,
LongPointer
,
FloatPointer
,
DoublePointer
,
CharPointer
,
PointerPointer
,
BoolPointer
,
CLongPointer
,
SizeTPointer
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. |
protected static class |
Pointer.NativeDeallocator
A
Pointer.Deallocator that calls, during garbage collection, a native function. |
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 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 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.
|
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() |
long |
capacity()
Returns
capacity . |
<P extends Pointer> |
capacity(long capacity)
Sets the capacity and returns this.
|
void |
close()
Calls
deallocate() . |
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> |
deallocator(Pointer.Deallocator deallocator)
Sets the deallocator and returns this.
|
boolean |
equals(Object obj)
Checks for equality with argument.
|
<P extends Pointer> |
fill(int b)
Calls in effect
memset(address + position, b, length) ,
where length = sizeof() * (limit - position) . |
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 . |
long |
limit()
Returns
limit . |
<P extends Pointer> |
limit(long limit)
Sets the limit and returns this.
|
static long |
maxBytes()
Returns
maxBytes , the maximum amount of memory allowed to be tracked. |
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) |
int |
offsetof(String member)
Returns
Loader.offsetof(getClass(), member) or -1 on error. |
long |
position()
Returns
position . |
<P extends Pointer> |
position(long position)
Sets the position and returns this.
|
<P extends Pointer> |
put(Pointer p)
Calls in effect
memcpy(this.address + this.position, p.address + p.position, length) ,
where length = sizeof(p) * (p.limit - p.position) . |
void |
setNull()
Sets
address to 0. |
int |
sizeof()
Returns 1 for Pointer or BytePointer else
Loader.sizeof(getClass()) or -1 on error. |
String |
toString()
|
static long |
totalBytes()
Returns
totalBytes() , current amount of memory tracked by deallocators. |
protected static <P extends Pointer> |
withDeallocator(P p)
A utility method to register easily a
Pointer.CustomDeallocator with a Pointer. |
<P extends Pointer> |
zero()
Returns
fill(0) . |
private static final Logger logger
private static final ReferenceQueue<Pointer> referenceQueue
ReferenceQueue
used by Pointer.DeallocatorReference
.
Initialized to null if the "org.bytedeco.javacpp.nopointergc" system property is "true".static final Thread deallocatorThread
static final long maxBytes
System.gc()
.
Set via "org.bytedeco.javacpp.maxbytes" system property, defaults to Runtime.maxMemory()
.static final int maxRetries
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)
.protected long address
protected long position
protected long limit
protected long capacity
private Pointer.Deallocator deallocator
public Pointer()
public Pointer(Pointer p)
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.
p
- the other Pointer to referenceprivate void allocate(Buffer b)
void init(long allocatedAddress, long allocatedCapacity, long ownerAddress, long deallocatorAddress)
allocatedAddress
- the new address value of allocated native memoryallocatedCapacity
- the amount of elements allocated (initial limit and capacity)deallocatorAddress
- the pointer to the native deallocation functionPointer.NativeDeallocator
protected static <P extends Pointer> P withDeallocator(P p)
Pointer.CustomDeallocator
with a Pointer.p
- the Pointer with which to register the deallocatorpublic static void deallocateReferences()
referenceQueue
.public static long maxBytes()
maxBytes
, the maximum amount of memory allowed to be tracked.public static long totalBytes()
totalBytes()
, current amount of memory tracked by deallocators.public boolean isNull()
address == 0
.public void setNull()
address
to 0.public long address()
address
.public long position()
position
.public <P extends Pointer> P position(long position)
array.position(i)
statement sort of equivalent to the array[i]
statement in C++.position
- the new positionpublic long limit()
limit
.public <P extends Pointer> P limit(long limit)
limit
- the new limitpublic long capacity()
capacity
.public <P extends Pointer> P capacity(long capacity)
capacity
- the new capacityprotected Pointer.Deallocator deallocator()
deallocator
.protected <P extends Pointer> P deallocator(Pointer.Deallocator deallocator)
null
. That is, it deallocates previously allocated memory.
Should not be called more than once after allocation.deallocator
- the new deallocatorpublic void close()
deallocate()
.close
in interface AutoCloseable
public void deallocate()
deallocate(true)
.public void deallocate(boolean deallocate)
deallocator(Deallocator)
.deallocate
- if true, deallocates, else does not, but disables garbage collectionpublic int offsetof(String member)
Loader.offsetof(getClass(), member)
or -1 on error.public int sizeof()
Loader.sizeof(getClass())
or -1 on error.private ByteBuffer asDirectBuffer()
public ByteBuffer asByteBuffer()
this.position(13).limit(42).asByteBuffer()
.ByteBuffer
createdpublic Buffer asBuffer()
asByteBuffer()
, but can be overridden to return subclasses of Buffer.asByteBuffer()
BytePointer.asBuffer()
,
ShortPointer.asBuffer()
,
IntPointer.asBuffer()
,
LongPointer.asBuffer()
,
FloatPointer.asBuffer()
,
DoublePointer.asBuffer()
,
CharPointer.asBuffer()
public <P extends Pointer> P put(Pointer p)
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))
.p
- the Pointer from which to copy memorypublic <P extends Pointer> P fill(int b)
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)
;b
- the byte value to fill the memory withpublic <P extends Pointer> P zero()
fill(0)
.public boolean equals(Object obj)
(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.Copyright © 2016. All rights reserved.