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

/** @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.  Certain
 * operations like constructing from AutoRes objects passed by value are only
 * possible if the object "transitions through" a wrapper struct.
 * See auto_ptr in the C++ <memory> header.
 */
template <class T, void Destruct(T)>
struct RTAutoResRef
{
    T mValue;

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

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

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

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

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

    /** 
     * 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(mValue, cchNewSize));
        if (aNewValue != NULL)
            mValue = aNewValue;
        else
            Destruct(mValue);
        return (aNewValue != NULL);
    }

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

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

    /** 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 (NULL != mValue)
        {
            Destruct(mValue);
        }
        mValue = aValue;
        return *this;
    }

#if 0
    /**
     * @todo I'm not sure how to express this now that our type is T and not
     * T*.  Something like return type *T, which would only be valid for T a
     * pointer type.  Or perhaps easiest to just leave it out.
     */

    /** Dereference with * operator. */
    T &operator*() { return *mValue; }
#endif

    /** Dereference with -> operator.  Only makes sense for pointer values. */
    T operator->() { return mValue; }

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

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

    /** 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 a reference structure. */
    template <class T1>
    operator RTAutoResRef<T1, Destruct>() { return RTAutoResRef<T1, Destruct>(release()); }

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

#endif /* ___iprt_autores___ not defined */