android.speech.recognition.SmartProxy Class Reference

Collaboration diagram for android.speech.recognition.SmartProxy:

Collaboration graph
[legend]

List of all members.


Detailed Description

Users should treat a SmartProxy as if it is a pointer to the underlying object it wraps. Smart proxies are modeled after the boost shared_ptr design, discussed one of the the URLs listed below.

There are a few guidelines for using proxies:

  1. Retain a copy of (as opposed to a reference to) a proxy to ensure that the underlying object does not get destroyed until the proxy gets destroyed.
  2. Pass a proxy around by reference (as opposed to pass-by-value) for efficiency.
  3. There are two kinds of proxy objects: stack-based or heap-based. The most common type of proxy is a stack-based local variable declared inside a function body. This proxy is ideal because it is thread-safe (no other thread can access function local variables) and gets deallocated automatically at the end of the method, along with all other local variables. Heap-based proxies, on the other hand, must be explicitly deleted.
  4. Individual proxy objects are not thread-safe so if you absolutely must access the same proxy from multiple threads (as opposed to giving each thread its own proxy) then you must synchronize access to it manually.
  5. Factory methods should return proxies by value.
  6. Methods should accept proxies by reference.
  7. Never construct more than one root proxy per object. The first SmartProxy ever constructed around an object is called the "root proxy". Root proxies are constructed using SmartProxy(void* object, ReturnCode.Type& returnCode). A root proxy contains the reference count of the underlying object. This means that if you construct multiple root proxies per underlying object, each root will see a difference reference count and one root will destroy the object before the other roots are done using it.
If you absolutely must wrap the same pointer multiple times and you do not have access to existing proxies that wrap it, simply store SmartProxy.getCounter() alongside the pointer and construct all future proxies using SmartProxy(RefCounter*) instead.

See also:
http://www.boost.org/libs/smart_ptr/shared_ptr.htm

http://en.wikipedia.org/wiki/Proxy_pattern

http://blogs.sun.com/nsolter/entry/reference_counting_smart_pointers_made

Author:
Gili Tzabari

Public Types

typedef void(* BoolConversion )()

Public Member Functions

virtual UAPI_EXPORT
Root
getRoot () const
virtual UAPI_EXPORT
SmartProxy
operator= (const SmartProxy &other)
UAPI_EXPORT operator BoolConversion () const
virtual UAPI_EXPORT bool operator! () const

Protected Member Functions

UAPI_EXPORT SmartProxy (void *object, const char *name)
UAPI_EXPORT SmartProxy (void *object, bool loggingAllowed, const char *name)
UAPI_EXPORT SmartProxy (Root *root)
UAPI_EXPORT SmartProxy (const SmartProxy &other)
UAPI_EXPORT SmartProxy ()
virtual UAPI_EXPORT ~SmartProxy ()
virtual UAPI_EXPORT void deleteObject (void *object)
UAPI_EXPORT void * getObject () const
virtual UAPI_EXPORT void onDestruction ()

Friends

class System

Classes

class  Root

Member Typedef Documentation

typedef void(* android.speech.recognition.SmartProxy.BoolConversion)()

Enables boolean conversion.

See also:
http://www.artima.com/cppsource/safebool2.html


Constructor & Destructor Documentation

UAPI_EXPORT android.speech.recognition.SmartProxy.SmartProxy ( void *  object,
const char *  name 
) [explicit, protected]

Creates a root SmartProxy for the specified pointer. If construction fails then !proxy will return true.

Parameters:
object a pointer to a shared object

UAPI_EXPORT android.speech.recognition.SmartProxy.SmartProxy ( void *  object,
bool  loggingAllowed,
const char *  name 
) [explicit, protected]

Creates a root SmartProxy for the specified pointer. If construction fails then !proxy will return true.

Parameters:
object a pointer to a shared object
loggingAllowed true if the object and its dependencies are allowed logging

UAPI_EXPORT android.speech.recognition.SmartProxy.SmartProxy ( Root root  )  [explicit, protected]

Constructs a new SmartProxy from an existing root proxy. If construction fails then !proxy will return true.

Parameters:
root the root proxy

UAPI_EXPORT android.speech.recognition.SmartProxy.SmartProxy ( const SmartProxy other  )  [protected]

Constructs a copy of an existing SmartProxy. If construction failed then !proxy will return true.

UAPI_EXPORT android.speech.recognition.SmartProxy.SmartProxy (  )  [protected]

Enables the construction of arrays of proxies. The proxy is initialized to null.

virtual UAPI_EXPORT android.speech.recognition.SmartProxy.~SmartProxy (  )  [protected, virtual]

Destroys the SmartProxy.


Member Function Documentation

virtual UAPI_EXPORT Root* android.speech.recognition.SmartProxy.getRoot (  )  const [virtual]

Returns the root proxy.

Returns:
the root proxy.

virtual UAPI_EXPORT SmartProxy& android.speech.recognition.SmartProxy.operator= ( const SmartProxy other  )  [virtual]

Causes the current SmartProxy to point to the same object as another SmartProxy. If the operation fails then !proxy will return true.

Parameters:
other the SmartProxy whose object to point to
Returns:
the resulting SmartProxy

virtual UAPI_EXPORT bool android.speech.recognition.SmartProxy.operator! (  )  const [virtual]

Returns true if the SmartProxy is null.

Returns:
true if the SmartProxy is null

virtual UAPI_EXPORT void android.speech.recognition.SmartProxy.deleteObject ( void *  object  )  [protected, virtual]

Deletes the underlying object. Subclasses must override this method as only they know the actual type of the underlying object.

Parameters:
object the underlying object

UAPI_EXPORT void* android.speech.recognition.SmartProxy.getObject (  )  const [protected]

Returns the underlying object.

Returns:
the underlying object

virtual UAPI_EXPORT void android.speech.recognition.SmartProxy.onDestruction (  )  [protected, virtual]

Invoked by the SmartProxy destructor.


Generated on Thu May 1 17:16:51 2008 for UAPI by  doxygen 1.5.3