Package com.avpkit.ferry

Class RefCounted

  • Direct Known Subclasses:
    Global, IAudioResampler, IBuffer, ICodec, IContainer, IContainerFormat, IError, IFilterChain, IIndexEntry, IMediaData, IMediaFilter, IMetaData, IPixelFormat, IProperty, IRational, IStream, IStreamCoder, ITimeValue, IVideoResampler, Mutex, RefCountedTester
    public class RefCounted
extends java.lang.Object
    Parent of all Ferry objects -- it mains reference counts
    in native code.


    RefCounted objects cannot be made with new. They must be
    constructed with special factory methods, usually called
    make(...).


    Special note for developers in languages other than C++



    You should not need to worry about this class very much. Feel
    free to ignore it.


    Special note for C++ Users



    Users of RefCounted objects in Native (C++) code must make
    sure they acquire() a reference to an object if they
    intend to keep using it after they have returned from
    the method it was passed to, and
    must call release() when done to ensure memory is freed.



    Methods that return RefCounted objects on the stack are
    expected to acquire() the reference for the caller, and
    callers must release() any RefCounted object
    returned on the stack.


    For example:




    
 RefCounted * methodReturningRefCountedObject();
    
 {
    
   mValueToReturn->acquire(); // acquire for caller
    
   return mValueToReturn; // and return
    
 }
    
 
    
 {
    
   RefCounted *value = methodReturningRefCountedObject();
    
   ...
    
   // caller must release
    
   if (value)
    
     value->release();
    
 }

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected boolean swigCMemOwn
      Internal Only.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected RefCounted​(long cPtr, boolean cMemoryOwn)
      Internal Only.
      protected RefCounted​(long cPtr, boolean cMemoryOwn, java.util.concurrent.atomic.AtomicLong ref)
      Internal Only.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int acquire()
      Internal Only.
      RefCounted copyReference()
      Create a new RefCounted object that is actually referring to the exact same underlying native object.
      void delete()
      Releases any underlying native memory and marks this object as invalid.
      static long getCPtr​(RefCounted obj)
      Internal Only.
      long getCurrentRefCount()
      Return the current reference count on this object.
      protected java.util.concurrent.atomic.AtomicLong getJavaRefCount()
      Internal Only.
      long getMyCPtr()
      Internal Only.
      int release()
      Internal Only.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • swigCMemOwn

        protected boolean swigCMemOwn
        Internal Only.

    • Constructor Detail

      • RefCounted

        protected RefCounted​(long cPtr,
                     boolean cMemoryOwn)
        Internal Only. Not part of public API.

      • RefCounted

        protected RefCounted​(long cPtr,
                     boolean cMemoryOwn,
                     java.util.concurrent.atomic.AtomicLong ref)
        Internal Only. Not part of public API.

    • Method Detail

      • getCPtr

        public static long getCPtr​(RefCounted obj)
        Internal Only. Not part of public API. Get the raw value of the native object that obj is proxying for.
        Parameters:
        obj - The java proxy object for a native object.
        Returns:
        The raw pointer obj is proxying for.

      • getMyCPtr

        public long getMyCPtr()
        Internal Only. Not part of public API. Get the raw value of the native object that we're proxying for.
        Returns:
        The raw pointer we're proxying for.

      • delete

        public void delete()
        Releases any underlying native memory and marks this object as invalid.

        Normally Ferry manages when to release native memory.

        In the unlikely event you want to control EXACTLY when a native object is released, each AVPKit object has a delete() method that you can use. Once you call delete(), you must ENSURE your object is never referenced again from that Java object -- Ferry tries to help you avoid crashes if you accidentally use an object after deletion but on this but we cannot offer 100% protection (specifically if another thread is accessing that object EXACTLY when you delete() it).

      • copyReference

        public RefCounted copyReference()
        Create a new RefCounted object that is actually referring to the exact same underlying native object.
        Returns:
        the new Java object.

      • getJavaRefCount

        protected java.util.concurrent.atomic.AtomicLong getJavaRefCount()
        Internal Only. Do not use.

      • getCurrentRefCount

        public long getCurrentRefCount()
        Return the current reference count on this object.

        The number returned represents the value at the instant the message was called, and the value can change even before this method returns. Callers are advised not to depend on the value of this except to check that the value == 1.

        If the value returned is one, and you know you have a valid reference to that object, then congratulations; you are the only person referencing that object.

        Returns:
        The current ref count.

      • acquire

        public int acquire()
        Internal Only. DO NOT USE FROM JAVA.


        Acquire a reference to this object.
        This increments the native internal ref count in native code by +1.



        This method is called internally by Ferry in Java, and you should
        not call it without knowing what you are doing. But if you do
        call it, make sure you call {#release()} once for each call
        you make to this method.


        Returns:
        The refcount after the acquire. Note due to multi-threaded issues, you should not rely on this value,
        as it may change before the method returns to you.

      • release

        public int release()
        Internal Only. DO NOT USE FROM JAVA.


        This decrements the native internal ref count by -1; the object is destroyed if its ref count reaches zero.



        This method is called internally by Ferry in Java, and you should
        not call it without knowing what you are doing. But if you do
        call it, make sure you had previously called {#acquire()} once for each call
        to {#release()} you make.


        Returns:
        The ref count after the release. Note due to multi-threaded issues, you should not rely on this value,
        as it may change before the method returns to you.