OpenVDB  12.1.0
PointExecutable.h
Go to the documentation of this file.
1 // Copyright Contributors to the OpenVDB Project
2 // SPDX-License-Identifier: Apache-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 #include "AttributeBindings.h"
18 
19 #include <openvdb/openvdb.h>
20 #include <openvdb/version.h>
22 
23 #include <llvm/Config/llvm-config.h>
24 
25 #include <unordered_map>
26 
27 struct TestPointExecutableAcc;
28 
29 namespace llvm {
30 class ExecutionEngine;
31 class LLVMContext;
32 namespace orc {
33 class LLJIT;
34 }
35 }
36 
37 namespace openvdb {
39 namespace OPENVDB_VERSION_NAME {
40 namespace ax {
41 
42 class Compiler;
43 
44 /// @brief Object that encapsulates compiled AX code which can be executed on a
45 /// collection of VDB Point Data grids. Executables are created by the
46 /// compiler and hold the final immutable JIT compiled function and context.
47 /// @details The PointExecutable is returned from the ax::Compiler when
48 /// compiling AX code for point execution. The class represents a typical AX
49 /// executable object; immutable except for execution settings and implements
50 /// 'execute' functions which can be called multiple times for arbitrary sets
51 /// of inputs. The intended usage of these executables is to configure their
52 /// runtime arguments and then call PointExecutable::execute with your VDBs.
53 /// For example:
54 /// @code
55 /// PointExecutable::Ptr exe = compiler.compile<PointExecutable>("@a += 1");
56 /// exe->setCreateMissing(false); // fail on missing attributes
57 /// exe->setGroupExecution("group1"); // only process points in group1
58 /// exe->execute(vdbs); // run on a set of vdb point data grids
59 /// exe->execute(points); // run on a single point data grid
60 /// @endcode
61 ///
62 /// The setCreateMissing is initialised with specific configurable settings:
63 /// - Create Missing: True
64 /// By default, create any missing attributes that were accessed
65 /// @sa setCreateMissing
66 /// - Group Execution: All
67 /// By default, process all points regardless of their group membership
68 /// @sa setGroupExecution
69 /// - Grain size: 1
70 /// The default grain sizes passed to the tbb partitioner for leaf level
71 /// processing.
72 /// @sa setGrainSize
73 ///
74 /// For more in depth information, see the @ref vdbaxcompilerexe documentation.
76 {
77 public:
78  using Ptr = std::shared_ptr<PointExecutable>;
79  ~PointExecutable();
80 
81  /// @brief Copy constructor. Shares the LLVM constructs but deep copies the
82  /// settings. Multiple copies of an executor can be used at the same time
83  /// safely.
84  PointExecutable(const PointExecutable& other);
85 
86  ////////////////////////////////////////////////////////
87 
88  /// @brief Run this point executable binary on a target PointDataGrid.
89  /// @details This method reads from the stored settings on the executable
90  /// to determine certain behaviour and runs the JIT compiled function
91  /// across every valid point. Point attributes may be created, deleted
92  /// collapsed or expanded, and points themselves may be added, deleted
93  /// or moved.
94  ///
95  /// This method is thread safe; it can be run concurrently from the same
96  /// PointExecutable instance on different inputs.
97  ///
98  /// @param grid The PointDataGrid to process
99  void execute(points::PointDataGrid& grid) const;
100 
101  ////////////////////////////////////////////////////////
102 
103  /// @brief Set a specific point group to execute over. The default is none,
104  /// which corresponds to all points. Note that this can also be compiled
105  /// into the AX function using the ingroup("mygroup") method.
106  /// @warning If the group does not exist during execute, a runtime error
107  /// will be thrown.
108  /// @param name The name of the group to execute over
109  void setGroupExecution(const std::string& name);
110  /// @return The points group to be processed. Default is empty, which is
111  /// all points.
112  const std::string& getGroupExecution() const;
113 
114  /// @brief Set the behaviour when missing point attributes are accessed.
115  /// Default behaviour is true, which creates them with default initial
116  /// values. If false, a missing attribute runtime error will be thrown
117  /// on missing accesses.
118  /// @param flag Enables or disables the creation of missing attributes
119  void setCreateMissing(const bool flag);
120  /// @return Whether this executable will generate new point attributes.
121  bool getCreateMissing() const;
122 
123  /// @brief Set the threading grain size. Default is 1. A value of 0 has the
124  /// effect of disabling multi-threading.
125  /// @param grain The grain size
126  void setGrainSize(const size_t grain);
127  /// @return The current grain size
128  size_t getGrainSize() const;
129 
130  /// @brief Set attribute bindings.
131  /// @param bindings A map of attribute bindings to expected names on
132  /// the geometry to be executed over. By default the AX attributes will be
133  /// bound to point attributes of the same name. Supplying bindings
134  /// for a subset of the attributes will leave the others unchanged.
135  /// AX attributes can only bind to a single point attribute and vice versa.
136  /// However, in a single set call these can be swapped e.g. a -> b and b -> a.
137  /// When bindings are overriden through subsequent calls to this function,
138  /// any dangling point attributes will be automatically bound by name.
139  /// To reset these bindings call get function and create a target set of bindings
140  /// for each attribute of name -> name.
141  void setAttributeBindings(const AttributeBindings& bindings);
142  /// @return The current attribute bindings map
143  const AttributeBindings& getAttributeBindings() const;
144 
145  ////////////////////////////////////////////////////////
146 
147  // foward declaration of settings for this executable
148  template <bool> struct Settings;
149 
150  /// @brief Command Line Interface handling for the PointExecutable.
151  /// @details This class wraps the logic for converting commands specific
152  /// to the PointExecutable to the internal Settings. Subsequent
153  /// executables can be initialized from the CLI object that gets created
155  {
156  ~CLI();
157  CLI(CLI&&);
158  CLI& operator=(CLI&&);
159  static CLI create(size_t argc, const char* argv[], bool* used=nullptr);
160  static void usage(std::ostream& os, const bool verbose);
161  private:
162  friend class PointExecutable;
163  CLI();
164  std::unique_ptr<Settings<true>> mSettings;
165  };
166 
167  /// @brief Intialize the Settings of this executables from the CLI object
168  /// @param cli The CLI object
169  void setSettingsFromCLI(const CLI& cli);
170 
171  ////////////////////////////////////////////////////////
172 
173 private:
174  friend class Compiler;
175  friend struct ::TestPointExecutableAcc;
176 
177  /// @brief Private method used in the unit tests
178  bool usesAcceleratedKernel(const points::PointDataTree& tree) const;
179 
180  /// @brief Constructor, expected to be invoked by the compiler. Should not
181  /// be invoked directly.
182  /// @param context Shared pointer to an llvm:LLVMContext associated with the
183  /// execution engine
184  /// @param engine Shared pointer to an llvm::ExecutionEngine used to build
185  /// functions. Context should be the associated LLVMContext
186  /// @param attributeRegistry Registry of attributes accessed by AX code
187  /// @param customData Custom data which will be shared by this executable.
188  /// It can be used to retrieve external data from within the AX code
189  /// @param functions A map of function names to physical memory addresses
190  /// which were built by llvm using engine
191  /// @param tree The AST linked to this executable. The AST is not stored
192  /// after compilation, but can be used during construction of the exe to
193  /// infer some pre/post processing optimisations.
195 #if LLVM_VERSION_MAJOR <= 15
196  const std::shared_ptr<const llvm::LLVMContext>& context,
197  const std::shared_ptr<const llvm::ExecutionEngine>& engine,
198 #else
199  const std::shared_ptr<const llvm::orc::LLJIT>& mExecutionEngine,
200 #endif
201  const AttributeRegistry::ConstPtr& attributeRegistry,
202  const CustomData::ConstPtr& customData,
203  const std::unordered_map<std::string, uint64_t>& functions,
204  const ast::Tree& tree);
205 
206 private:
207 #if LLVM_VERSION_MAJOR <= 15
208  // The Context and ExecutionEngine must exist _only_ for object lifetime
209  // management. The ExecutionEngine must be destroyed before the Context
210  const std::shared_ptr<const llvm::LLVMContext> mContext;
211  const std::shared_ptr<const llvm::ExecutionEngine> mExecutionEngine;
212 #else
213  const std::shared_ptr<const llvm::orc::LLJIT> mExecutionEngine;
214 #endif
215  const AttributeRegistry::ConstPtr mAttributeRegistry;
216  const CustomData::ConstPtr mCustomData;
217  const std::unordered_map<std::string, uint64_t> mFunctionAddresses;
218  std::unique_ptr<Settings<false>> mSettings;
219 };
220 
221 } // namespace ax
222 } // namespace OPENVDB_VERSION_NAME
223 } // namespace openvdb
224 
225 #endif // OPENVDB_AX_COMPILER_POINT_EXECUTABLE_HAS_BEEN_INCLUDED
226 
Definition: FunctionRegistry.h:23
#define OPENVDB_AX_API
Definition: Platform.h:312
A Tree is the highest concrete (non-abstract) node in the entire AX AST hierarchy. It represents an entire conversion of a valid AX string.
Definition: AST.h:562
std::shared_ptr< const CustomData > ConstPtr
Definition: CustomData.h:38
std::shared_ptr< const AttributeRegistry > ConstPtr
Definition: AttributeRegistry.h:43
The Attribute Bindings class is used by the compiled Executables to handle the mapping of AX Attribut...
Object that encapsulates compiled AX code which can be executed on a collection of VDB Point Data gri...
Definition: PointExecutable.h:75
std::shared_ptr< PointExecutable > Ptr
Definition: PointExecutable.h:78
Definition: Exceptions.h:13
Definition: PointExecutable.h:148
Command Line Interface handling for the PointExecutable.
Definition: PointExecutable.h:154
The compiler class. This holds a set of compiler options and constructs executable objects (e...
Definition: Compiler.h:50
These classes contain lists of expected attributes and volumes which are populated by compiler during...
Attribute-owned data structure for points. Point attributes are stored in leaf nodes and ordered by v...
Access to the CustomData class which can provide custom user user data to the OpenVDB AX Compiler...
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h.in:121
Container class that associates a tree with a transform and metadata.
Definition: Grid.h:28
This class wraps an interface for a map of attribute bindings. These map attributes in AX code to con...
Definition: AttributeBindings.h:36
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h.in:218
Definition: Tree.h:194