GU/GU_DetailHandle.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Jeff Lait
 *      Side Effects Software Inc
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        GU_DetailHandle.h ( GU Library, C++)
 *
 * COMMENTS:    A detail handle is used to maintain a reference to a 
 *              GU_Detail.  It provides a level of indirection so that
 *              the underlying GU_Detail may be deleted or changed
 *              without those interested in the GU_Detail having to tell.
 *              It also provides write/read lock tests to allow memory
 *              managers to tell what is safe to be deleted.
 */

#ifndef __GU_DetailHandle__
#define __GU_DetailHandle__

#include "GU_API.h"

class GU_Detail;
class GU_DetailHandleRef;

/// A GU_DetailHandle is designed to allow arms length references to 
/// GU_Details.  The underlying GU_Detail can be deleted or swapped
/// and things which use the GU_DetailHandle will properly be notified.
/// Further, it provides access control to the GU_Detail, ensuring multiple
/// entities do not write to it at once.  This is currently used to ensure
/// deletion is not performed on active GU_Details.  Eventually it could
/// be used for multi-threaded support.
class GU_API GU_DetailHandle
{
public:
    GU_DetailHandle();
    GU_DetailHandle(const GU_DetailHandle &handle);

    ~GU_DetailHandle();

    void                 clear();

    const GU_DetailHandle &operator=(const GU_DetailHandle &handle);

    bool                 operator==(const GU_DetailHandle &handle) const;
    bool                 operator!=(const GU_DetailHandle &handle) const;

    /// peekDetail does no locking.  Thus, it should be avoided unless
    /// the goal is just to test if the GU_Detail is present.  This
    /// is largely provided for supporting old code in hackish situations.
    const GU_Detail     *peekDetail() const;

    /// This will acquire a read lock on the GU_Detail.  The result is 0
    /// if no lock can be acquired, or no underlying detail exists.
    /// The returned detail should be passed to unlock().  (Technically,
    /// no locking occurs on error, but unlock is a no-op with a 0 gdp)
    const GU_Detail     *readLock();

    /// This will acquire a write lock on the GU_Detail.  The result is 0
    /// if no lock can be acquired, or no underlying detail is present.
    /// The returned detail should be passed to unlock() when finished.
    /// There can only be one active write lock at a time.  Do not destroy
    /// or modify the pointer itself and expect the unlock to update
    /// the GU_Detail *.  Instead, use one of the delete or change functions.
    /// No readlocks or write locks can be active for this to work.
    GU_Detail           *writeLock();

    /// This will unlock one layer of locking.  
    /// If the passed in gdp is null, no unlocking occurs.
    /// Otherwise, the passed in gdp is asserted to match the one
    /// which myHandle points to.
    void                 unlock(const GU_Detail *gdp);

    /// This changes the underlying gdp of the handle.  The old
    /// gdp is returned.  It is asserted that no locks are active.
    /// If there is an active lock, the passed in gdp is returned.
    GU_Detail           *setGdp(GU_Detail *gdp);

    /// Create a new underlying reference & set it to point to the
    /// given gdp.
    /// The own flag determines if the GU_Detail will be deleted by
    /// the handle system when the underlying reference is deleted.
    void                 allocateAndSet(GU_Detail *gdp, bool own=true);

    /// Deletes the underlying gdp and sets the gdp pointer to be null.
    /// It returns true if the gdp was successfully deleted, false if not.
    /// Failure likely results from a lock being present.
    bool                 deleteGdp();

    /// Determines if anyone has a lock on this handle.
    bool                 hasActiveLock() const;

    /// Determine if this is a null handle.  This means it
    /// points to a null handle, or the handle's gdp is null.
    bool                 isNull() const;

    /// Returns the number of references made to the base handle.
    int                  getRefCount() const;

    /// Preserve Requests:
    /// A preserve request is a request that people create a new
    /// GU_DetailHandle rather than editting the current one.  It
    /// is used by SOPs to determine if it is safe to do an in place
    /// cook.
    void                 addPreserveRequest();
    void                 removePreserveRequest();
    int                  getPreserveRequest() const;

private:
    GU_DetailHandleRef  *myHandle;
};

/// A GU_ConstDetailHandle uses a GU_DetailHandle to provide const-only
/// access to a GU_Detail. It uses a GU_DetailHandle member variable to
/// do all the actual work, and simply hides any functionality that is
/// unsafe or inappropriate for a const GU_Detail.
class GU_API GU_ConstDetailHandle
{
public:
    GU_ConstDetailHandle()
    { }
    GU_ConstDetailHandle(const GU_ConstDetailHandle &handle)
    { myDetailHandle = handle.myDetailHandle; }
    GU_ConstDetailHandle(const GU_DetailHandle &handle)
    { myDetailHandle = handle; }

    ~GU_ConstDetailHandle()
    { }

    const GU_ConstDetailHandle &operator=(const GU_ConstDetailHandle &handle)
    {
        myDetailHandle = handle.myDetailHandle;
        return *this;
    }
    const GU_ConstDetailHandle &operator=(const GU_DetailHandle &handle)
    {
        myDetailHandle = handle;
        return *this;
    }

    bool                 operator==(const GU_ConstDetailHandle &handle) const
    { return myDetailHandle == handle.myDetailHandle; }
    bool                 operator!=(const GU_ConstDetailHandle &handle) const
    { return myDetailHandle != handle.myDetailHandle; }

    // This method casts from a GU_ConstDetailHandle to a GU_DetailHandle.
    // Use it carefully.
    GU_DetailHandle castAwayConst() const
    { return myDetailHandle; }

    /// This will acquire a read lock on the GU_Detail.  The result is 0
    /// if no lock can be acquired, or no underlying detail exists.
    /// The returned detail should be passed to unlock().  (Technically,
    /// no locking occurs on error, but unlock is a no-op with a 0 gdp)
    const GU_Detail     *readLock()
    { return myDetailHandle.readLock(); }

    /// This will unlock one layer of locking.  
    /// If the passed in gdp is null, no unlocking occurs.
    /// Otherwise, the passed in gdp is asserted to match the one
    /// which myHandle points to.
    void                 unlock(const GU_Detail *gdp)
    { myDetailHandle.unlock(gdp); }

    /// Determine if this is a null handle.  This means it
    /// points to a null handle, or the handle's gdp is null.
    bool                 isNull() const
    { return myDetailHandle.isNull(); }

    /// Preserve Requests:
    /// A preserve request is a request that people create a new
    /// GU_DetailHandle rather than editting the current one.  It
    /// is used by SOPs to determine if it is safe to do an in place
    /// cook.
    void                 addPreserveRequest()
                            { myDetailHandle.addPreserveRequest(); }
    void                 removePreserveRequest()
                            { myDetailHandle.removePreserveRequest(); }
    int                  getPreserveRequest() const
                            { return myDetailHandle.getPreserveRequest(); }

private:
    GU_DetailHandle      myDetailHandle;
};

/// GU_DetalHandleAutoFOOLock is a utility class to allow the easy extraction
/// of const GU_Detail * from GU_DetailHandles.  It uses the C++ scoping
/// mechanism to make the locking & unlocking transparent to the caller.
/// One can thus do:
///     GU_DetailHandleAutoFOOLock       gdl(sop->getCookedGeo())
///     const GU_Detail                 *gdp = gdl.getGdp();
/// The FOO = Read returns const GU_Details and does a read lock.
/// The FOO = Write returns non-const GU_Details and does a write lock.
///
class
GU_DetailHandleAutoReadLock
{
public:
    GU_DetailHandleAutoReadLock(const GU_ConstDetailHandle &handle)
    {
        myHandle = handle;
        myGdp = myHandle.readLock();
    }
    GU_DetailHandleAutoReadLock(const GU_DetailHandle &handle)
    {
        myHandle = handle;
        myGdp = myHandle.readLock();
    }
    ~GU_DetailHandleAutoReadLock()
    {
        myHandle.unlock(myGdp);
    }
    
    const GU_Detail     *getGdp() const { return myGdp; }

private:
    GU_ConstDetailHandle         myHandle;
    const GU_Detail             *myGdp;
};

class
GU_DetailHandleAutoWriteLock
{
public:
    GU_DetailHandleAutoWriteLock(const GU_DetailHandle &handle)
    {
        myHandle = handle;
        myGdp = myHandle.writeLock();
    }
    ~GU_DetailHandleAutoWriteLock()
    {
        myHandle.unlock(myGdp);
    }
    
    GU_Detail                   *getGdp() const { return myGdp; }

private:
    GU_DetailHandle              myHandle;
    GU_Detail                   *myGdp;
};

#endif

---