OpenVDB 9.0.0
PointExecutable.h
Go to the documentation of this file.
1// Copyright Contributors to the OpenVDB Project
2// SPDX-License-Identifier: MPL-2.0
3
4/// @file compiler/PointExecutable.h
5///
6/// @authors Nick Avramoussis, Francisco Gochez, Richard Jones
7///
8/// @brief The PointExecutable, produced by the OpenVDB AX Compiler for
9/// execution over OpenVDB Points Grids.
10///
11
12#ifndef OPENVDB_AX_COMPILER_POINT_EXECUTABLE_HAS_BEEN_INCLUDED
13#define OPENVDB_AX_COMPILER_POINT_EXECUTABLE_HAS_BEEN_INCLUDED
14
15#include "CustomData.h"
16#include "AttributeRegistry.h"
17
18#include <openvdb/openvdb.h>
19#include <openvdb/version.h>
21
22#include <unordered_map>
23
24class TestPointExecutable;
25
26namespace llvm {
27class ExecutionEngine;
28class LLVMContext;
29}
30
31namespace openvdb {
33namespace OPENVDB_VERSION_NAME {
34namespace ax {
35
36class Compiler;
37
38/// @brief Object that encapsulates compiled AX code which can be executed on a
39/// collection of VDB Point Data grids. Executables are created by the
40/// compiler and hold the final immutable JIT compiled function and context.
41/// @details The PointExecutable is returned from the ax::Compiler when
42/// compiling AX code for point execution. The class represents a typical AX
43/// executable object; immutable except for execution settings and implements
44/// 'execute' functions which can be called multiple times for arbitrary sets
45/// of inputs. The intended usage of these executables is to configure their
46/// runtime arguments and then call PointExecutable::execute with your VDBs.
47/// For example:
48/// @code
49/// PointExecutable::Ptr exe = compiler.compile<PointExecutable>("@a += 1");
50/// exe->setCreateMissing(false); // fail on missing attributes
51/// exe->setGroupExecution("group1"); // only process points in group1
52/// exe->execute(vdbs); // run on a set of vdb point data grids
53/// exe->execute(points); // run on a single point data grid
54/// @endcode
55///
56/// The setCreateMissing is initialised with specific configurable settings:
57/// - Create Missing: True
58/// By default, create any missing attributes that were accessed
59/// @sa setCreateMissing
60/// - Group Execution: All
61/// By default, process all points regardless of their group membership
62/// @sa setGroupExecution
63/// - Grain size: 1
64/// The default grain sizes passed to the tbb partitioner for leaf level
65/// processing.
66/// @sa setGrainSize
67///
68/// For more in depth information, see the @ref vdbaxcompilerexe documentation.
70{
71public:
72 using Ptr = std::shared_ptr<PointExecutable>;
74
75 /// @brief Copy constructor. Shares the LLVM constructs but deep copies the
76 /// settings. Multiple copies of an executor can be used at the same time
77 /// safely.
79
80 ////////////////////////////////////////////////////////
81
82 /// @brief Run this point executable binary on a target PointDataGrid.
83 /// @details This method reads from the stored settings on the executable
84 /// to determine certain behaviour and runs the JIT compiled function
85 /// across every valid point. Point attributes may be created, deleted
86 /// collapsed or expanded, and points themselves may be added, deleted
87 /// or moved.
88 ///
89 /// This method is thread safe; it can be run concurrently from the same
90 /// PointExecutable instance on different inputs.
91 ///
92 /// @param grid The PointDataGrid to process
93 void execute(points::PointDataGrid& grid) const;
94
95 ////////////////////////////////////////////////////////
96
97 /// @brief Set a specific point group to execute over. The default is none,
98 /// which corresponds to all points. Note that this can also be compiled
99 /// into the AX function using the ingroup("mygroup") method.
100 /// @warning If the group does not exist during execute, a runtime error
101 /// will be thrown.
102 /// @param name The name of the group to execute over
103 void setGroupExecution(const std::string& name);
104 /// @return The points group to be processed. Default is empty, which is
105 /// all points.
106 const std::string& getGroupExecution() const;
107
108 /// @brief Set the behaviour when missing point attributes are accessed.
109 /// Default behaviour is true, which creates them with default initial
110 /// values. If false, a missing attribute runtime error will be thrown
111 /// on missing accesses.
112 /// @param flag Enables or disables the creation of missing attributes
113 void setCreateMissing(const bool flag);
114 /// @return Whether this executable will generate new point attributes.
115 bool getCreateMissing() const;
116
117 /// @brief Set the threading grain size. Default is 1. A value of 0 has the
118 /// effect of disabling multi-threading.
119 /// @param grain The grain size
120 void setGrainSize(const size_t grain);
121 /// @return The current grain size
122 size_t getGrainSize() const;
123
124 ////////////////////////////////////////////////////////
125
126 // foward declaration of settings for this executable
127 struct Settings;
128
129private:
130 friend class Compiler;
131 friend class ::TestPointExecutable;
132
133 /// @brief Constructor, expected to be invoked by the compiler. Should not
134 /// be invoked directly.
135 /// @param context Shared pointer to an llvm:LLVMContext associated with the
136 /// execution engine
137 /// @param engine Shared pointer to an llvm::ExecutionEngine used to build
138 /// functions. Context should be the associated LLVMContext
139 /// @param attributeRegistry Registry of attributes accessed by AX code
140 /// @param customData Custom data which will be shared by this executable.
141 /// It can be used to retrieve external data from within the AX code
142 /// @param functions A map of function names to physical memory addresses
143 /// which were built by llvm using engine
144 /// @param tree The AST linked to this executable. The AST is not stored
145 /// after compilation, but can be used during construction of the exe to
146 /// infer some pre/post processing optimisations.
147 PointExecutable(const std::shared_ptr<const llvm::LLVMContext>& context,
148 const std::shared_ptr<const llvm::ExecutionEngine>& engine,
149 const AttributeRegistry::ConstPtr& attributeRegistry,
150 const CustomData::ConstPtr& customData,
151 const std::unordered_map<std::string, uint64_t>& functions,
152 const ast::Tree& tree);
153
154private:
155 // The Context and ExecutionEngine must exist _only_ for object lifetime
156 // management. The ExecutionEngine must be destroyed before the Context
157 const std::shared_ptr<const llvm::LLVMContext> mContext;
158 const std::shared_ptr<const llvm::ExecutionEngine> mExecutionEngine;
159 const AttributeRegistry::ConstPtr mAttributeRegistry;
160 const CustomData::ConstPtr mCustomData;
161 const std::unordered_map<std::string, uint64_t> mFunctionAddresses;
162 std::unique_ptr<Settings> mSettings;
163};
164
165} // namespace ax
166} // namespace OPENVDB_VERSION_NAME
167} // namespace openvdb
168
169#endif // OPENVDB_AX_COMPILER_POINT_EXECUTABLE_HAS_BEEN_INCLUDED
170
These classes contain lists of expected attributes and volumes which are populated by compiler during...
Access to the CustomData class which can provide custom user user data to the OpenVDB AX Compiler.
Attribute-owned data structure for points. Point attributes are stored in leaf nodes and ordered by v...
Container class that associates a tree with a transform and metadata.
Definition: Grid.h:577
std::shared_ptr< const AttributeRegistry > ConstPtr
Definition: AttributeRegistry.h:42
The compiler class. This holds an llvm context and set of compiler options, and constructs executable...
Definition: Compiler.h:50
std::shared_ptr< const CustomData > ConstPtr
Definition: CustomData.h:38
Object that encapsulates compiled AX code which can be executed on a collection of VDB Point Data gri...
Definition: PointExecutable.h:70
const std::string & getGroupExecution() const
void setCreateMissing(const bool flag)
Set the behaviour when missing point attributes are accessed. Default behaviour is true,...
std::shared_ptr< PointExecutable > Ptr
Definition: PointExecutable.h:72
void execute(points::PointDataGrid &grid) const
Run this point executable binary on a target PointDataGrid.
PointExecutable(const PointExecutable &other)
Copy constructor. Shares the LLVM constructs but deep copies the settings. Multiple copies of an exec...
void setGrainSize(const size_t grain)
Set the threading grain size. Default is 1. A value of 0 has the effect of disabling multi-threading.
void setGroupExecution(const std::string &name)
Set a specific point group to execute over. The default is none, which corresponds to all points....
Definition: Compiler.h:31
Definition: Exceptions.h:13
A Tree is the highest concrete (non-abstract) node in the entire AX AST hierarchy....
Definition: AST.h:562
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h.in:116
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h.in:202