HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
GU_DetailHandle Class Reference

#include <GU_DetailHandle.h>

Public Member Functions

 GU_DetailHandle ()
 
 GU_DetailHandle (const GU_DetailHandle &handle)
 
 GU_DetailHandle (GU_DetailHandle &&handle)
 
 ~GU_DetailHandle ()
 
void clear ()
 
GU_DetailHandle duplicateGeometry (GA_DataIdStrategy data_id_strategy=GA_DATA_ID_BUMP) const
 
GU_DetailHandleoperator= (const GU_DetailHandle &handle)
 
GU_DetailHandleoperator= (GU_DetailHandle &&handle)
 
bool operator== (const GU_DetailHandle &handle) const
 
bool operator!= (const GU_DetailHandle &handle) const
 
uint hash () const
 
void makeUnique (GA_DataIdStrategy data_id_strategy=GA_DATA_ID_BUMP)
 
bool isUnique () const
 
GU_DetailgdpNC ()
 
const GU_Detailgdp () const
 
const GU_DetailpeekDetail () const
 
const GU_DetailreadLock ()
 
GU_DetailwriteLock ()
 
void unlock (const GU_Detail *gdp)
 
void allocateAndSet (GU_Detail *gdp, bool own=true)
 
bool deleteGdp ()
 
bool hasActiveLock () const
 Determines if anyone has a lock on this handle. More...
 
bool isNull () const
 
bool isValid () const
 Determine if this is a valid handle (!isNull()) More...
 
SYS_SAFE_BOOL operator bool () const
 Safe-bool operator to return whether the handle is valid. More...
 
int getRefCount () const
 Returns the number of references made to the base handle. More...
 
int getLockCount () const
 Returns the number of locks made to the base handle for debugging. More...
 
void addPreserveRequest ()
 
void removePreserveRequest ()
 
int getPreserveRequest () const
 
void addExternalReference ()
 
void removeExternalReference ()
 
int getExternalReference () const
 
int64 getMemoryUsage (bool inclusive) const
 

Detailed Description

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. NOTE: The locks are not enforced.

Examples:
field3d/ROP_Field3D.C, packedsphere/GU_PackedSphere.C, SIM/SIM_ForceOrbit.C, SIM/SIM_ForceOrbit.h, SIM/SIM_SolverHair.C, SIM/SNOW_Solver.C, SIM/SNOW_Solver.h, SOP/SOP_BouncyAgent.C, SOP/SOP_DualStar.C, and SOP/SOP_DualStar.h.

Definition at line 35 of file GU_DetailHandle.h.

Constructor & Destructor Documentation

GU_DetailHandle::GU_DetailHandle ( )
GU_DetailHandle::GU_DetailHandle ( const GU_DetailHandle handle)
GU_DetailHandle::GU_DetailHandle ( GU_DetailHandle &&  handle)
GU_DetailHandle::~GU_DetailHandle ( )

Member Function Documentation

void GU_DetailHandle::addExternalReference ( )

External references should not block unload requests at the SOP level. Normally if any external GU_DetailHandles still refer to the handle, unloading is prevented.

void GU_DetailHandle::addPreserveRequest ( )

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 GU_DetailHandle::allocateAndSet ( GU_Detail gdp,
bool  own = true 
)

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.

Examples:
SIM/SIM_SolverHair.C, SIM/SNOW_Solver.C, SOP/SOP_BouncyAgent.C, and SOP/SOP_DualStar.C.
void GU_DetailHandle::clear ( )
Examples:
SIM/SNOW_Solver.C.
bool GU_DetailHandle::deleteGdp ( )

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.

GU_DetailHandle GU_DetailHandle::duplicateGeometry ( GA_DataIdStrategy  data_id_strategy = GA_DATA_ID_BUMP) const

This method will duplicate the geometry associated with the handle, returning a new handle.

const GU_Detail* GU_DetailHandle::gdp ( ) const
GU_Detail* GU_DetailHandle::gdpNC ( )

Unlocked readable & writeable pointers. If acquiring a write pointer, it is expected one will ensure uniqueness prior to acquiring it.

int GU_DetailHandle::getExternalReference ( ) const
int GU_DetailHandle::getLockCount ( ) const

Returns the number of locks made to the base handle for debugging.

int64 GU_DetailHandle::getMemoryUsage ( bool  inclusive) const

Return the amount of memory owned by the GU_DetailHandle itself, NOT the detail. This will count the memory of the GU_DetailHandleRef, which could be shared, so only the definitive "original" handle should be counted, e.g. the one on SOP_Node.

int GU_DetailHandle::getPreserveRequest ( ) const
int GU_DetailHandle::getRefCount ( ) const

Returns the number of references made to the base handle.

bool GU_DetailHandle::hasActiveLock ( ) const

Determines if anyone has a lock on this handle.

uint GU_DetailHandle::hash ( ) const
inline

Compute a hash based on myHandle. This is not on the contents of the gdp!

Definition at line 58 of file GU_DetailHandle.h.

bool GU_DetailHandle::isNull ( ) const

Determine if this is a null handle. This means it points to a null handle, or the handle's gdp is null.

Examples:
SIM/SIM_ForceOrbit.C, and SIM/SNOW_Solver.C.
bool GU_DetailHandle::isUnique ( ) const
inline

Definition at line 65 of file GU_DetailHandle.h.

bool GU_DetailHandle::isValid ( void  ) const
inline

Determine if this is a valid handle (!isNull())

Definition at line 118 of file GU_DetailHandle.h.

void GU_DetailHandle::makeUnique ( GA_DataIdStrategy  data_id_strategy = GA_DATA_ID_BUMP)

Ensures this is the only handle referring to the underlying geometry, ie, getRefCount() == 1. A no-op if the geometry is already unique, otherwise invokes duplicateGeometry().

SYS_SAFE_BOOL GU_DetailHandle::operator bool ( ) const
inline

Safe-bool operator to return whether the handle is valid.

Definition at line 121 of file GU_DetailHandle.h.

GU_DetailHandle& GU_DetailHandle::operator= ( const GU_DetailHandle handle)
GU_DetailHandle& GU_DetailHandle::operator= ( GU_DetailHandle &&  handle)
bool GU_DetailHandle::operator== ( const GU_DetailHandle handle) const
const GU_Detail* GU_DetailHandle::peekDetail ( ) 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* GU_DetailHandle::readLock ( )

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)

void GU_DetailHandle::removeExternalReference ( )
void GU_DetailHandle::removePreserveRequest ( )
void GU_DetailHandle::unlock ( const GU_Detail gdp)

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.

GU_Detail* GU_DetailHandle::writeLock ( )

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.


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