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
 
void allocateAndSet (GU_Detail *gdp, bool own=true)
 
bool deleteGdp ()
 
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...
 
void addPreserveRequest ()
 
void removePreserveRequest ()
 
int getPreserveRequest () const
 
void addExternalReference ()
 
void removeExternalReference ()
 
int getExternalReference () const
 
int64 getMemoryUsage (bool inclusive) const
 
const GU_DetailreadLock ()
 
GU_DetailwriteLock ()
 
void unlock (const GU_Detail *gdp)
 
bool hasActiveLock () const
 
int getLockCount () const
 

Detailed Description

A GU_DetailHandle is designed to allow arms length references to GU_Details. It acts as a shared pointer that ensures life time of GU_Details will be properly preserved. Further, it provides access control to the GU_Detail, ensuring multiple entities do not write to it at once.

NOTE: The locking methods are historical accidents and are not enforced nor encouraged.

Examples:
field3d/ROP_Field3D.C, packedprim/packedprim.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 38 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. Anything outside of SOPs should always respect uniqueness instead. If storing a handle that comes from SOPs, adding a preserve request will stop SOPs from re-using it.

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:
packedprim/packedprim.C, 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 ( )

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

NOTE: Locking is not enforced, and no longer encouraged. 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

NOTE: Locking is not enforced, and no longer encouraged. 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 61 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 70 of file GU_DetailHandle.h.

bool GU_DetailHandle::isValid ( void  ) const
inline

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

Definition at line 98 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(). For most applications, you should only modify handles that you know are unique to avoid editing geometry stored in caches.

SYS_SAFE_BOOL GU_DetailHandle::operator bool ( ) const
inline

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

Definition at line 101 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

Equivalent to gdp(), peekDetail is left over from when locking was considered important.

const GU_Detail* GU_DetailHandle::readLock ( )

NOTE: Locking is not enforced, and no longer encouraged. 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)

NOTE: Locking is not enforced, and no longer encouraged. 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 ( )

NOTE: Locking is not enforced, and no longer encouraged. 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: