Internal::Function#

class Function#

A reference-counted handle to Halide’s internal representation of a function.

Similar to a front-end Func object, but with no syntactic sugar to help with definitions.

Public Functions

Function() = default#

Construct a new function with no definitions and no name.

This constructor only exists so that you can make vectors of functions, etc.

explicit Function(const std::string &n)#: Construct a new function with the given name.

explicit Function(const std::vector<Type> &required_types, int required_dims, const std::string &n)#

Construct a new function with the given name, with a requirement that it can only represent Expr(s) of the given type(s), and must have exactly the give number of dimensions.

required_types.empty() means there are no constraints on the type(s). required_dims == AnyDims means there are no constraints on the dimensions.

explicit Function(const FunctionPtr&)#

Construct a Function from an existing FunctionContents pointer.

Must be non-null

void update_with_deserialization(const std::string &name, const std::string &origin_name, const std::vector<Halide::Type> &output_types, const std::vector<Halide::Type> &required_types, int required_dims, const std::vector<std::string> &args, const FuncSchedule &func_schedule, const Definition &init_def, const std::vector<Definition> &updates, const std::string &debug_file, const std::vector<Parameter> &output_buffers, const std::vector<ExternFuncArgument> &extern_arguments, const std::string &extern_function_name, NameMangling name_mangling, DeviceAPI device_api, const Expr &extern_proxy_expr, bool trace_loads, bool trace_stores, bool trace_realizations, const std::vector<std::string> &trace_tags, bool no_profiling, const std::string &profiler_display_name, bool frozen, const FunctionPtr &global_wrapper)#: Update a function with deserialized data.

inline FunctionPtr get_contents() const#: Get a handle on the halide function contents that this Function represents.

void deep_copy(const FunctionPtr &copy, std::map<FunctionPtr, FunctionPtr> &copied_map) const#

Deep copy this Function into ‘copy’.

It recursively deep copies all called functions, schedules, update definitions, extern func arguments, specializations, and reduction domains. This method does not deep-copy the Parameter objects. This method also takes a map of <old Function, deep-copied version> as input and would use the deep-copied Function from the map if exists instead of creating a new deep-copy to avoid creating deep-copies of the same Function multiple times. If ‘name’ is specified, copy’s name will be set to that.

void define(const std::vector<std::string> &args, std::vector<Expr> values)#

Add a pure definition to this function.

It may not already have a definition. All the free variables in ‘value’ must appear in the args list. ‘value’ must not depend on any reduction domain

void clear_definition()#

Reset this Function to an undefined state in place (clearing all pure, update, and extern definitions, output types/buffers, and schedule) while preserving the Function’s object identity, so existing references to it remain valid and it can be given a fresh definition with define().

Used by Func::change_type() to turn the original Func into an inline wrapper.

void define_update(const std::vector<Expr> &args, std::vector<Expr> values, const ReductionDomain &rdom = ReductionDomain{})#

Add an update definition to this function.

It must already have a pure definition but not an update definition, and the length of args must match the length of args used in the pure definition. ‘value’ may depend on some reduction domain may contain variables from that domain as well as pure variables. A reduction domain may also be introduced by passing it as the last argument. Any pure variables must also appear as Variables in the args array, and they must have the same name as the pure definition’s argument in the same index.

void accept(IRVisitor *visitor) const#: Accept a visitor to visit all of the definitions and arguments of this function.

void mutate(IRMutator *mutator)#: Accept a mutator to mutator all of the definitions and arguments of this function.

const std::string &name() const#: Get the name of the function.

const std::string &origin_name() const#

If this is a wrapper of another func, created by a chain of in or clone_in calls, returns the name of the original Func.

Otherwise returns the name.

Definition &definition()#: Get a mutable handle to the init definition.

const Definition &definition() const#: Get the init definition.

const std::vector<std::string> &args() const#: Get the pure arguments.

int dimensions() const#: Get the dimensionality.

int outputs() const#: Get the number of outputs.

const std::vector<Type> &output_types() const#: Get the types of the outputs.

const std::vector<Type> &required_types() const#: Get the type constraints on the outputs (if any).

int required_dimensions() const#: Get the dimensionality constraints on the outputs (if any).

const std::vector<Expr> &values() const#

Get the right-hand-side of the pure definition.

Returns an empty vector if there is no pure definition.

Warning: Any Vars in the Exprs are not qualified with the Func name, so the Exprs may contain names which collide with names provided by unique_name.

bool has_pure_definition() const#: Does this function have a pure definition?

inline bool is_pure() const#: Does this function only have a pure definition?

bool can_be_inlined() const#: Is it legal to inline this function?

FuncSchedule &schedule()#: Get a handle to the function-specific schedule for the purpose of modifying it.

const FuncSchedule &schedule() const#: Get a const handle to the function-specific schedule for inspecting it.

const std::vector<Parameter> &output_buffers() const#: Get a handle on the output buffer used for setting constraints on it.

StageSchedule &update_schedule(int idx = 0)#: Get a mutable handle to the stage-specfic schedule for the update stage.

Definition &update(int idx = 0)#: Get a mutable handle to this function’s update definition at index ‘idx’.

const Definition &update(int idx = 0) const#: Get a const reference to this function’s update definition at index ‘idx’.

const std::vector<Definition> &updates() const#: Get a const reference to this function’s update definitions.

bool has_update_definition() const#: Does this function have an update definition?

bool has_extern_definition() const#: Check if the function has an extern definition.

NameMangling extern_definition_name_mangling() const#: Get the name mangling specified for the extern definition.

Expr make_call_to_extern_definition(const std::vector<Expr> &args, const Target &t) const#

Make a call node to the extern definition.

An error if the function has no extern definition.

Expr extern_definition_proxy_expr() const#

Get the proxy Expr for the extern stage.

This is an expression known to have the same data access pattern as the extern stage. It must touch at least all of the memory that the extern stage does, though it is permissible for it to be conservative and touch a superset. For most Functions, including those with extern definitions, this will be an undefined Expr.

void define_extern(const std::string &function_name, const std::vector<ExternFuncArgument> &args, const std::vector<Type> &types, const std::vector<Var> &dims, NameMangling mangling, DeviceAPI device_api)#: Add an external definition of this Func.

const std::vector<ExternFuncArgument> &extern_arguments() const#: Retrieve the arguments of the extern definition.

const std::string &extern_function_name() const#: Get the name of the extern function called for an extern definition.

DeviceAPI extern_function_device_api() const#: Get the DeviceAPI declared for an extern function.

inline bool same_as(const Function &other) const#: Test for equality of identity.

const std::string &debug_file() const#: Get a const handle to the debug filename.

std::string &debug_file()#: Get a handle to the debug filename.

operator ExternFuncArgument() const#: Use an an extern argument to another function.

void trace_loads()#: Tracing calls and accessors, passed down from the Func equivalents.

void lock_loop_levels()#: Replace this Function’s LoopLevels with locked copies that cannot be mutated further.

void do_not_profile()#: Mark the function as too small for meaningful profiling.

bool should_not_profile() const#: Check if the function is marked as one that should not be profiled.

void set_profiler_display_name(const std::string&)#

Override the name shown for this Function in the profiler.

The Function’s internal name (used in IR and as the wrapper-graph key) is unchanged. Used to display auto-generated wrapper Funcs with names that the user will recognize — e.g. “foo (input)” for an input buffer wrapper, or “foo.in(bar)” for a Func::in() wrapper.

const std::string &profiler_display_name() const#: Get the profiler display name; empty if not overridden.

void freeze()#: Mark function as frozen, which means it cannot accept new definitions.

bool frozen() const#

Check if a function has been frozen.

If so, it is an error to add new definitions.

Function new_function_in_same_group(const std::string&)#

Make a new Function with the same lifetime as this one, and return a strong reference to it.

Useful to create Functions which have circular references to this one - e.g. the wrappers produced by Func::in.

void add_wrapper(const std::string &f, Function &wrapper)#

Mark calls of this function by ‘f’ to be replaced with its wrapper during the lowering stage.

If the string ‘f’ is empty, it means replace all calls to this function by all other functions (excluding itself) in the pipeline with the wrapper. This will also freeze ‘wrapper’ to prevent user from updating the values of the Function it wraps via the wrapper. See Func::in for more details.

void set_global_wrapper(Function &wrapper)#

Set / get this Func’s global wrapper (created by Func::in()).

Calls that follow global-wrapper links resolve through it. set_global_wrapper freezes the wrapper and weakens its back-reference to this Func.

const Call *is_wrapper() const#

Check if a Function is a trivial wrapper around another Function, Buffer, or Parameter.

Returns the Call node if it is. Otherwise returns null.

Function &substitute_calls(const std::map<FunctionPtr, FunctionPtr> &substitutions)#

Replace every call to Functions in ‘substitutions’ keys by all Exprs referenced in this Function to call to their substitute Functions (i.e.

the corresponding values in ‘substitutions’ map).

bool is_pure_arg(const std::string &name) const#: Return true iff the name matches one of the Function’s pure args.

void check_types(const Expr &e) const#

If the Function has type requirements, check that the given argument is compatible with them.

If not, assert-fail. (If there are no type requirements, do nothing.)

void check_dims(int dims) const#

If the Function has dimension requirements, check that the given argument is compatible with them.

If not, assert-fail. (If there are no dimension requirements, do nothing.)

void create_output_buffers(const std::vector<Type> &types, int dims) const#

Define the output buffers.

If the Function has types specified, this can be called at any time. If not, it can only be called for a Function with a pure definition.

struct Compare#: This lets you use a Function as a key in a map of the form map<Function, Foo, Function::Compare>.