source: vbox/trunk/include/iprt/autores@ 10927

/** @file
 * IPRT - C++ Extensions: resource lifetime management
 */

/*
 * Copyright (C) 2008 Sun Microsystems, Inc.
 *
 * This file is part of VirtualBox Open Source Edition (OSE), as
 * available from http://www.virtualbox.org. This file is free software;
 * you can redistribute it and/or modify it under the terms of the GNU
 * General Public License (GPL) as published by the Free Software
 * Foundation, in version 2 as it comes in the "COPYING" file of the
 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
 *
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 USA or visit http://www.sun.com if you need
 * additional information or have any questions.
 */

#ifndef ___iprt_autores___
# define ___iprt_autores___

#include <iprt/mem.h>

/**
 * Wrapper class around RTAutoRes to provide reference semantics.  This is
 * needed to construct AutoRes objects from constant references to other
 * AutoRes objects (such as temporary objects returned from functions) which
 * can not be modified due to their const modifier, but are not actually
 * constant objects.  See a discussion of auto_ptr and auto_ptr_ref for more
 * details.
 */
template <class T, void Destruct(T)>
struct RTAutoResRef
{
    T mValue;

    explicit RTAutoResRef(T aValue) { mValue = aValue; }
};

/** 
 * An auto pointer-type class for resources which take a C-style destructor
 * destructor (free() or equivalent).
 */
template <class T, void Destruct(T)>
class RTAutoRes
{
private:
    /** The actual resource value */
    T mValue;
public:
    /** Constructor */
    RTAutoRes(T aValue = 0) { mValue = aValue; }

    /** Destructor */
    ~RTAutoRes() { if (mValue != 0) Destruct(mValue); }

    /** Copy constructor */
    RTAutoRes(RTAutoRes &orig) { mValue = orig.release(); }

    /** Copy from equivalent class */
    template <class T1>
    RTAutoRes(RTAutoRes<T1, Destruct> &orig)
    { mValue = orig.release(); }

    /** Convert a reference structure into an AutoRes pointer. */
    RTAutoRes(RTAutoResRef<T, Destruct> ref) { mValue = ref.mValue; }

    /** Assignment operator. */
    RTAutoRes& operator=(RTAutoRes &orig)
    {
        reset(orig.release());
        return *this;
    }

    /** Assignment from equivalent class. */
    template <class T1>
    RTAutoRes& operator=(RTAutoRes<T1, Destruct> &orig)
    {
        reset(orig.release);
        return *this;
    }

    /** Assignment from a value. */
    RTAutoRes& operator=(T aValue)
    {
        if (mValue != 0)
        {
            Destruct(mValue);
        }
        mValue = aValue;
        return *this;
    }

    /** Assign from a reference structure into an AutoRes pointer. */
    RTAutoRes& operator=(RTAutoResRef<T, Destruct> ref)
    {
        if (ref.mValue != mValue)
        {
            Destruct(mValue);
            mValue = ref.mValue;
        }
        return *this;
    }

    /** Typecast an AutoRes pointer to an AutoRes pointer of a different type. */
    template <class T1>
    operator RTAutoRes<T1, Destruct>()
    { return RTAutoRes<T1, Destruct>(release()); }

    /** Typecast an AutoRes pointer to a reference structure. */
    template <class T1>
    operator RTAutoResRef<T1, Destruct>()
    { return RTAutoResRef<T1, Destruct>(release()); }

    /** release method to get the pointer's value and "reset" the pointer. */
    T release(void) { T aTmp = mValue; mValue = 0; return aTmp; }

    /** reset the pointer value to zero or to another pointer. */
    void reset(T aValue = 0) { if (aValue != mValue) { Destruct(mValue); mValue = aValue; } }

    /** Accessing the value inside. */
    T get(void) { return mValue; }
};

/** Re-casting template to convert a void fn(void *) to a void fn(T *) */
template <class T, void fn(void *)>
inline void RTAutoResRecastVoid(T *aValue) { fn(aValue); }

template <class T, void Destruct(T *) = RTAutoResRecastVoid <T, RTMemFree> >
class RTMemAutoPtr : public RTAutoRes <T *, Destruct>
{
public:
    /** Constructor */
    RTMemAutoPtr(T *aValue = NULL) : RTAutoRes <T *, Destruct>(aValue) {}

    /** Copy constructors */
    RTMemAutoPtr(RTMemAutoPtr &orig) : RTAutoRes <T *, Destruct>(orig) {}
    template <class T1>
    RTMemAutoPtr(RTMemAutoPtr<T1, Destruct> &orig) : RTAutoRes<T1 *, Destruct>(orig) {}

    /** Assignment operators */
    RTMemAutoPtr& operator=(RTMemAutoPtr &orig)
    { this->RTAutoRes <T *, Destruct>::operator=(orig); }
    template <class T1>
    RTMemAutoPtr& operator=(RTMemAutoPtr<T1, Destruct> &orig)
    { this->RTAutoRes<T1 *, Destruct>::operator=(orig); return *this; }
    RTMemAutoPtr& operator=(T *aValue)
    { this->RTAutoRes <T *, Destruct>::operator=(aValue); return *this; }
    RTMemAutoPtr& operator=(RTAutoResRef<T *, Destruct> ref)
    { this->RTAutoRes <T *, Destruct>::operator=(ref); return *this; }

    /** Dereference with * operator. */
    T &operator*() { return *this->get(); }

    /** Dereference with -> operator. */
    T* operator->() { return this->get(); }

    /**
     * Reallocate the resource value.  Free the old value if allocation fails.
     * @returns true if the new allocation succeeds, false otherwise
     * @param   Reallocator  the function to be used for reallocating the
     *                       resource.  It should have equivalent semantics to
     *                       C realloc.
     * @note We can overload this member for other reallocator signatures as
     *       needed.
     */
    template <void *Reallocator(void *, size_t)>
    bool realloc(size_t cchNewSize)
    {
        T *aNewValue = reinterpret_cast<T *>(Reallocator(this->release(), cchNewSize));
        if (aNewValue != NULL)  /* This line is technically not necessary */
            this->reset(aNewValue);
        return (aNewValue != NULL);
    }
};

#endif /* ___iprt_autores___ not defined */