OpenVDB 13.0.0

Loading...
Searching...
No Matches
Function Struct Referenceabstract

The base/abstract representation of an AX function. Derived classes must implement the Function::types call to describe their signature. More...

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

Inheritance diagram for Function:

## Public Types
enum | SignatureMatch { None = 0 , Size , Implicit , Ambiguous , Explicit }
| The result type from calls to Function::match. More...
using | Ptr = std::shared_ptr<Function>

## Public Member Functions
| Function (const size_t size, const std::string &symbol)
virtual | ~Function ()=default
virtual ArgInfo | types (ArgInfoVector &, llvm::LLVMContext &) const
| Populate a vector of ArgInfos which describe this function signature. This method is used by Function::create, Function::print and Function::match.
virtual llvm::Type * | types (std::vector< llvm::Type * > &, llvm::LLVMContext &) const =0
virtual llvm::Function * | create (llvm::LLVMContext &C, llvm::Module *M=nullptr) const
| Converts and creates this AX function into a llvm Function.
llvm::Function * | create (llvm::Module &M) const
| Convenience method which always uses the provided module to find the function or insert it if necessary.
llvm::Function * | get (const llvm::Module &M) const
| Convenience method for calling M.getFunction(symbol). Returns a nullptr if the function has not yet been created or if it is embedded IR.
virtual llvm::Value * | call (const std::vector< llvm::Value * > &args, llvm::IRBuilder<> &B, const bool cast) const
| Uses the IRBuilder to create a call to this function with the given arguments, creating the function and inserting it into the IRBuilder's Module if necessary (through Function::create). Returns the result of the function call which can be a nullptr if the function is a non-sret void call.
virtual llvm::Value * | call (const std::vector< llvm::Value * > &args, llvm::IRBuilder<> &B) const
virtual Value | call (const Arguments &args, llvm::IRBuilder<> &B) const
Value | call (const NativeArguments &args, llvm::IRBuilder<> &B) const
virtual SignatureMatch | match (const ArgInfoVector &inputs, llvm::LLVMContext &C) const
| The base implementation for determining how a vector of llvm arguments translates to this functions signature. Returns an enum which represents the available mapping.
virtual SignatureMatch | match (const std::vector< llvm::Type * > &inputs, llvm::LLVMContext &C) const
size_t | size () const
| The number of arguments that this function has.
const char * | symbol () const
| The function symbol name.
const char * | argName (const size_t idx) const
| Returns the descriptive name of the given argument index.
virtual void | print (llvm::LLVMContext &C, std::ostream &os, const char *name=nullptr, const bool axTypes=true) const
| Print this function's signature to the provided ostream.
const SmallArgumentVector< const char * > & | dependencies () const
bool | hasParamAttribute (const size_t i, const llvm::Attribute::AttrKind &kind) const
| Deprecated builder methods, no longer public.
void | setArgumentNames (std::vector< const char * > names)
void | setDependencies (std::vector< const char * > deps)
void | setFnAttributes (const std::vector< llvm::Attribute::AttrKind > &in)
void | setRetAttributes (const std::vector< llvm::Attribute::AttrKind > &in)
void | setParamAttributes (const size_t i, const std::vector< llvm::Attribute::AttrKind > &in)

## Static Protected Member Functions
static void | cast (std::vector< llvm::Value * > &args, const std::vector< llvm::Type * > &types, llvm::IRBuilder<> &B)
| Cast the provided arguments to the given type as supported by implicit casting of function types. If the types already match OR if a cast cannot be performed, nothing is done to the argument.

## Detailed Description

The base/abstract representation of an AX function. Derived classes must implement the Function::types call to describe their signature.

## Member Typedef Documentation

## ◆ Ptr

using Ptr = std::shared_ptr<Function>

## Member Enumeration Documentation

## ◆ SignatureMatch

enum SignatureMatch

The result type from calls to Function::match.

Note
  Function::match cannot return Ambiguous - this is only returned by the FunctionGroup API.

Enumerator
None |
Size |
Implicit |
Ambiguous |
Explicit |

## Constructor & Destructor Documentation

## ◆ Function()

Function | ( | const size_t | size,
|  | const std::string & | symbol )
| inline

## ◆ ~Function()

virtual ~Function | ( |  | ) |
| virtual default

## Member Function Documentation

## ◆ argName()

const char * argName | ( | const size_t | idx | ) | const
| inline

Returns the descriptive name of the given argument index.

If the index is greater than the number of arguments, an empty string is returned.

Parameters

  idx | The index of the argument

## ◆ call() [1/4]

virtual Value call | ( | const Arguments & | args,
|  | llvm::IRBuilder<> & | B ) const
| virtual

Reimplemented in CFunction< SignatureT >, IRFunctionBase, SRetFunction< SignatureT, CFunction< SignatureT > >, and SRetFunction< SignatureT, IRFunction< SignatureT > >.

## ◆ call() [2/4]

Value call | ( | const NativeArguments & | args,
|  | llvm::IRBuilder<> & | B ) const
| inline

## ◆ call() [3/4]

virtual llvm::Value * call | ( | const std::vector< llvm::Value * > & | args,
|  | llvm::IRBuilder<> & | B ) const
| virtual

From LLVM 16 onwards, this version of call does not support argument casting. This must be performed using the NativeArguments struct

Reimplemented in CFunction< SignatureT >, IRFunctionBase, SRetFunction< SignatureT, CFunction< SignatureT > >, and SRetFunction< SignatureT, IRFunction< SignatureT > >.

## ◆ call() [4/4]

virtual llvm::Value * call | ( | const std::vector< llvm::Value * > & | args,
|  | llvm::IRBuilder<> & | B,
|  | const bool | cast ) const
| virtual

Uses the IRBuilder to create a call to this function with the given arguments, creating the function and inserting it into the IRBuilder's Module if necessary (through Function::create). Returns the result of the function call which can be a nullptr if the function is a non-sret void call.

Note
  The IRBuilder must have a valid llvm Module/Function/Block attached
  If the number of provided arguments do not match the size of the current function, invalid IR will be generated.
  If the provided argument types do not match the current function and cast is false, invalid IR will be generated. Additionally, invalid IR will be generated if cast is true but no valid cast exists for a given argument.
  When casting arguments, the readonly flags of the function are not checked (unlike Function::match). Casting an argument will cause a new copy of the argument to be created and passed to the function. These new values do not propagate back any changes to the original argument. Separate functions for all writable argument types must be created.

Parameters

  args | The llvm Value arguments to call this function with
  B | The llvm IRBuilder
  cast | Whether to allow implicit casting of arguments

Deprecated
  "Function::call which takes llvm::Value's and " "supports casting is incompatible with LLVM 16+ and will be removed."

Reimplemented in CFunction< SignatureT >, IRFunctionBase, SRetFunction< SignatureT, CFunction< SignatureT > >, and SRetFunction< SignatureT, IRFunction< SignatureT > >.

## ◆ cast()

void cast | ( | std::vector< llvm::Value * > & | args,
|  | const std::vector< llvm::Type * > & | types,
|  | llvm::IRBuilder<> & | B )
| static protected

Cast the provided arguments to the given type as supported by implicit casting of function types. If the types already match OR if a cast cannot be performed, nothing is done to the argument.

## ◆ create() [1/2]

virtual llvm::Function * create | ( | llvm::LLVMContext & | C,
|  | llvm::Module * | M = nullptr ) const
| virtual

Converts and creates this AX function into a llvm Function.

This method uses the result from Function::types() to construct a llvm::FunctionType and a subsequent a llvm::Function. Any parameter, return or function attributes are also added to the function. If a module is provided, the module if first checked to see if the function already exists. If it does, it is immediately returned. If the function doesn't exist in the module, its prototype is created and also inserted into the end of the modules function list. If no module is provided, the function is left detached and must be added to a valid Module to be callable.

Warning
  If a module is not provided, the caller takes ownership of the returned function and is responsible for deallocating it.

Note
  The body of the function is left to derived classes to implement. As you need a Module to generate the prototype/body, this function serves two purposes. The first is to return the detached function signature if only a context is provided. The second is to ensure the function prototype and body (if required) is inserted into the module prior to returning.
  It is possible to end up with function symbol collisions if you do not have unique function symbols in your module

Parameters

  C | The LLVM Context
  M | The Module to write the function to

Reimplemented in IRFunctionBase.

## ◆ create() [2/2]

llvm::Function * create | ( | llvm::Module & | M | ) | const
| inline

Convenience method which always uses the provided module to find the function or insert it if necessary.

Parameters

  M | The llvm::Module to use

## ◆ dependencies()

const SmallArgumentVector< const char * > & dependencies | ( |  | ) | const
| inline

## ◆ get()

llvm::Function * get | ( | const llvm::Module & | M | ) | const

Convenience method for calling M.getFunction(symbol). Returns a nullptr if the function has not yet been created or if it is embedded IR.

Parameters

  M | The llvm::Module to use

## ◆ hasParamAttribute()

bool hasParamAttribute | ( | const size_t | i,
|  | const llvm::Attribute::AttrKind & | kind ) const
| inline

Deprecated builder methods, no longer public.

Deprecated
  "This method incorrectly returns the attributes " "of the function set by the FunctionBuilder, not by the codegen. To " "inspect function attributes, retrieve the created function from the " "llvm::Module."

## ◆ match() [1/2]

virtual SignatureMatch match | ( | const ArgInfoVector & | inputs,
|  | llvm::LLVMContext & | C ) const
| virtual

The base implementation for determining how a vector of llvm arguments translates to this functions signature. Returns an enum which represents the available mapping.

This method calls types() to figure out the function signature, then compares each argument type to the type in the input vector. If the types match exactly, an Explicit match is found. If the sizes of the inputs and signature differ, no match is found and None is returned. If however, the sizes match and there exists a valid implicit cast from the input type to the signature type for every input, an Implicit match is returned. Finally, if the sizes match but there is no implicit cast mapping, Size is returned. i8 -> i32 : Implicit i32 -> i32 : Explicit str -> i32 : Size (i32,i32) -> i32 : None Never returns Ambiguous (this state is used by FunctionGroup)

Note
  Due to the way CFunctionSRet is implemented, the LLVM Context must be provided in case we have a zero arg function signature with a SRET.

Parameters

  inputs | The input types
  C | The LLVM Context

Reimplemented in SRetFunction< SignatureT, CFunction< SignatureT > >, and SRetFunction< SignatureT, IRFunction< SignatureT > >.

## ◆ match() [2/2]

virtual SignatureMatch match | ( | const std::vector< llvm::Type * > & | inputs,
|  | llvm::LLVMContext & | C ) const
| virtual

Deprecated
  "Switch to AX's internal ArgInfo types for LLVM 16 onwards"

Reimplemented in SRetFunction< SignatureT, CFunction< SignatureT > >, and SRetFunction< SignatureT, IRFunction< SignatureT > >.

## ◆ print()

virtual void print | ( | llvm::LLVMContext & | C,
|  | std::ostream & | os,
|  | const char * | name = nullptr,
|  | const bool | axTypes = true ) const
| virtual

Print this function's signature to the provided ostream.

This is intended to return a descriptive front end user string rather than the function's IR representation. This function is virtual so that derived classes can customize how they present frontend information.

See also
  printSignature

Parameters

  C | The llvm context
  os | The ostream to print to
  name | The name to insert into the description.
  axTypes | Whether to print llvm IR or AX Types.

Reimplemented in SRetFunction< SignatureT, CFunction< SignatureT > >, and SRetFunction< SignatureT, IRFunction< SignatureT > >.

## ◆ setArgumentNames()

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

Deprecated
  "Use the FunctionBuilder to construct Functions"

## ◆ setDependencies()

void setDependencies | ( | std::vector< const char * > | deps | ) |
| inline

Deprecated
  "Use the FunctionBuilder to construct Functions"

## ◆ setFnAttributes()

void setFnAttributes | ( | const std::vector< llvm::Attribute::AttrKind > & | in | ) |
| inline

Deprecated
  "Use the FunctionBuilder to construct Functions"

## ◆ setParamAttributes()

void setParamAttributes | ( | const size_t | i,
|  | const std::vector< llvm::Attribute::AttrKind > & | in )
| inline

Deprecated
  "Use the FunctionBuilder to construct Functions"

## ◆ setRetAttributes()

void setRetAttributes | ( | const std::vector< llvm::Attribute::AttrKind > & | in | ) |
| inline

Deprecated
  "Use the FunctionBuilder to construct Functions"

## ◆ size()

size_t size | ( |  | ) | const
| inline

The number of arguments that this function has.

## ◆ symbol()

const char * symbol | ( |  | ) | const
| inline

The function symbol name.

This will be used as its identifier in IR and must be unique.

## ◆ types() [1/2]

virtual ArgInfo types | ( | ArgInfoVector & | ,
|  | llvm::LLVMContext & | ) const
| inline virtual

Populate a vector of ArgInfos which describe this function signature. This method is used by Function::create, Function::print and Function::match.

Note
  The variant that takes a vector of ArgInfos is optional with LLVM 15 for compatibility but must be implemented with newer versions.

Reimplemented in CFunction< SignatureT >, IRFunction< SignatureT >, SRetFunction< SignatureT, CFunction< SignatureT > >, and SRetFunction< SignatureT, IRFunction< SignatureT > >.

## ◆ types() [2/2]

virtual llvm::Type * types | ( | std::vector< llvm::Type * > & | ,
|  | llvm::LLVMContext & | ) const
| pure virtual

Deprecated
  "Switch to AX's internal ArgInfo types for LLVM 16 onwards"

Implemented in CFunction< SignatureT >, IRFunction< SignatureT >, SRetFunction< SignatureT, CFunction< SignatureT > >, and SRetFunction< SignatureT, IRFunction< SignatureT > >.