Package org.bytedeco.javacpp

Class Pointer

    • Field Detail

      • logger

        private static final Logger logger

      • referenceQueue

        private static final java.lang.ref.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 java.lang.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 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​(java.nio.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​(java.nio.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

      • 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 java.lang.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​(java.lang.String string,
                              long relativeMultiple)
                       throws java.lang.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:
        java.lang.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 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("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)
                                             java.nio.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 <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 java.lang.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

      • 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

      • offsetof

        public static int offsetof​(java.lang.Class<? extends Pointer> type,
                           java.lang.String member)
        Returns Loader.offsetof(type, member).

      • offsetof

        public int offsetof​(java.lang.String member)
        Returns Loader.offsetof(getClass(), member) or -1 on error.

      • sizeof

        public static int sizeof​(java.lang.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 java.nio.ByteBuffer asDirectBuffer()

      • asByteBuffer

        public java.nio.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:
        ByteBuffer.isDirect(), getPointer(long)

      • malloc

        public static Pointer malloc​(long size)

      • calloc

        public static Pointer calloc​(long n,
                             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)

      • 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​(java.lang.Class<P> type)
        Returns getPointer(type, 0).

      • getPointer

        public <P extends Pointer> P getPointer​(java.lang.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​(java.lang.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 java.lang.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 java.lang.Object