org.bytedeco.javacpp

Class Pointer

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

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)
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)
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.
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	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 extends Pointer> 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.

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 extends Pointer> 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 extends Pointer> 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 extends Pointer> 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 extends Pointer> 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 extends Pointer> 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 int offsetof(String member)

Returns Loader.offsetof(getClass(), member) or -1 on error.

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)

put

public <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). 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 extends Pointer> 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 extends Pointer> 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