SPtr Class Template Reference

Inheritance diagram for SPtr:

SQPtr


Public Methods

 SPtr ()
 SPtr (T *in)
 SPtr (const char *classID, bool factory=false)
 SPtr (const SRef< T > &in)
 SPtr (const SPtr< T > &in)
 ~SPtr ()
void release ()
void createInstance (const char *classID, IBase *reserved=NULL)
 operator T *& () const
T * operator-> () const
T * operator= (T *in)
T * operator= (const SPtr< T > &in)
T * operator= (const SRef< T > &in)
bool operator< (const SPtr< T > &in) const
template<class U> bool operator== (const SPtr< U > &in) const
template<class U> bool operator!= (const SPtr< U > &in) const
T * detach ()
T * getRef ()
T * ptr () const

Detailed Description

template<class T>
class SPtr< T >

This class is the OpenAccess plug-in system smart pointer implementation. It manages the lifetime of plug-in instances that are being used by clients. This is accomplished by the interaction between the SPtr class and the reference count of the plug-in, the latter being accessed through the IBase::addRef and IBase::release member functions. The high level model of the SPtr is that it adds a reference to a component in its constructor, and releases it in the destructor. However, it also has member functions that allow it to work properly as the target in an output parameter, and the assignee in an SRef return value. There are constructors that accomplish various tasks within the plug-in system (see individual descriptions), and operators for testing and comparisons (again, see individual descriptions).

It is highly reccommended that clients use either an SPtr or SQPtr (see below) to hold pointers to interfaces. Among the advantages of using the smart pointer classes is the fact that they clean up the references to any outstanding plug-in interfaces in the case of an exception being thrown through or out of the function holding the interface pointer(s).

Constructor & Destructor Documentation

template<class T>
SPtr< T >::SPtr (    )  [inline]
 

This is the default constructor for the SPtr class. It initializes the internal pointer to NULL.

template<class T>
SPtr< T >::SPtr (  T *    in )  [inline]
 

This constructor takes in a raw interface pointer. It adds a reference to the instance (via the IBase::addRef() function) and stores the pointer value in its internal pointer field.

Parameters:
in A pointer to an interface of type T.

template<class T>
SPtr< T >::SPtr (  const char *    classID,
bool    factory = false
)  [inline]
 

This constructor takes in the name of a plug-in. It passes this name to the plug-in manager to create a new instance of the requested plug-in. It requests an interface pointer of type T. If the plug-in does not implement that interface, the new plug-in instance will be deleted, and the internal pointer of the SPtr is set to NULL.

Parameters:
classID A NULL terminated string representing the name of the plug-in to create.
factory If this parameter is set to true, the SPtr will request a pointer to the plug-in's factory* instead of the plug-in itself. This factory must implement the interface T. This is useful if the factory implements a custom creation interface, or some other interface that is relevent to all instances of this plug-in type (for example, licensing or authorization).

template<class T>
SPtr< T >::SPtr (  const SRef< T > &    in )  [inline, explicit]
 

This constructor takes in an SRef of a matching interface type. This is usually invoked when a function that returns an interface by an SRef is assigned into an SPtr. Since it is the job of the SRef class to preserve the reference count of the plug-in through a function return, the SPtr "takes over" this reference by calling SRef::detach(). See the description of SRef for more details.

Parameters:
in A reference to an SRef object.

template<class T>
SPtr< T >::SPtr (  const SPtr< T > &    in )  [inline]
 

This constructor creates an empty (NULL) smart pointer.

Parameters:
in A reference to another SPtr of the same type.

template<class T>
SPtr< T >::~SPtr (    )  [inline]
 

This is the destructor of the SPtr class. If the internal pointer is not NULL, then it calls IBase::release() to remove the reference on the plug-in instance.

Member Function Documentation

template<class T>
void SPtr< T >::createInstance (  const char *    classID,
IBase *    reserved = NULL
)  [inline]
 

This function takes in the name of a plug-in. It passes this name to the plug-in manager to create a new instance of the requested plug-in. It requests an interface pointer of type T. If the plug-in does not implement that interface, the new plug-in instance will be deleted, and the internal pointer of the SPtr is set to remain unchanged. If this function is successful, the internal pointer is set to the interface pointer of type T from the plug-in instance.

Parameters:
classID A NULL terminated string representing the name of the plug-in to create.
reserved This parameter is for advanced plug-in usage. Normally it should be set to NULL (the default).

template<class T>
T * SPtr< T >::detach (    )  [inline]
 

This function is used to pass control of the interface pointer out of the smart pointer class. It sets its internal pointer to NULL and returns the original value. The reference count is left unchanged.

template<class T>
T * SPtr< T >::getRef (    )  [inline]
 

This function increments the reference count of the plug-in instance and returns the value of the T pointer. It is primarily used in a function that returns an interface pointer via an output parameter. The result of getRef() is suitable for assigning into the output paramater variable. This maintains consistancy with the rule that all interface pointers passed out of a function call must have their reference count incremented by one.

template<class T>
SPtr< T >::operator T *& (    )  const [inline]
 

This operator is invoked under several circumstances. Among the interesting ones are:

  • When the smart pointer is used as an output parameter that takes the form T *&out (where T is the interface type). For these output parameters, an instance of a smart pointer of type T can be used directly as though it were a raw pointer of the appropriate type. If the types don't match, a compiler error is issued.

  • When the smart pointer is being used as a pointer (for example, passed into a fuction via an input parameter of the form T *in).

template<class T>
template<class U>
template< class U > bool SPtr< T >::operator!= (  const SPtr< U > &    in )  const [inline]
 

This operator returns true if the pointers are not the same; otherwise it returns false.

Parameters:
in A reference to another SPtr of arbitrary type.

template<class T>
T * SPtr< T >::operator-> (    )  const [inline]
 

This operator is used to access the member functions of the T interface. It allows the smart pointer to be used with the same syntax as a raw pointer. For example, if myFunction() is a member function of the IMyInterface class: 

   SPtr<IMyInterface>	plugin("MyPlugin");
   
   plugin->myFunction();

template<class T>
bool SPtr< T >::operator< (  const SPtr< T > &    in )  const [inline]
 

This operator returns true if this object is considered to be less than the argument.

Parameters:
in A reference to another SPtr of the same type.

template<class T>
T * SPtr< T >::operator= (  const SRef< T > &    in )  [inline]
 

This assigment operator takes in an SRef of a matching interface type. This is usually invoked when a function that returns an interface by an SRef is assigned into an SPtr. Since it's the job of the SRef class to preserve the reference count of the plug-in through a function return, the SPtr "takes over" this reference by calling SRef::detach(). See the description of SRef for more details.

Parameters:
in A reference to an SRef object.

Reimplemented in SQPtr.

template<class T>
T * SPtr< T >::operator= (  const SPtr< T > &    in )  [inline]
 

Reimplemented in SQPtr.

template<class T>
T * SPtr< T >::operator= (  T *    in )  [inline]
 

This function takes in a raw interface pointer. It adds a reference to the instance (via the IBase::addRef() function) and stores the pointer value in its internal pointer field.

Parameters:
in A pointer to an interface of type T.

Reimplemented in SQPtr.

template<class T>
template<class U>
bool template< class U > SPtr< T >::operator== (  const SPtr< U > &    in )  const [inline]
 

This operator returns true if the pointers are the same; otherwise it returns false.

Parameters:
in A reference to another SPtr of arbitrary type.

template<class T>
T * SPtr< T >::ptr (    )  const [inline]
 

This function simply returns the pointer value of the internal interface pointer. It is usually used to pass the interface pointer into functions where the conversion operators will not be invoked, such as printf().

template<class T>
void SPtr< T >::release (    )  [inline]
 

This function releases the reference on the underlying plug-in instance (see SPtr::~SPtr()) and sets the internal pointer to NULL. It is primarily used to clear a smart pointer prior to being reused, for example, as an output parameter in an interator.

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

Return to top of page




Copyright © 2002 - 2010 Cadence Design Systems, Inc.
All Rights Reserved.