Detailed Description

template<typename YI_PTR_TYPE>
class CYISharedPtr< YI_PTR_TYPE >

The CYISharedPtr is a smart pointer that takes a shared ownership of a dynamically allocated object. The last instance of CYISharedPtr going out-of-scope will clean up the memory thus avoiding memory leaks.

Deprecated:: This class has been deprecated and may be removed in a future release. The std::shared_ptr class should be used instead.

CYISharedPtr is a very powerful smart pointer for cases where the it isn't clear on who should be cleaning up the memory. It is not as fast as the CYIScopedPointer due to its thread-safety characteristic, but will be very useful in certain cases. As guidance, if this particular instance is never copied and never leaves your class, you should consider using a CYIScopedPtr for performance gain instead.

In the following example ownership is not necessarily clear:

class MyClass
{
private:
     MyData *m_pData;
public:
     MyClass(MyData *pData) : m_data(pData)
     {
     }
};
void main()
{
     MyData obj1(new MyClass());
     MyData obj2(obj1.GetData());
     MyData obj3(obj2.GetData());
     // which one of the three instance should delete MyClass?
} // memory leak occured

The problem can easily be solved using the CYISharedPtr.

Here is how it can be done:

class MyClass
{
private:
     CYISharedPtr<MyData> m_pData;
public:
     MyClass(const CYISharedPtr<MyData> &pData) : m_data(pData)
     {
     }
};
void main()
{
     MyData obj1(CYISharedPtr<MyData>(new MyClass()));
     MyData obj2(obj1.GetData());
     MyData obj3(obj2.GetData());
     // All three objects share ownership of MyClass
} // the last object going out-of-scope will delete MyClass an no memory leaks occured

CYISharedPtr also has an optional custom delete function object that can be overridden to fit your needs. Here is how to use this feature:

class MyCustomDeleteFunctor
{
public:
    void operator()(MyThread *pServices)
    {
         if (pServices)
         {
             pService->Stop();
             delete pService;
         }
    }
};
 class MyClass
 {
 private:
     CYISharedPtr<MyThread> m_pService;
 public:
     MyClass() : m_pService(new MyThread(), MyCustomDeleteFunctor())
     {
         m_pService->Start();
     }
 };

Remarks: CYISharedPtr is thread-safe, with one exception: a single shared pointer instance cannot be read from and written to at the same time. For example, if a shared pointer instance is getting reset at the same time as another instance is being created from it, it results in undefined behaviour. If a shared pointer instance goes out of scope at the same time as another pointer is copying from it, it results in undefined behaviour. Multiple reads from the same shared pointer instance is supported, and multiple writes to the same shared pointer instance is supported.

See also: CYISharedArray; CYIWeakPtr; CYIWeakArray; CYIScopedPtr; CYIScopedArray

#include <smartptr/YiSharedPtr.h>

Inheritance diagram for CYISharedPtr< YI_PTR_TYPE >:

[legend]

Public Member Functions
	CYISharedPtr ()

	CYISharedPtr (YI_PTR_TYPE *pData)

	CYISharedPtr (YI_PTR_TYPE *pData, typename CYICallbackDeleter< YI_PTR_TYPE >::YI_CALLBACK pCallback)

template<typename YI_FUNCTION_OBJECT >
	CYISharedPtr (YI_PTR_TYPE *pData, YI_FUNCTION_OBJECT functor)

template<typename YI_OTHER_TYPE >
	CYISharedPtr (const std::shared_ptr< YI_OTHER_TYPE > &pShared)

template<typename YI_OTHER_PTR_TYPE >
	CYISharedPtr (const CYISharedPtr< YI_OTHER_PTR_TYPE > &rOther)

	CYISharedPtr (const CYIWeakPtr< YI_PTR_TYPE > &rOther)=delete

template<typename YI_OTHER_PTR_TYPE >
	CYISharedPtr (const CYIWeakPtr< YI_OTHER_PTR_TYPE > &rOther)=delete

	~CYISharedPtr ()

void	Reset ()

YI_PTR_TYPE &	operator* () const

YI_PTR_TYPE *	operator-> () const

bool	operator! () const

	operator bool () const

template<typename YI_OTHER_PTR_TYPE >
	operator std::shared_ptr< YI_OTHER_PTR_TYPE > () const

template<typename YI_OTHER_PTR_TYPE >
CYISharedPtr< YI_PTR_TYPE > &	operator= (const std::shared_ptr< YI_OTHER_PTR_TYPE > &rOther)

template<typename YI_OTHER_PTR_TYPE >
CYISharedPtr< YI_PTR_TYPE > &	operator= (const CYISharedPtr< YI_OTHER_PTR_TYPE > &rOther)

CYISharedPtr< YI_PTR_TYPE > &	operator= (const CYIWeakPtr< YI_PTR_TYPE > &rOther)=delete

template<typename YI_OTHER_PTR_TYPE >
CYISharedPtr< YI_PTR_TYPE > &	operator= (const CYIWeakPtr< YI_OTHER_PTR_TYPE > &rOther)=delete

YI_PTR_TYPE *	Get () const

bool	IsNull () const

bool	IsUnique () const

uint32_t	GetUseCount () const

void	Swap (CYISharedPtr< YI_PTR_TYPE > &rPtr)

CYIWeakPtr< YI_PTR_TYPE >	ToWeakPtr () const

template<typename YI_OTHER_PTR_TYPE >
CYISharedPtr< YI_OTHER_PTR_TYPE >	StaticCast () const

template<typename YI_OTHER_PTR_TYPE >
CYISharedPtr< YI_OTHER_PTR_TYPE >	DynamicCast () const

const CYIRuntimeTypeInfo *	GetRuntimeTypeInfo () const

Static Public Member Functions
static const CYIRuntimeTypeInfo &	GetClassTypeInfo ()

Friends
template<typename YI_OTHER_PTR_TYPE >
class	CYIWeakPtr

template<typename YI_OTHER_PTR_TYPE >
class	CYISharedPtr

template<typename YI_OTHER_PTR_TYPE >
class	CYIEnableSharedFromThis

Constructor & Destructor Documentation

template<typename YI_PTR_TYPE>

CYISharedPtr< YI_PTR_TYPE >::CYISharedPtr ( )

Constructs CYISharedPtr and sets its internal object to nullptr

template<typename YI_PTR_TYPE>

CYISharedPtr< YI_PTR_TYPE >::CYISharedPtr ( YI_PTR_TYPE * pData )

explicit

Constructs CYISharedPtr and sets its internal object to the provided parameter

Parameters

pData the data to take shared ownership

template<typename YI_PTR_TYPE>

CYISharedPtr< YI_PTR_TYPE >::CYISharedPtr	(	YI_PTR_TYPE *	pData,
		typename CYICallbackDeleter< YI_PTR_TYPE >::YI_CALLBACK	pCallback
	)

explicit

Constructs CYISharedPtr and sets its internal object to the provided parameter while using a user defined deletion callback.

template<typename YI_PTR_TYPE>

template<typename YI_FUNCTION_OBJECT >

CYISharedPtr< YI_PTR_TYPE >::CYISharedPtr	(	YI_PTR_TYPE *	pData,
		YI_FUNCTION_OBJECT	functor
	)

explicit

Constructs CYISharedPtr and sets its internal object to the provided parameter while using a user defined deletion functor (function object).

template<typename YI_PTR_TYPE>

template<typename YI_OTHER_TYPE >

CYISharedPtr< YI_PTR_TYPE >::CYISharedPtr ( const std::shared_ptr< YI_OTHER_TYPE > & pShared )

Constructs CYISharedPtr and sets its internal object to pShared. The ownership is shared with pShared.

template<typename YI_PTR_TYPE>

template<typename YI_OTHER_PTR_TYPE >

CYISharedPtr< YI_PTR_TYPE >::CYISharedPtr ( const CYISharedPtr< YI_OTHER_PTR_TYPE > & rOther )

Constructs CYISharedPtr and sets its internal object from another CYISharedPtr of a different type

Warning: Make sure the types are compatible since the implementation is making a C-Style cast

Parameters

rOther the pointer to take shared ownership of its object

template<typename YI_PTR_TYPE>

CYISharedPtr< YI_PTR_TYPE >::CYISharedPtr ( const CYIWeakPtr< YI_PTR_TYPE > & rOther )

delete

Constructs CYISharedPtr and sets its internal object from another CYIWeakPtr of the same type

Parameters

rOther the pointer to take shared ownership of its object

template<typename YI_PTR_TYPE>

template<typename YI_OTHER_PTR_TYPE >

CYISharedPtr< YI_PTR_TYPE >::CYISharedPtr ( const CYIWeakPtr< YI_OTHER_PTR_TYPE > & rOther )

delete

Constructs CYISharedPtr and sets its internal object from another CYIWeakPtr of a different type

Warning: Make sure the types are compatible since the implementation is making a C-Style cast

Parameters

rOther the pointer to take shared ownership of its object

template<typename YI_PTR_TYPE>

CYISharedPtr< YI_PTR_TYPE >::~CYISharedPtr ( )

Destructor will only delete m_pData if this instance is the last CYISharedPtr to have a reference to our object

Member Function Documentation

template<typename YI_PTR_TYPE>

template<typename YI_OTHER_PTR_TYPE >

CYISharedPtr<YI_OTHER_PTR_TYPE> CYISharedPtr< YI_PTR_TYPE >::DynamicCast ( ) const

Performs a dynamic cast that shares the reference count. This function can be used for up-casting/down-casting from a base/derived class. If the desired type is incompatible with this CYISharedPtr, it will return a NULL CYISharedPtr.

Code Example :

#include "utilities/YiRtti.h"
class A
{
public:
    virtual ~A() {}
    int32_t m_nAValue;
    YI_TYPE_BASES(A)
};
class B : public A
{
public:
    B() : A() {}
    virtual ~B() {}
    int32_t m_nBValue;
    YI_TYPE_BASES(B, A)
};
class C : public A
{
public:
    C() : A() {}
    virtual ~C() {}
    int32_t m_nCValue;
    YI_TYPE_BASES(C, A)
};
YI_TYPE_DEF(A)
YI_TYPE_DEF(B, A)
YI_TYPE_DEF(C, A)
void Func(const CYISharedPtr<A> &rA)
{
    //Here, let's pretend that we know for sure that rA is either an instance of B or an instance of C, but we don't know which one it is.
    CYISharedPtr<B> b = rA.DynamicCast<B>();
    if (b)
    {
        // Success!
    }
    else
    {
        // So rA wasn't an instance of B, so let's try C
        CYISharedPtr<C> c = rA.DynamicCast<C>();
        if (c)
        {
            // Success!
        }
        else
        {
            // So rA is neither an instance of B nor an instance of C.
        }
    }
}

Warning: This function performs runtime checks. Make sure your objects are using YI_TYPE_BASES from YiRtti.h

template<typename YI_PTR_TYPE>

YI_PTR_TYPE* CYISharedPtr< YI_PTR_TYPE >::Get ( ) const

Accesses the internal object without taking ownership. Mostly for legacy code compatibility.

Example:

void my_legacy_function(MyData *pPtr)
{
   ...
}
void Func()
{
     CYISharedPtr<MyData> pData(new MyData);
     my_legacy_function(pData.Get());
}

Returns: Returns the internal object

template<typename YI_PTR_TYPE>

static const CYIRuntimeTypeInfo& CYISharedPtr< YI_PTR_TYPE >::GetClassTypeInfo ( )

static

A function that returns the YiRTTI type of the type of this shared pointer. The value pointed-to by this shared pointer is ignored.

Warning: Calling this function on a shared pointer that has a non-YiRTTI type will not compile.

template<typename YI_PTR_TYPE>

const CYIRuntimeTypeInfo* CYISharedPtr< YI_PTR_TYPE >::GetRuntimeTypeInfo ( ) const

Convenience function that returns the YiRTTI type of the object. Returns a null pointer if this shared pointer is null.

Instead of calling this:

const CYIRuntimeTypeInfo &type = pSharedPtr.Get()->GetRuntimeTypeInfo();

you can call this instead:

const CYIRuntimeTypeInfo *pType = pSharedPtr.GetRuntimeTypeInfo();

Warning: Calling this function on a non-YiRTTI object will not compile.

template<typename YI_PTR_TYPE>

uint32_t CYISharedPtr< YI_PTR_TYPE >::GetUseCount ( ) const

Returns the number of CYISharedPtr<T> objects that manage the object T.

template<typename YI_PTR_TYPE>

bool CYISharedPtr< YI_PTR_TYPE >::IsNull ( ) const

Syntactic sugar for the operator!()

Example:

void Func()
{
     CYISharedPtr<MyData> pData(new MyData);
     if (pData.IsNull()) // will be false
     {
     }
     ...
     pData.Reset();
     if (pData.IsNull()) // will be true since the internal object is now null.
     {
     }
}

Returns: Returns true if the internal object is null, false otherwise.

template<typename YI_PTR_TYPE>

bool CYISharedPtr< YI_PTR_TYPE >::IsUnique ( ) const

Helper function to determine if this particular instance is the last reference

If this function returns true, it also means that the object will be deleted if this instance goes out-of-scope.

Remarks: CYIWeakPtr does not affect the result of this function.

Returns: Returns true if this is the only reference owning the object, false otherwise.

template<typename YI_PTR_TYPE>

CYISharedPtr< YI_PTR_TYPE >::operator bool ( ) const

This operator tests if the instance is not null.

Example:

void Func()
{
     CYISharedPtr<MyData> pData(new MyData);
     if (pData) // will be true
     {
     }
     ...
     pData.Reset();
     if (pData) // will be false since the internal object is now null.
     {
     }
}

Returns: Returns true if the internal object is not null, false otherwise.

template<typename YI_PTR_TYPE>

template<typename YI_OTHER_PTR_TYPE >

CYISharedPtr< YI_PTR_TYPE >::operator std::shared_ptr< YI_OTHER_PTR_TYPE > ( ) const

template<typename YI_PTR_TYPE>

bool CYISharedPtr< YI_PTR_TYPE >::operator! ( ) const

This operator tests if the instance is null

Example:

void Func()
{
     CYISharedPtr<MyData> pData(new MyData);
     if (!pData) // will be false
     {
     }
     ...
     pData.Reset();
     if (!pData) // will be true since the internal object is now null.
     {
     }
}

Returns: Returns true if the internal object is null, false otherwise.

template<typename YI_PTR_TYPE>

YI_PTR_TYPE& CYISharedPtr< YI_PTR_TYPE >::operator* ( ) const

Dereferences the internal object. If the internal object is null, the behavior is undefined.

Example:

void Func()
{
     CYISharedPtr<MyData> pData(new MyData());
     (*pData).SetValue(42);
     ...
}

Returns: Returns dereferenced internal object

template<typename YI_PTR_TYPE>

YI_PTR_TYPE* CYISharedPtr< YI_PTR_TYPE >::operator-> ( ) const

Directly accesses the internal object's members. If the internal object is null, the behavior is undefined.

Example:

void Func()
{
     CYISharedPtr<MyData> pData(new MyData());
     pData->SetValue(42);
     ...
}

Returns: Returns the internal object

template<typename YI_PTR_TYPE>

template<typename YI_OTHER_PTR_TYPE >

CYISharedPtr<YI_PTR_TYPE>& CYISharedPtr< YI_PTR_TYPE >::operator= ( const std::shared_ptr< YI_OTHER_PTR_TYPE > & rOther )

This function resets the internal object to the one provided as a parameter.

If the previous instance was the last reference of its object, the previous object will be promptly deleted.

Parameters

rOther the pointer to share ownership of its object with.

Returns: Returns itself to allow daisy-chaining

template<typename YI_PTR_TYPE>

template<typename YI_OTHER_PTR_TYPE >

CYISharedPtr<YI_PTR_TYPE>& CYISharedPtr< YI_PTR_TYPE >::operator= ( const CYISharedPtr< YI_OTHER_PTR_TYPE > & rOther )

This function resets the internal object to the one provided as a parameter.

If the previous instance was the last reference of its object, the previous object will be promptly deleted.

Parameters

rOther the pointer to share ownership of its object with.

Returns: Returns itself to allow daisy-chaining

template<typename YI_PTR_TYPE>

CYISharedPtr<YI_PTR_TYPE>& CYISharedPtr< YI_PTR_TYPE >::operator= ( const CYIWeakPtr< YI_PTR_TYPE > & rOther )

delete

This function resets the internal object to the one provided as a parameter.

If the previous instance was the last reference of its object, the previous object will be promptly deleted.

Parameters

rOther the pointer to share ownership of its object with.

Returns: Returns itself to allow daisy-chaining

template<typename YI_PTR_TYPE>

template<typename YI_OTHER_PTR_TYPE >

CYISharedPtr<YI_PTR_TYPE>& CYISharedPtr< YI_PTR_TYPE >::operator= ( const CYIWeakPtr< YI_OTHER_PTR_TYPE > & rOther )

delete

This function resets the internal object to the one provided as a parameter.

If the previous instance was the last reference of its object, the previous object will be promptly deleted.

Parameters

rOther the pointer to share ownership of its object with.

Returns: Returns itself to allow daisy-chaining

template<typename YI_PTR_TYPE>

void CYISharedPtr< YI_PTR_TYPE >::Reset ( )

This function resets the internal object to nullptr.

If the previous instance was the last reference of its object, the previous object will be promptly deleted.

template<typename YI_PTR_TYPE>

template<typename YI_OTHER_PTR_TYPE >

CYISharedPtr<YI_OTHER_PTR_TYPE> CYISharedPtr< YI_PTR_TYPE >::StaticCast ( ) const

Performs a static cast that shares the reference count. This function can be use for up-casting/down-casting from a base/derived class.

Code Example :

class A
{
public:
    virtual ~A() {}
    int32_t m_nAValue;
};
class B : public A
{
public:
    B() : A() {}
    virtual ~B() {}
    int32_t m_nBValue;
};
void Func(const CYISharedPtr<A> &rA)
{
    //Here, let's pretend that we know for sure that rA is an instance of B, since static_cast is unsafe.
    CYISharedPtr<B> b = rA.StaticCast<B>();
}

Warning: static_cast performs no runtime checks. For down-casting, only use this type of cast if you know for sure what the derived class of this pointer is. In the event that you do not know which derived class the pointer type is, use CYISharedPtr::DynamicCast() instead.

template<typename YI_PTR_TYPE>

void CYISharedPtr< YI_PTR_TYPE >::Swap ( CYISharedPtr< YI_PTR_TYPE > & rPtr )

Swap function that will move the ownership of a object to a different CYISharedPtr that could be living in a completely different scope.

Example:

class MyClass
{
private:
     CYISharedPtr<MyData> m_pData;
public:
     MyClass() : m_pData(new MyData())
     {
     }
     void Swap(CYISharedPtr<MyData> &pData)
     {
         m_pData.Swap(pData);  // instance from the class swapped with instance from this function
     }
};

Parameters

rPtr	the CYISharedPtr to swap ownership with

template<typename YI_PTR_TYPE>

CYIWeakPtr<YI_PTR_TYPE> CYISharedPtr< YI_PTR_TYPE >::ToWeakPtr ( ) const

This function generates a weak reference to the object. A weak reference does not take ownership and will never delete the object. It is the user responsibility to make sure that the weak pointer is still valid (not null) when using it.

Example :

void Func(const CYISharedPtr<MyData> &rData)
{
     CYIWeakPtr<MyData> weakPtr = rData.ToWeakPtr();
}

Returns: Returns a weak reference to the object.

See also: CYIWeakPtr

Friends And Related Function Documentation

template<typename YI_PTR_TYPE>

template<typename YI_OTHER_PTR_TYPE >

friend class CYIEnableSharedFromThis

friend

template<typename YI_PTR_TYPE>

template<typename YI_OTHER_PTR_TYPE >

friend class CYISharedPtr

friend

template<typename YI_PTR_TYPE>

template<typename YI_OTHER_PTR_TYPE >

friend class CYIWeakPtr

friend

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

smartptr/YiSharedPtr.h

Detailed Description

template<typename YI_PTR_TYPE> class CYISharedPtr< YI_PTR_TYPE >

Public Member Functions

Static Public Member Functions

Friends

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

template<typename YI_PTR_TYPE>
class CYISharedPtr< YI_PTR_TYPE >