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:

See Also:

  • Field Details

    • 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 + 3 * Runtime.maxMemory() : 0. If maxBytes is also not set, this is equivalent to a default of 4 * 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 Details

    • 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 Details

    • 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:

    • offsetAddress

      protected <P extends Pointer> P offsetAddress(long i)
      Adds i * sizeof() to address and subtracts i from limit and capacity.

    • 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

    • interruptDeallocatorThread

      public static void interruptDeallocatorThread()
      Calls deallocatorThread.interrupt().

    • 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 Pointer.DeallocatorReference.totalBytes, current amount of memory tracked by deallocators.

    • totalCount

      public static long totalCount()
      Returns Pointer.DeallocatorReference.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("JavaCPP_trimMemory") private static boolean trimMemory()
      Makes sure to return freed memory to the system, as required by Linux, at least.

    • physicalBytes

      @Name("JavaCPP_physicalBytes") public static long physicalBytes()
      Returns the amount of non-shared physical memory currently used by the whole process, or 0 if unknown. Also known as "anonymous resident set size" (Linux, Mac OS X, etc) or "private working set size" (Windows).

    • physicalBytesInaccurate

      @Name("JavaCPP_physicalBytes") public static long physicalBytesInaccurate(long maxSize)
      May return a value larger than physicalBytes() but less than maxSize to save processing time.

    • totalPhysicalBytes

      @Name("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("JavaCPP_availablePhysicalBytes") public static long availablePhysicalBytes()
      Returns the amount of physical memory that is free according to the operating system, or 0 if unknown.

    • getDirectBufferAddress

      @Name("JavaCPP_getDirectBufferAddress") protected static long getDirectBufferAddress(@Raw(withEnv=true) Buffer b)
      Returns the starting address of the memory region referenced by the given direct Buffer. An alternative to allocating a new Pointer object if all you need is the memory address.

    • 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 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()
      Creates a new ByteBuffer covering the memory space between the position and limit of this Pointer. The way the methods were designed allows constructs such as this.position(13).limit(42).asByteBuffer().

      The new buffer's position will be equal to position, its capacity and its limit will be equal to limit, and its mark will be undefined. In the event that limit <= 0, the capacity and limit will be set to position + 1. The new buffer will be direct and mutable.

      NOTE: ByteBuffer objects can only support a capacity of size Integer.MAX_VALUE. Certain combinations of position and limit can be greater than the supported capacity. For example, the following code snippet initializes a BytePointer and attempts to make a ByteBuffer from the final element: 

      final long bigSize = Integer.MAX_VALUE + 1L;

try (BytePointer pointer = new BytePointer(bigSize)) {
    pointer.fill(1);
    pointer.put(pointer.capacity() - 1L, (byte)100);

    ByteBuffer buffer = pointer.position(Integer.MAX_VALUE)
                               .asByteBuffer();

    buffer.position(); // 2147483647
    buffer.capacity(); // 2147483647 (error: off by 1)
    buffer.remaining(); // 0 (error: off by 1)
}
      In order to access this memory location using a ByteBuffer, you must first offset this pointer's address. See the example below: 
      final long bigSize = Integer.MAX_VALUE + 1L;

try (BytePointer pointer = new BytePointer(bigSize)) {
    pointer.fill(1);
    pointer.put(pointer.capacity() - 1L, (byte)100);

    ByteBuffer buffer = pointer.getPointer(Integer.MAX_VALUE)
                               .asByteBuffer();

    buffer.position(); // 0
    buffer.capacity(); // 1
    buffer.remaining(); // 1
}
      Returns:
      the direct NIO ByteBuffer created
      See Also:

    • asBuffer

      public Buffer asBuffer()
      Same as asByteBuffer(), but can be overridden to return subclasses of Buffer.
      Returns:
      asByteBuffer()
      See Also:

    • 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 extends Pointer> P getPointer()
      Returns getPointer(0).

    • getPointer

      public <P extends Pointer> P getPointer(long i)
      Returns getPointer(getClass(), i).

    • getPointer

      public <P extends Pointer> P getPointer(Class<P> type)
      Returns getPointer(type, 0).

    • getPointer

      public <P extends Pointer> P getPointer(Class<P> type, long i)
      Returns new P(this).offsetAddress(i) after scaling position, limit, and capacity with sizeof(). Throws RuntimeException if the cast constructor is missing from the subclass type.

    • 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