Helios++
Helios software for LiDAR simulations
MultiThreadSAHKDTreeFactory Class Reference

Decorator for any SAH KDTree which provides support for multi thread KDTree building. More...

#include <MultiThreadSAHKDTreeFactory.h>

Inheritance diagram for MultiThreadSAHKDTreeFactory:
Collaboration diagram for MultiThreadSAHKDTreeFactory:

Public Member Functions

 MultiThreadSAHKDTreeFactory (shared_ptr< SimpleKDTreeFactory > const kdtf, shared_ptr< SimpleKDTreeGeometricStrategy > const gs, size_t const numJobs=2, size_t const geomJobs=2)
 MultiThreadSAHKDTreeFactory default constructor. More...
 
KDTreeFactoryclone () const override
 
void _clone (KDTreeFactory *kdtf) const override
 Assign attributes from MultiThreadSAHKDTreeFactory to its clone.
 
- Public Member Functions inherited from MultiThreadKDTreeFactory
 MultiThreadKDTreeFactory (shared_ptr< SimpleKDTreeFactory > const kdtf, shared_ptr< SimpleKDTreeGeometricStrategy > const gs, size_t const numJobs=2, size_t const geomJobs=2)
 MultiThreadKDTreeFactory default constructor. More...
 
KDTreeNodeRootmakeFromPrimitivesUnsafe (vector< Primitive * > &primitives, bool const computeStats=false, bool const reportStats=false) override
 Build a KDTree which type depends on current KDTree factory (MultiThreadKDTreeFactory::kdtf) on a multi thread basis. More...
 
virtual shared_ptr< SimpleKDTreeFactorygetKdtf () const
 Obtain the SimpleKDTreeFactory used to build tree nodes. More...
 
virtual size_t getPoolSize () const
 Obtain the pool size of the thread pool (num jobs) More...
 
virtual size_t getNumJobs () const
 Obtain the number of threads for node-level parallelization. More...
 
virtual size_t getGeomJobs () const
 Obtain the number of threads for geometry-level parallelization. More...
 
virtual shared_ptr< SimpleKDTreeGeometricStrategygetGS () const
 Obtain the geometric strategy. More...
 
- Public Member Functions inherited from SimpleKDTreeFactory
 SimpleKDTreeFactory ()
 SimpleKDTreeFactory default constructor. More...
 
KDTreeFactoryclone () const override
 
KDTreeNodeRootmakeFromPrimitivesUnsafe (vector< Primitive * > &primitives, bool const computeStats=false, bool const reportStats=false) override
 Build a simple KDTree from given primitives. More...
 
- Public Member Functions inherited from KDTreeFactory
 KDTreeFactory ()
 K dimensional tree factory default constructor.
 
virtual KDTreeNodeRootmakeFromPrimitives (vector< Primitive * > const &primitives, bool const computeStats=false, bool const reportStats=false)
 Safe wrapper from makeFromPrimitivesUnsafe which handles a copy to make from primitives by default. This function behavior might be overridden by any derived/child class. It is expected that any implementation of makeFromPrimitives provides a way to implement the makeFromPrimitivesUnsafe method without modifying vector of input primitives. Notice this does not mean primitives themselves cannot be modified, that depends on the type of KDTreeFactory. It only means that the vector itself will not be modified, for instance due to sorting purposes. More...
 
virtual bool isBuildingLightNodes ()
 Check if KDTreeFactory is building light nodes. More...
 
virtual void setBuildingLightNodes (bool const buildLightNodes)
 Set KDTreeFactory so it build light nodes (true) or not (false) More...
 
virtual void setChild (LightKDTreeNode *&child, KDTreeNode *node)
 Set child to given node if and only if node is not null. It must be used to assign children nodes in a thread-safe way. More...
 

Protected Attributes

std::shared_ptr< SAHKDTreeFactorysahkdtf
 Pointer to SAH KDTree as a casting of kdtf pointer. More...
 
boost::mutex ilotCacheMutex
 Mutex for the ILOT cache. More...
 
std::unique_ptr< boost::unique_lock< boost::mutex > > ilotCacheLock
 Unique pointer to store unique lock for ILOT cache. More...
 
- Protected Attributes inherited from MultiThreadKDTreeFactory
shared_ptr< SimpleKDTreeFactorykdtf
 The SimpleKDTreeFactory or derived to be used to build tree nodes.
 
shared_ptr< SimpleKDTreeGeometricStrategygs
 The SimpleKDTreeGeometricStrategy or derived to be used to handle geometry-level parallelization during multi-thread KDTree building.
 
KDTreeFactoryThreadPool tpNode
 The thread pool to handle concurrency during recursive KDTree building at node-level.
 
size_t minTaskPrimitives
 The minimum number of primitives on a given split so a new task is started to handle them.
 
int maxGeometryDepth
 The maximum geometry depth level \(d^*\) as explained in the MultiThreadKDTreeFactory::buildRecursiveGeometryLevel It is updated accordingly always that MultiThreadKDTreeFactory::makeFromPrimitivesUnsafe is called. More...
 
size_t numJobs
 The maximum number of jobs (threads/workers) that this factory is allowed to use.
 
size_t geomJobs
 The number of jobs (threads/workers) that this factory must use when building upper KDTree nodes (geometry-level parallelization)
 
shared_ptr< SharedTaskSequencermasters
 All masters threads (except main thread) are handled by this shared task sequencer. More...
 
size_t finishedGeomJobs
 How many geometry-level jobs have fully finished during current KDT building. More...
 
boost::mutex finishedGeomJobsMutex
 Mutex to handle concurrent access to counter of finished geometry-level jobs. More...
 
bool notUsed
 True if the factory has not been used before, false otherwise.
 
- Protected Attributes inherited from SimpleKDTreeFactory
std::function< KDTreeNode *(KDTreeNode *, bool const, vector< Primitive * > &, int const, int const)> _buildRecursive
 The member function as attribute used to recursively build KDTree nodes. By default it will be assigned to the buildRecursive member function but it might be overridden by other implementations. For instance, to wrap the buildRecursive behavior to handle parallel building of KDTrees. More...
 
size_t minSplitPrimitives
 How many primitives are required for a node to be splitted. More...
 
- Protected Attributes inherited from KDTreeFactory
bool buildLightNodes = true
 When it is true, the KDTreeFactory is expected to build light nodes. It is, built KDTree must have a KDTreeRootNode which children are all LightKDTreeNode. When it is false, KDTreeFactory is allowed to build KDTree with KDTreeNode children, which might require more memory. More...
 
LightKDTreeNodeBlockAllocator lkdtnBlockAllocator
 The block allocator to speed-up lighten of KDTree by reducing allocation calls when instantiating multiple LightKDTreeNode. More...
 

Private Member Functions

template<class Archive >
void serialize (Archive &ar, unsigned int const version)
 Serialize a multi thread SAH KDTree factory to a stream of bytes. More...
 

Private Attributes

shared_ptr< SimpleKDTreeFactorykdtf
 The SimpleKDTreeFactory or derived to be used to build tree nodes.
 

Friends

class boost::serialization::access
 

Additional Inherited Members

- Protected Member Functions inherited from MultiThreadKDTreeFactory
KDTreeNodebuildRecursive (KDTreeNode *parent, bool const left, vector< Primitive * > &primitives, int const depth, int const index) override
 Recursively build a KDTree for given primitives using given KDTreeFactory (kdtf). The building of upper nodes is delegated to the MultiThreadKDTreeFactory::buildRecursiveGeometryLevel method, while the building of middle and lower nodes is assumed by the MultiThreadKDTreeFactory::buildRecursiveNodeLevel method. More...
 
KDTreeNodebuildRecursiveGeometryLevel (KDTreeNode *parent, bool const left, vector< Primitive * > &primitives, int const depth, int const index)
 Recursively build a KDTree for given primitives using given KDTreeFactory (kdtf) in a geometry-level parallelization context. The geometry-level parallelization implies distributing threads among splits as uniform as possible, while satisfying the constraint that any split must have at least one associated thread. It is the way to go for building the upper levels of the KDTree. For the sake of understanding, let \(P_i\left[a, b\right]\) note the \(i\)-th split associated to threads from \(a\)-th (inclusive) to \(b\)-th (inclusive). Thus, if \(d\) is said to be the tree depth and \(k\) is the number of threads, then it is possible to modellize the behavior of the geometry level parallel building process as follows: More...
 
void buildChildrenGeometryLevel (KDTreeNode *node, KDTreeNode *parent, vector< Primitive * > const &primitives, int const depth, int const index, vector< Primitive * > &leftPrimitives, vector< Primitive * > &rightPrimitives, int const auxiliarThreads)
 Provide an alternative implementation for the building of left and right children nodes. More...
 
KDTreeNodebuildRecursiveNodeLevel (KDTreeNode *parent, bool const left, vector< Primitive * > &primitives, int const depth, int const index)
 Recursively build a KDTree for given primitives using given KDTreeFactory (kdtf) in a node-level parallelization context. The node-level parallelization implies a one thread per node distribution. While it can be used to build the entire KDTree, at the upper levels it leads to idle threads. This problem is easy to see at the first node (root node), because there is only one node and thus only one thread can be working on it. The same would apply for the second node if the number of threads is \(>2\), because there would be only two working threads while the others will remain idle. However, this is inefficient and can be solved by delegating upper nodes to a geometry-level parallelization strategy instead of a node-level one. More...
 
void computeKDTreeStats (KDTreeNodeRoot *root) const override
 Call the compute KDTree stats method of decorated KDTree factory. More...
 
void reportKDTreeStats (KDTreeNodeRoot *root, vector< Primitive * > const &primitives) const override
 Call the report KDTree stats method of decorated KDTree factory. More...
 
virtual void prepareToMake ()
 Prepare the MultiThreadKDTreeFactory so it is ready to start making a new KDTree. More...
 
virtual void increaseFinishedGeomJobsCount (size_t const amount)
 Increase count of finished geometry-level jobs in a thread safe way. More...
 
- Protected Member Functions inherited from SimpleKDTreeFactory
virtual KDTreeNodebuildRecursiveRecipe (KDTreeNode *parent, bool const left, vector< Primitive * > &primitives, int const depth, int const index, std::function< void(KDTreeNode *node, KDTreeNode *parent, bool const left, vector< Primitive * > const &primitives)> f_computeNodeBoundaries, std::function< void(KDTreeNode *node, KDTreeNode *parent, vector< Primitive * > &primitives, int const depth)> f_defineSplit, std::function< void(vector< Primitive * > const &primitives, int const splitAxis, double const splitPos, vector< Primitive * > &leftPrimitives, vector< Primitive * > &rightPrimitives)> f_populateSplits, std::function< void(KDTreeNode *node, KDTreeNode *parent, vector< Primitive * > const &primitives, int const depth, int const index, vector< Primitive * > &leftPrimitives, vector< Primitive * > &rightPrimitives)> f_buildChildrenNodes)
 The recipe of the recursive building algorithm. It is meant to be used by the SimpleKDTreeFactory::buildRecursive but also by any alternative implementation which shares the same recipe (global logic) but changes the way some parts are computed. For instance, it is used by the MultiThreadKDTreeFactory to handle geometry-level parallelization. More...
 
virtual void defineSplit (KDTreeNode *node, KDTreeNode *parent, vector< Primitive * > &primitives, int const depth) const
 Define the split axis and position for current node. More...
 
virtual void populateSplits (vector< Primitive * > const &primitives, int const splitAxis, double const splitPos, vector< Primitive * > &leftPrimitives, vector< Primitive * > &rightPrimitives) const
 Populate list of primitives for left and right splits from given primitives of node being splitted. More...
 
virtual void buildChildrenNodes (KDTreeNode *node, KDTreeNode *parent, vector< Primitive * > const &primitives, int const depth, int const index, vector< Primitive * > &leftPrimitives, vector< Primitive * > &rightPrimitives)
 Build children nodes for given node. If no children nodes must be built, then the node is configured as a leaf node. More...
 
virtual void computeNodeBoundaries (KDTreeNode *node, KDTreeNode *parent, bool const left, vector< Primitive * > const &primitives) const
 Compute min and max position and surface area of bounding cuboid for given node. More...
 
virtual void onPopulateSplitsDigestPrimitive (Primitive *p, int const splitAxis, double const splitPos, vector< Primitive * > &leftPrimitives, vector< Primitive * > &rightPrimitives) const
 Function to assist SimpleKDTreeFactory::populateSplits by providing the logic of digesting a primitive. More...
 
virtual void computeMinMaxSAHForChild (KDTreeNode *node, KDTreeNode *parent, bool const left, vector< Primitive * > const &primitives) const
 Function to assist SimpleKDTreeFactory::computeNodeBoundaries when computing surface area heuristic and minimum and maximum positions for child nodes. More...
 
virtual void onRootBoundariesDigestPrimitive (Primitive *primitive, double &ax, double &ay, double &az, double &bx, double &by, double &bz) const
 Function to assist SimpleKDTreeFactory::computeNodeBoundaries by providing the logic of digesting a primitive. More...
 
virtual void onComputeNodeBoundariesCalcSAH (KDTreeNode *node, double const ax, double const ay, double const az, double const bx, double const by, double const bz) const
 Function to assist SimpleKDTreeFactory::computeNodeBoundaries when computing the SAH for a node. More...
 
virtual bool checkNodeMustSplit (vector< Primitive * > const &primitives, vector< Primitive * > const &leftPrimitives, vector< Primitive * > const &rightPrimitives) const
 Check wheter the node must be splitted (true) or not (false) depending on its total primitives and the ones that would be assigned to left and right children. More...
 
virtual void makeLeaf (KDTreeNode *node, vector< Primitive * > const &primitives) const
 Make given node a leaf one. More...
 
- Protected Member Functions inherited from KDTreeFactory
virtual void lighten (KDTreeNodeRoot *root)
 Rebuild all children of given root KDTree node as LightKDTeeeNode nodes. More...
 
virtual LightKDTreeNode_lighten (KDTreeNode *node)
 Assist KDTreeFactory::lighten function by handling the lighten of a given non-root node. More...
 

Detailed Description

Decorator for any SAH KDTree which provides support for multi thread KDTree building.

Author
Alberto M. Esmoris Pena
Version
1.0

Constructor & Destructor Documentation

◆ MultiThreadSAHKDTreeFactory()

MultiThreadSAHKDTreeFactory::MultiThreadSAHKDTreeFactory ( shared_ptr< SimpleKDTreeFactory > const  kdtf,
shared_ptr< SimpleKDTreeGeometricStrategy > const  gs,
size_t const  numJobs = 2,
size_t const  geomJobs = 2 
)

MultiThreadSAHKDTreeFactory default constructor.

Parameters
kdtfThe SAH factory to be used to build the KDTree

Member Function Documentation

◆ clone()

KDTreeFactory * MultiThreadSAHKDTreeFactory::clone ( ) const
overridevirtual
See also
KDTreeFactory::clone

Reimplemented from MultiThreadKDTreeFactory.

◆ serialize()

template<class Archive >
void MultiThreadSAHKDTreeFactory::serialize ( Archive &  ar,
unsigned int const  version 
)
inlineprivate

Serialize a multi thread SAH KDTree factory to a stream of bytes.

Template Parameters
ArchiveType of rendering
Parameters
arSpecific rendering for the stream of bytes
versionVersion number for the multi thread SAH K dimensional tree factory

Member Data Documentation

◆ ilotCacheLock

std::unique_ptr<boost::unique_lock<boost::mutex> > MultiThreadSAHKDTreeFactory::ilotCacheLock
protected

◆ ilotCacheMutex

boost::mutex MultiThreadSAHKDTreeFactory::ilotCacheMutex
protected

◆ sahkdtf

std::shared_ptr<SAHKDTreeFactory> MultiThreadSAHKDTreeFactory::sahkdtf
protected

Pointer to SAH KDTree as a casting of kdtf pointer.

See also
MultiThreadKDTreeFactory::kdtf

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