Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

TypedHandle Class Template Reference

#include <coherence/lang/TypedHandle.hpp>

Inherited by BoxHandle, Immutable, String::StringHandle, SubscriptHandle, and throwable_spec::hierarchy.

List of all members.


Detailed Description

template<class T>
class coherence::lang::TypedHandle< T >

Reference counting "smart pointer" class for use with Coherence managed objects.

Managed objects manage their own life cycle, rather the relying on user code to identify when they should be deleted. The TypedHandle class can be used with any class implementing the coherence::lang::Object interface.

By convention each Object implementation will include two typedefs for TypedHandle to make their usage easier. For instance the class "Foo" would define Foo::Handle as a TypedHandle<Foo>. The second typedef is called a View, and is analogous to a pointer to a const, that is Foo::View is TypedHandle<const Foo>.

TypedHandles are not thread-safe, and should not be used in a multi-threaded context even if protected by external synchronization. They should only be used as local variables. The most common place where thread-safe handles are needed is for object data members. For these cases the Coherence API includes thread-safe handles/views, namely MemberHandle/View and WeakHandle/View.

See also:
Object

MemberHandle

MemberView

WeakHandle

WeakView

FinalHandle

FinalView

Author:
mf 2007.07.05

Public Types

typedef T ValueType
 A concrete object type that is referenced by this handle.
typedef
value_less_functor
< T > 
value_compare
 Functor allowing handles to be used within STL sorted containers, such as std::map and std::set, and to have their equivalence checks delegated to the Objects they reference.
typedef
value_equal_functor
< T > 
value_equal
 Functor allowing handles to be used within hash containers, such as the SGI and MS style hash_map and hash_set, and to have their equivalence checks delegated to the Objects they reference.
typedef
value_hash_functor
< T > 
value_hasher
 Functor allowing handles to be used within hash containers, such as the SGI as MS style hash_map and hash_set, and to have their hash computation be based on the value of the referenced Object.
typedef
identity_hash_functor
< T > 
identity_hasher
 Functor allowing handles to be used within hash containers, such as the SGI as MS style hash_map and hash_set, and to have their hash computation be based on their identity, i.e.

Public Member Functions

 T ()
 Construct a handle that references NULL.
 T (T *po)
 Construct a handle that references given Object.
 T (T *po, const ChainedHandleElement &that)
 Construct a handle which is linked to another chained element type.
template<class DT>
 T (const TypedHandle< DT > &that)
 Construct a handle from a handle to a derived type.
 T (const TypedHandle< T > &that)
 Construct a handle from another handle.
 ~ ()
 Destruct this handle.
T & operator * () const
 Dereference this handle, returning T&.
T * operator-> () const
 Dereference this handle, returning T*.
TypedHandle< T > & operator= (const TypedHandle< T > &h)
 Assign this TypedHandle another Object to reference.
template<class DT>
TypedHandle< T > & operator= (const TypedHandle< DT > &h)
 Assign this TypedHandle from a handle to a derived type.
template<class AT>
bool operator< (const TypedHandle< AT > &h) const
 Compare two handles with "less-than" predicate.

Protected Member Functions

T * get () const
 Return pointer without null checking.
TypedHandle< T > & set (T *o, const ChainedHandleElement &that)
 Set the TypedHandle to attach to the supplied pointer.
void performAction (Action nAction, T *po)
 Perform the specified action.
void safeDestruct (Action nAction)
 Destruct the handle.

Protected Attributes

T * m_o
 Pointer to the referenced object.

Classes

class  identity_hash_functor
 Identity based hash functor which is compatible with both the SGI and MS style hash containers. More...
class  value_equal_functor
 The binary functor that compares values pointed by the handles for equality. More...
class  value_hash_functor
 Value based hash functor which is compatible with both the SGI and MS style hash containers. More...
class  value_less_functor
 The binary functor that compares objects pointed by the handles with the "less-than" operator. More...

Member Typedef Documentation

typedef identity_hash_functor<T> identity_hasher

Functor allowing handles to be used within hash containers, such as the SGI as MS style hash_map and hash_set, and to have their hash computation be based on their identity, i.e.

the reference they contain.


Member Function Documentation

T ( T *  po  )  [inline]

Construct a handle that references given Object.

Parameters:
po a pointer to the Object to reference

T ( T *  po,
const ChainedHandleElement &  that 
) [inline]

Construct a handle which is linked to another chained element type.

This is used for chaining Holders to Handles.

Parameters:
po the pointer to assign from
that the "owner" of that pointer

T ( const TypedHandle< DT > &  that  )  [inline]

Construct a handle from a handle to a derived type.

New handle will reference the same Object that the given handle.

Parameters:
that another handle

T ( const TypedHandle< T > &  that  )  [inline]

Construct a handle from another handle.

New handle will reference the same Object that the given handle.

Parameters:
that another handle

T& operator * (  )  const [inline]

Dereference this handle, returning T&.

Returns:
a raw T& reference to the referenced Object
Exceptions:
NullPointerException if the this handle is NULL

T* operator-> (  )  const [inline]

Dereference this handle, returning T*.

Returns:
a raw T* pointer to the referenced Object
Exceptions:
NullPointerException if the this handle is NULL

bool operator< ( const TypedHandle< AT > &  h  )  const [inline]

Compare two handles with "less-than" predicate.

This is only an identity based comparison, and does not take the value into account.

T* get (  )  const [inline, protected]

Return pointer without null checking.

Does NOT throw NullPointerException.

One should use h.get() to get raw T* pointer. Please do not use neither &*h (as it may throw NullPointerException) nor (T*)h (as it may perform unsafe unchecked type cast).

TypedHandle<T>& set ( T *  o,
const ChainedHandleElement &  that 
) [inline, protected]

Set the TypedHandle to attach to the supplied pointer.

Any existing attachment will be detached.

Parameters:
o the address of the object to point to or NULL

void performAction ( Action  nAction,
T *  po 
) [inline, protected]

Perform the specified action.

Parameters:
nAction the action to perform
po pointer to object on which to act

void safeDestruct ( Action  nAction  )  [inline, protected]

Destruct the handle.

Any exception occurring during destruction will simply be printed, the intent of this function is for use during TypedHandle destruction. It is not the common path and is pulled out to encourage inlining of the destructor.


The documentation for this class was generated from the following file:
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.