OpenVDB 13.0.0

Loading...
Searching...
No Matches
FunctionBuilder Struct Reference

The FunctionBuilder class provides a builder pattern framework to allow easy and valid construction of AX functions. There are a number of complex tasks which may need to be performed during construction of C or IR function which are delegated to this builder, whilst ensuring that the constructed functions are guaranteed to be valid. More...

`#include <openvdb_ax/codegen/FunctionTypes.h>`

## Classes
struct | Settings

## Public Types
enum | DeclPreferrence { C , IR , Any }

## Public Member Functions
| FunctionBuilder (const char *name)
template<typename Signature, bool SRet = false>
FunctionBuilder & | addSignature (const Signature *ptr, const char *symbol=nullptr)
template<typename Signature, bool SRet = false>
FunctionBuilder & | addSignature (const IRFunctionBase::GeneratorCb &cb, const char *symbol=nullptr)
template<typename Signature, bool SRet = false>
FunctionBuilder & | addSignature (const IRFunctionBase::GeneratorCb &cb, const Signature *ptr, const char *symbol=nullptr)
template<typename Signature, bool SRet = false>
FunctionBuilder & | addSignature (const IRFunctionBase::GeneratorNativeCb &cb, const char *symbol=nullptr)
template<typename Signature, bool SRet = false>
FunctionBuilder & | addSignature (const IRFunctionBase::GeneratorNativeCb &cb, const Signature *ptr, const char *symbol=nullptr)
template<typename Signature, bool SRet = false>
FunctionBuilder & | addSignature (const IRFunctionBase::GeneratorArgumentsCb &cb, const char *symbol=nullptr)
template<typename Signature, bool SRet = false>
FunctionBuilder & | addSignature (const IRFunctionBase::GeneratorArgumentsCb &cb, const Signature *ptr, const char *symbol=nullptr)
FunctionBuilder & | addDependency (const char *name)
FunctionBuilder & | setEmbedIR (bool on)
FunctionBuilder & | setConstantFold (bool on)
FunctionBuilder & | setArgumentNames (const std::vector< const char * > &names)
FunctionBuilder & | addParameterAttribute (const size_t idx, const llvm::Attribute::AttrKind attr)
| Parameter and Function Attributes. When designing a C binding, llvm will be unable to assign parameter markings to the return type, function body or parameter attributes due to there not being any visibility on the function itself during codegen. The best way to ensure performant C bindings is to ensure that the function is marked with the required llvm parameters.
FunctionBuilder & | addReturnAttribute (const llvm::Attribute::AttrKind attr)
FunctionBuilder & | addFunctionAttribute (const llvm::Attribute::AttrKind attr)
FunctionBuilder & | setReadOnly (const bool on)
| Mark functions currently sharing settings with as "readonly". This enables the strictest possible memory effects for this function in llvm and implies that the function does not write to any memory (i.e. CreateStore) and only reads memory directly from its function arguments (i.e. nothing external to the function). Functions marked as "readonly" but do not adhere to the above will cause UB.
FunctionBuilder & | setBuiltin ()
| Mark functions currently sharing settings as builtin AX methods. At compile time, this causes the IR function body, arguments and return value to be marked with a set of default attributes that apply to all builtin methods, as they are expected to only be called by AX programs. Currently this results in:
FunctionBuilder & | setExternalKernel ()
| Mark this function as an external kernel entry point. Should only be used by the ComputeGenerators. Results in a number of function attributes/parameters being set.
FunctionBuilder & | setDocumentation (const char *doc)
FunctionBuilder & | setPreferredImpl (DeclPreferrence pref)
FunctionGroup::UniquePtr | get () const

## Detailed Description

The FunctionBuilder class provides a builder pattern framework to allow easy and valid construction of AX functions. There are a number of complex tasks which may need to be performed during construction of C or IR function which are delegated to this builder, whilst ensuring that the constructed functions are guaranteed to be valid.

Use the FunctionBuilder::addSignature methods to append function signatures. Finalize the group of functions with FunctionBuilder::get.

## Member Enumeration Documentation

## ◆ DeclPreferrence

enum DeclPreferrence

Enumerator
C |
IR |
Any |

## Constructor & Destructor Documentation

## ◆ FunctionBuilder()

FunctionBuilder | ( | const char * | name | ) |
| inline

## Member Function Documentation

## ◆ addDependency()

FunctionBuilder & addDependency | ( | const char * | name | ) |
| inline

## ◆ addFunctionAttribute()

FunctionBuilder & addFunctionAttribute | ( | const llvm::Attribute::AttrKind | attr | ) |
| inline

## ◆ addParameterAttribute()

FunctionBuilder & addParameterAttribute | ( | const size_t | idx,
|  | const llvm::Attribute::AttrKind | attr )
| inline

Parameter and Function Attributes. When designing a C binding, llvm will be unable to assign parameter markings to the return type, function body or parameter attributes due to there not being any visibility on the function itself during codegen. The best way to ensure performant C bindings is to ensure that the function is marked with the required llvm parameters.

Note
  Some of the most common are shown in FunctionBuilder::setBuiltin, but also consider FunctionBuilder::setReadOnly

## ◆ addReturnAttribute()

FunctionBuilder & addReturnAttribute | ( | const llvm::Attribute::AttrKind | attr | ) |
| inline

## ◆ addSignature() [1/7]

template<typename Signature, bool SRet = false>

FunctionBuilder & addSignature | ( | const IRFunctionBase::GeneratorArgumentsCb & | cb,
|  | const char * | symbol = nullptr )
| inline

## ◆ addSignature() [2/7]

template<typename Signature, bool SRet = false>

FunctionBuilder & addSignature | ( | const IRFunctionBase::GeneratorArgumentsCb & | cb,
|  | const Signature * | ptr,
|  | const char * | symbol = nullptr )
| inline

## ◆ addSignature() [3/7]

template<typename Signature, bool SRet = false>

FunctionBuilder & addSignature | ( | const IRFunctionBase::GeneratorCb & | cb,
|  | const char * | symbol = nullptr )
| inline

## ◆ addSignature() [4/7]

template<typename Signature, bool SRet = false>

FunctionBuilder & addSignature | ( | const IRFunctionBase::GeneratorCb & | cb,
|  | const Signature * | ptr,
|  | const char * | symbol = nullptr )
| inline

## ◆ addSignature() [5/7]

template<typename Signature, bool SRet = false>

FunctionBuilder & addSignature | ( | const IRFunctionBase::GeneratorNativeCb & | cb,
|  | const char * | symbol = nullptr )
| inline

## ◆ addSignature() [6/7]

template<typename Signature, bool SRet = false>

FunctionBuilder & addSignature | ( | const IRFunctionBase::GeneratorNativeCb & | cb,
|  | const Signature * | ptr,
|  | const char * | symbol = nullptr )
| inline

## ◆ addSignature() [7/7]

template<typename Signature, bool SRet = false>

FunctionBuilder & addSignature | ( | const Signature * | ptr,
|  | const char * | symbol = nullptr )
| inline

## ◆ get()

FunctionGroup::UniquePtr get | ( |  | ) | const
| inline

## ◆ setArgumentNames()

FunctionBuilder & setArgumentNames | ( | const std::vector< const char * > & | names | ) |
| inline

## ◆ setBuiltin()

FunctionBuilder & setBuiltin | ( |  | ) |
| inline

Mark functions currently sharing settings as builtin AX methods. At compile time, this causes the IR function body, arguments and return value to be marked with a set of default attributes that apply to all builtin methods, as they are expected to only be called by AX programs. Currently this results in:

Function Attributes: llvm::Attribute::NoFree llvm::Attribute::WillReturn llvm::Attribute::NoRecurse llvm::Attribute::NoUnwind llvm::Attribute::AlwaysInline Return Attributes: - Parameter Attributes (Ptrs): llvm::Attribute::NonNull llvm::Attribute::NoUndef llvm::Attribute::NoFree llvm::Attribute::NoCapture / (llvm::CaptureInfo::none() from LLVM 21)

Warning
  Attributes in this method may be extended - as such, you should mark external function with individual attributes instead of calling this.

## ◆ setConstantFold()

FunctionBuilder & setConstantFold | ( | bool | on | ) |
| inline

## ◆ setDocumentation()

FunctionBuilder & setDocumentation | ( | const char * | doc | ) |
| inline

## ◆ setEmbedIR()

FunctionBuilder & setEmbedIR | ( | bool | on | ) |
| inline

## ◆ setExternalKernel()

FunctionBuilder & setExternalKernel | ( |  | ) |
| inline

Mark this function as an external kernel entry point. Should only be used by the ComputeGenerators. Results in a number of function attributes/parameters being set.

## ◆ setPreferredImpl()

FunctionBuilder & setPreferredImpl | ( | DeclPreferrence | pref | ) |
| inline

## ◆ setReadOnly()

FunctionBuilder & setReadOnly | ( | const bool | on | ) |
| inline

Mark functions currently sharing settings with as "readonly". This enables the strictest possible memory effects for this function in llvm and implies that the function does not write to any memory (i.e. CreateStore) and only reads memory directly from its function arguments (i.e. nothing external to the function). Functions marked as "readonly" but do not adhere to the above will cause UB.

Note
  Obviously invalid for SRET functions!