com::avpkit::ferry::RefCounted Class Reference

Parent of all Ferry objects – it mains reference counts in native code. More...

#include <RefCounted.h>

Inheritance diagram for com::avpkit::ferry::RefCounted:

Collaboration diagram for com::avpkit::ferry::RefCounted:

Public Member Functions
virtual int32_t	acquire ()
	Internal Only. More...
virtual int32_t	release ()
	Internal Only. More...
virtual RefCounted *	copyReference ()
	Create a new Java object that refers to the same native object. More...
virtual int32_t	getCurrentRefCount ()
	Return the current reference count on this object. More...
void	setJavaAllocator (void *allocator)
	This method is public but not part of the standard API. More...
void *	getJavaAllocator ()
	This method is public but not part of the standard API. More...

Protected Member Functions
virtual void	destroy ()
	This method is called by RefCounted objects when their Ref Count reaches zero and they are about to be destroyed.

Protected Attributes
AtomicInteger *	mRefCount
	This is the internal reference count, represented as an AtomicInteger to make sure it is thread safe.
void *	mAllocator
	Not part of public API.

Detailed Description

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();
}

Definition at line 84 of file RefCounted.h.

Member Function Documentation

acquire()

int32_t com::avpkit::ferry::RefCounted::acquire ( )

virtual

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.

Reimplemented in com::avpkit::core::StreamCoder, com::avpkit::core::Stream, and com::avpkit::core::Codec.

Definition at line 63 of file RefCounted.cpp.

  {
    //VS_LOG_DEBUG("acquire: %p", this);
    return mRefCount->incrementAndGet();
  }

References mRefCount.

Referenced by com::avpkit::core::Codec::acquire(), com::avpkit::core::Stream::acquire(), copyReference(), and com::avpkit::ferry::RefCountedTester::make().

copyReference()

RefCounted * com::avpkit::ferry::RefCounted::copyReference ( )

virtual

Create a new Java object that refers to the same native object.

This method is meant for other language use like Java; it will acquire the object but also force the creation of a new proxy object in the target language that just forwards to the same native object.

It is not meant for calling from C++ code; use the standard acquire and release semantics for that.

Returns

A new Java object.

Definition at line 94 of file RefCounted.cpp.

  {
    this->acquire();
    return this;
  }

References acquire().

getCurrentRefCount()

int32_t com::avpkit::ferry::RefCounted::getCurrentRefCount ( )

virtual

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.

Definition at line 80 of file RefCounted.cpp.

  {
    return mRefCount->get();
  }

References mRefCount.

getJavaAllocator()

void * com::avpkit::ferry::RefCounted::getJavaAllocator

(

)

This method is public but not part of the standard API.

Returns

Get the java allocator set.

Definition at line 57 of file RefCounted.cpp.

  {
    return mAllocator;
  }

References mAllocator.

Referenced by com::avpkit::ferry::Buffer::make().

release()

int32_t com::avpkit::ferry::RefCounted::release ( )

virtual

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.

Reimplemented in com::avpkit::core::StreamCoder, com::avpkit::core::Stream, and com::avpkit::core::Codec.

Definition at line 70 of file RefCounted.cpp.

  {
    //VS_LOG_DEBUG("release: %p", this);
    int32_t retval = mRefCount->decrementAndGet();
    if (!retval)
      this->destroy();
    return retval;
  }

References destroy(), and mRefCount.

Referenced by com::avpkit::core::Codec::release(), com::avpkit::core::Stream::release(), com::avpkit::core::Container::setMetaData(), and com::avpkit::core::Stream::setMetaData().

setJavaAllocator()

void com::avpkit::ferry::RefCounted::setJavaAllocator

(

void *

allocator

)

This method is public but not part of the standard API.

RefCounted objects can have a Java Allocator associated with them. In general users of this library should NEVER call this method, but it has to be public.

Parameters

allocator

An instance of a jobject we can use to do large memory allocation. The object should be of the com.avpkit.ferry.JNIMemoryAllocator java type.

Definition at line 46 of file RefCounted.cpp.

  {
    if (mAllocator)
      JNIHelper::sDeleteGlobalRef((jobject)mAllocator);
    if (allocator)
      mAllocator = JNIHelper::sNewGlobalRef((jobject)allocator);
    else
      mAllocator = 0;
  }

References mAllocator.

---

The documentation for this class was generated from the following files:

• csrc/com/avpkit/ferry/RefCounted.h
• csrc/com/avpkit/ferry/RefCounted.cpp