com.xuggle.ferry
Class RefCounted

Package class diagram package RefCounted
java.lang.Object
  extended by com.xuggle.ferry.RefCounted
Direct Known Subclasses:
Global, IAudioResampler, IBuffer, ICodec, IContainer, IContainerFormat, IContainerParameters, IError, IIndexEntry, IMediaData, IMetaData, IPixelFormat, IProperty, IRational, IStream, IStreamCoder, ITimeValue, IVideoResampler, Mutex, RefCountedTester

public class RefCounted
extends 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
protected  boolean swigCMemOwn
          Internal Only.
 
Constructor Summary
protected RefCounted(long cPtr, boolean cMemoryOwn)
          Internal Only.
protected RefCounted(long cPtr, boolean cMemoryOwn, AtomicLong ref)
          Internal Only.
 
Method Summary
 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  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,
                     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 Xuggler 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 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.


Copyright © 2008, 2010 Xuggle