Halide 22.0.0 Halide compiler and libraries

Classes | Public Member Functions | Static Public Member Functions | List of all members
Halide::Pipeline Class Reference

A class representing a Halide pipeline. More...

`#include <Pipeline.h>`

## Classes
struct | RealizationArg

## Public Member Functions
| Pipeline ()
| Make an undefined Pipeline object. More...
| Pipeline (const Func &output)
| Make a pipeline that computes the given Func. More...
| Pipeline (const std::vector< Func > &outputs)
| Make a pipeline that computes the givens Funcs as outputs. More...
| Pipeline (const std::vector< Func > &outputs, const std::vector< Internal::Stmt > &requirements)
| Make a pipeline from deserialization. More...
std::vector< Argument > | infer_arguments (const Internal::Stmt &body)
std::vector< Func > | outputs () const
| Get the Funcs this pipeline outputs. More...
std::vector< Internal::Stmt > | requirements () const
| Get the requirements of this pipeline. More...
AutoSchedulerResults | apply_autoscheduler (const Target &target, const AutoschedulerParams &autoscheduler_params) const
| Generate a schedule for the pipeline using the specified autoscheduler. More...
Func | get_func (size_t index)
| Return handle to the index-th Func within the pipeline based on the topological order. More...
void | compile_to (const std::map< OutputFileType, std::string > &output_files, const std::vector< Argument > &args, const std::string &fn_name, const Target &target)
| Compile and generate multiple target files with single call. More...
void | compile_to_bitcode (const std::string &filename, const std::vector< Argument > &args, const std::string &fn_name, const Target &target=get_target_from_environment())
| Statically compile a pipeline to llvm bitcode, with the given filename (which should probably end in .bc), type signature, and C function name. More...
void | compile_to_llvm_assembly (const std::string &filename, const std::vector< Argument > &args, const std::string &fn_name, const Target &target=get_target_from_environment())
| Statically compile a pipeline to llvm assembly, with the given filename (which should probably end in .ll), type signature, and C function name. More...
void | compile_to_object (const std::string &filename, const std::vector< Argument > &, const std::string &fn_name, const Target &target=get_target_from_environment())
| Statically compile a pipeline with multiple output functions to an object file, with the given filename (which should probably end in .o or .obj), type signature, and C function name (which defaults to the same name as this halide function. More...
void | compile_to_header (const std::string &filename, const std::vector< Argument > &, const std::string &fn_name, const Target &target=get_target_from_environment())
| Emit a header file with the given filename for a pipeline. More...
void | compile_to_assembly (const std::string &filename, const std::vector< Argument > &args, const std::string &fn_name, const Target &target=get_target_from_environment())
| Statically compile a pipeline to text assembly equivalent to the object file generated by compile_to_object. More...
void | compile_to_c (const std::string &filename, const std::vector< Argument > &, const std::string &fn_name, const Target &target=get_target_from_environment())
| Statically compile a pipeline to C source code. More...
void | compile_to_lowered_stmt (const std::string &filename, const std::vector< Argument > &args, StmtOutputFormat fmt=Text, const Target &target=get_target_from_environment())
| Write out an internal representation of lowered code. More...
void | compile_to_conceptual_stmt (const std::string &filename, const std::vector< Argument > &args, StmtOutputFormat fmt=Text, const Target &target=get_target_from_environment())
| Write out a conceptual representation of lowered code, before any parallel loop get factored out into separate functions, or GPU loops are offloaded to kernel code.r Useful for analyzing and debugging scheduling. More...
void | print_loop_nest ()
| Write out the loop nests specified by the schedule for this Pipeline's Funcs. More...
void | compile_to_file (const std::string &filename_prefix, const std::vector< Argument > &args, const std::string &fn_name, const Target &target=get_target_from_environment())
| Compile to object file and header pair, with the given arguments. More...
void | compile_to_static_library (const std::string &filename_prefix, const std::vector< Argument > &args, const std::string &fn_name, const Target &target=get_target_from_environment())
| Compile to static-library file and header pair, with the given arguments. More...
void | compile_to_multitarget_static_library (const std::string &filename_prefix, const std::vector< Argument > &args, const std::vector< Target > &targets)
| Compile to static-library file and header pair once for each target; each resulting function will be considered (in order) via halide_can_use_target_features() at runtime, with the first appropriate match being selected for subsequent use. More...
void | compile_to_multitarget_object_files (const std::string &filename_prefix, const std::vector< Argument > &args, const std::vector< Target > &targets, const std::vector< std::string > &suffixes)
| Like compile_to_multitarget_static_library(), except that the object files are all output as object files (rather than bundled into a static library). More...
Module | compile_to_module (const std::vector< Argument > &args, const std::string &fn_name, const Target &target=get_target_from_environment(), LinkageType linkage_type=LinkageType::ExternalPlusMetadata)
| Create an internal representation of lowered code as a self contained Module suitable for further compilation. More...
void | compile_jit (const Target &target=get_jit_target_from_environment())
| Eagerly jit compile the function to machine code. More...
Callable | compile_to_callable (const std::vector< Argument > &args, const Target &target=get_jit_target_from_environment())
| Eagerly jit compile the function to machine code and return a callable struct that behaves like a function pointer. More...
void | set_jit_externs (const std::map< std::string, JITExtern > &externs)
| Install a set of external C functions or Funcs to satisfy dependencies introduced by HalideExtern and define_extern mechanisms. More...
const std::map< std::string, JITExtern > & | get_jit_externs ()
| Return the map of previously installed externs. More...
JITHandlers & | jit_handlers ()
| Get a struct containing the currently set custom functions used by JIT. More...
template<typename T >
void | add_custom_lowering_pass (T *pass)
| Add a custom pass to be used during lowering. More...
void | add_custom_lowering_pass (Internal::IRMutator *pass, std::function< void()> deleter)
| Add a custom pass to be used during lowering, with the function that will be called to delete it also passed in. More...
void | clear_custom_lowering_passes ()
| Remove all previously-set custom lowering passes. More...
const std::vector< CustomLoweringPass > & | custom_lowering_passes ()
| Get the custom lowering passes. More...
Realization | realize (std::vector< int32_t > sizes={}, const Target &target=Target())
| See Func::realize. More...
Realization | realize (JITUserContext *context, std::vector< int32_t > sizes={}, const Target &target=Target())
| Same as above, but takes a custom user-provided context to be passed to runtime functions. More...
void | realize (RealizationArg output, const Target &target=Target())
| Evaluate this Pipeline into an existing allocated buffer or buffers. More...
void | realize (JITUserContext *context, RealizationArg output, const Target &target=Target())
| Same as above, but takes a custom user-provided context to be passed to runtime functions. More...
void | infer_input_bounds (const std::vector< int32_t > &sizes, const Target &target=get_jit_target_from_environment())
| For a given size of output, or a given set of output buffers, determine the bounds required of all unbound ImageParams referenced. More...
void | infer_input_bounds (RealizationArg output, const Target &target=get_jit_target_from_environment())
void | infer_input_bounds (JITUserContext *context, const std::vector< int32_t > &sizes, const Target &target=get_jit_target_from_environment())
| Variants of infer_inputs_bounds that take a custom user context. More...
void | infer_input_bounds (JITUserContext *context, RealizationArg output, const Target &target=get_jit_target_from_environment())
std::vector< Argument > | infer_arguments ()
| Infer the arguments to the Pipeline, sorted into a canonical order: all buffers (sorted alphabetically by name), followed by all non-buffers (sorted alphabetically by name). More...
bool | defined () const
| Check if this pipeline object is defined. More...
void | invalidate_cache ()
| Invalidate any internal cached state, e.g. More...
void | add_requirement (const Expr &condition, const std::vector< Expr > &error_args)
| Add a top-level precondition to the generated pipeline, expressed as a boolean Expr. More...
template<typename... Args, typename = std::enable_if_t<Internal::all_are_printable_args<Args...>::value>>
HALIDE_NO_USER_CODE_INLINE void | add_requirement (const Expr &condition, Args &&...error_args)
void | trace_pipeline ()
| Generate begin_pipeline and end_pipeline tracing calls for this pipeline. More...

## Static Public Member Functions
static void | add_autoscheduler (const std::string &autoscheduler_name, const AutoSchedulerFn &autoscheduler)
| Add a new the autoscheduler method with the given name. More...

## Detailed Description

A class representing a Halide pipeline.

Constructed from the Func or Funcs that it outputs.

Definition at line 107 of file Pipeline.h.

## Constructor & Destructor Documentation

## ◆ Pipeline() [1/4]

Halide::Pipeline::Pipeline | ( |  | ) |

Make an undefined Pipeline object.

## ◆ Pipeline() [2/4]

Halide::Pipeline::Pipeline | ( | const Func & | output | ) |

Make a pipeline that computes the given Func.

Schedules the Func compute_root().

## ◆ Pipeline() [3/4]

Halide::Pipeline::Pipeline | ( | const std::vector< Func > & | outputs | ) |

Make a pipeline that computes the givens Funcs as outputs.

Schedules the Funcs compute_root().

## ◆ Pipeline() [4/4]

Halide::Pipeline::Pipeline | ( | const std::vector< Func > & | outputs,
|  | const std::vector< Internal::Stmt > & | requirements
| ) |  |

Make a pipeline from deserialization.

## Member Function Documentation

## ◆ infer_arguments() [1/2]

std::vector< Argument > Halide::Pipeline::infer_arguments | ( | const Internal::Stmt & | body | ) |

Referenced by check_call_graphs().

## ◆ outputs()

std::vector< Func > Halide::Pipeline::outputs | ( |  | ) | const

Get the Funcs this pipeline outputs.

## ◆ requirements()

std::vector< Internal::Stmt > Halide::Pipeline::requirements | ( |  | ) | const

Get the requirements of this pipeline.

## ◆ apply_autoscheduler()

AutoSchedulerResults Halide::Pipeline::apply_autoscheduler | ( | const Target & | target,
|  | const AutoschedulerParams & | autoscheduler_params
| ) |  | const

Generate a schedule for the pipeline using the specified autoscheduler.

## ◆ add_autoscheduler()

static void Halide::Pipeline::add_autoscheduler | ( | const std::string & | autoscheduler_name,
|  | const AutoSchedulerFn & | autoscheduler
| ) |  |
| static

Add a new the autoscheduler method with the given name.

Does not affect the current default autoscheduler. It is an error to call this with the same name multiple times.

## ◆ get_func()

Func Halide::Pipeline::get_func | ( | size_t | index | ) |

Return handle to the index-th Func within the pipeline based on the topological order.

Referenced by apply_schedule_included_schedule_file(), and do_cost_model_schedule().

## ◆ compile_to()

void Halide::Pipeline::compile_to | ( | const std::map< OutputFileType, std::string > & | output_files,
|  | const std::vector< Argument > & | args,
|  | const std::string & | fn_name,
|  | const Target & | target
| ) |  |

Compile and generate multiple target files with single call.

Deduces target files based on filenames specified in output_files map.

## ◆ compile_to_bitcode()

void Halide::Pipeline::compile_to_bitcode | ( | const std::string & | filename,
|  | const std::vector< Argument > & | args,
|  | const std::string & | fn_name,
|  | const Target & | target = `get_target_from_environment()`
| ) |  |

Statically compile a pipeline to llvm bitcode, with the given filename (which should probably end in .bc), type signature, and C function name.

If you're compiling a pipeline with a single output Func, see also Func::compile_to_bitcode.

## ◆ compile_to_llvm_assembly()

void Halide::Pipeline::compile_to_llvm_assembly | ( | const std::string & | filename,
|  | const std::vector< Argument > & | args,
|  | const std::string & | fn_name,
|  | const Target & | target = `get_target_from_environment()`
| ) |  |

Statically compile a pipeline to llvm assembly, with the given filename (which should probably end in .ll), type signature, and C function name.

If you're compiling a pipeline with a single output Func, see also Func::compile_to_llvm_assembly.

## ◆ compile_to_object()

void Halide::Pipeline::compile_to_object | ( | const std::string & | filename,
|  | const std::vector< Argument > & | ,
|  | const std::string & | fn_name,
|  | const Target & | target = `get_target_from_environment()`
| ) |  |

Statically compile a pipeline with multiple output functions to an object file, with the given filename (which should probably end in .o or .obj), type signature, and C function name (which defaults to the same name as this halide function.

You probably don't want to use this directly; call compile_to_static_library or compile_to_file instead.

## ◆ compile_to_header()

void Halide::Pipeline::compile_to_header | ( | const std::string & | filename,
|  | const std::vector< Argument > & | ,
|  | const std::string & | fn_name,
|  | const Target & | target = `get_target_from_environment()`
| ) |  |

Emit a header file with the given filename for a pipeline.

The header will define a function with the type signature given by the second argument, and a name given by the third. You don't actually have to have defined any of these functions yet to call this. You probably don't want to use this directly; call compile_to_static_library or compile_to_file instead.

## ◆ compile_to_assembly()

void Halide::Pipeline::compile_to_assembly | ( | const std::string & | filename,
|  | const std::vector< Argument > & | args,
|  | const std::string & | fn_name,
|  | const Target & | target = `get_target_from_environment()`
| ) |  |

Statically compile a pipeline to text assembly equivalent to the object file generated by compile_to_object.

This is useful for checking what Halide is producing without having to disassemble anything, or if you need to feed the assembly into some custom toolchain to produce an object file.

## ◆ compile_to_c()

void Halide::Pipeline::compile_to_c | ( | const std::string & | filename,
|  | const std::vector< Argument > & | ,
|  | const std::string & | fn_name,
|  | const Target & | target = `get_target_from_environment()`
| ) |  |

Statically compile a pipeline to C source code.

This is useful for providing fallback code paths that will compile on many platforms. Vectorization will fail, and parallelization will produce serial code.

## ◆ compile_to_lowered_stmt()

void Halide::Pipeline::compile_to_lowered_stmt | ( | const std::string & | filename,
|  | const std::vector< Argument > & | args,
|  | StmtOutputFormat | fmt = `Text`,
|  | const Target & | target = `get_target_from_environment()`
| ) |  |

Write out an internal representation of lowered code.

Useful for analyzing and debugging scheduling. Can emit html or plain text.

## ◆ compile_to_conceptual_stmt()

void Halide::Pipeline::compile_to_conceptual_stmt | ( | const std::string & | filename,
|  | const std::vector< Argument > & | args,
|  | StmtOutputFormat | fmt = `Text`,
|  | const Target & | target = `get_target_from_environment()`
| ) |  |

Write out a conceptual representation of lowered code, before any parallel loop get factored out into separate functions, or GPU loops are offloaded to kernel code.r Useful for analyzing and debugging scheduling.

Can emit html or plain text.

## ◆ print_loop_nest()

void Halide::Pipeline::print_loop_nest | ( |  | ) |

Write out the loop nests specified by the schedule for this Pipeline's Funcs.

Helpful for understanding what a schedule is doing.

## ◆ compile_to_file()

void Halide::Pipeline::compile_to_file | ( | const std::string & | filename_prefix,
|  | const std::vector< Argument > & | args,
|  | const std::string & | fn_name,
|  | const Target & | target = `get_target_from_environment()`
| ) |  |

Compile to object file and header pair, with the given arguments.

## ◆ compile_to_static_library()

void Halide::Pipeline::compile_to_static_library | ( | const std::string & | filename_prefix,
|  | const std::vector< Argument > & | args,
|  | const std::string & | fn_name,
|  | const Target & | target = `get_target_from_environment()`
| ) |  |

Compile to static-library file and header pair, with the given arguments.

## ◆ compile_to_multitarget_static_library()

void Halide::Pipeline::compile_to_multitarget_static_library | ( | const std::string & | filename_prefix,
|  | const std::vector< Argument > & | args,
|  | const std::vector< Target > & | targets
| ) |  |

Compile to static-library file and header pair once for each target; each resulting function will be considered (in order) via halide_can_use_target_features() at runtime, with the first appropriate match being selected for subsequent use.

This is typically useful for specializations that may vary unpredictably by machine (e.g., SSE4.1/AVX/AVX2 on x86 desktop machines). All targets must have identical arch-os-bits.

## ◆ compile_to_multitarget_object_files()

void Halide::Pipeline::compile_to_multitarget_object_files | ( | const std::string & | filename_prefix,
|  | const std::vector< Argument > & | args,
|  | const std::vector< Target > & | targets,
|  | const std::vector< std::string > & | suffixes
| ) |  |

Like compile_to_multitarget_static_library(), except that the object files are all output as object files (rather than bundled into a static library).

`suffixes` is an optional list of strings to use for as the suffix for each object file. If nonempty, it must be the same length as `targets`. (If empty, Target::to_string() will be used for each suffix.)

Note that if `targets.size()` > 1, the wrapper code (to select the subtarget) will be generated with the filename `${filename_prefix}_wrapper.o`

Note that if `targets.size()` > 1 and `no_runtime` is not specified, the runtime will be generated with the filename `${filename_prefix}_runtime.o`

## ◆ compile_to_module()

Module Halide::Pipeline::compile_to_module | ( | const std::vector< Argument > & | args,
|  | const std::string & | fn_name,
|  | const Target & | target = `get_target_from_environment()`,
|  | LinkageType | linkage_type = `LinkageType::ExternalPlusMetadata`
| ) |  |

Create an internal representation of lowered code as a self contained Module suitable for further compilation.

Referenced by check_call_graphs().

## ◆ compile_jit()

void Halide::Pipeline::compile_jit | ( | const Target & | target = `get_jit_target_from_environment()` | ) |

Eagerly jit compile the function to machine code.

This normally happens on the first call to realize. If you're running your halide pipeline inside time-sensitive code and wish to avoid including the time taken to compile a pipeline, then you can call this ahead of time. Default is to use the Target returned from Halide::get_jit_target_from_environment()

## ◆ compile_to_callable()

Callable Halide::Pipeline::compile_to_callable | ( | const std::vector< Argument > & | args,
|  | const Target & | target = `get_jit_target_from_environment()`
| ) |  |

Eagerly jit compile the function to machine code and return a callable struct that behaves like a function pointer.

The calling convention will exactly match that of an AOT-compiled version of this Func with the same Argument list.

## ◆ set_jit_externs()

void Halide::Pipeline::set_jit_externs | ( | const std::map< std::string, JITExtern > & | externs | ) |

Install a set of external C functions or Funcs to satisfy dependencies introduced by HalideExtern and define_extern mechanisms.

These will be used by calls to realize, infer_bounds, and compile_jit.

## ◆ get_jit_externs()

const std::map< std::string, JITExtern > & Halide::Pipeline::get_jit_externs | ( |  | ) |

Return the map of previously installed externs.

Is an empty map unless set otherwise.

## ◆ jit_handlers()

JITHandlers & Halide::Pipeline::jit_handlers | ( |  | ) |

Get a struct containing the currently set custom functions used by JIT.

This can be mutated. Changes will take effect the next time this Pipeline is realized.

## ◆ add_custom_lowering_pass() [1/2]

template<typename T >

void Halide::Pipeline::add_custom_lowering_pass | ( | T * | pass | ) |
| inline

Add a custom pass to be used during lowering.

It is run after all other lowering passes. Can be used to verify properties of the lowered Stmt, instrument it with extra code, or otherwise modify it. The Func takes ownership of the pass, and will call delete on it when the Func goes out of scope. So don't pass a stack object, or share pass instances between multiple Funcs.

Definition at line 387 of file Pipeline.h.

References add_custom_lowering_pass().

Referenced by add_custom_lowering_pass(), and check_call_graphs().

## ◆ add_custom_lowering_pass() [2/2]

void Halide::Pipeline::add_custom_lowering_pass | ( | Internal::IRMutator * | pass,
|  | std::function< void()> | deleter
| ) |  |

Add a custom pass to be used during lowering, with the function that will be called to delete it also passed in.

Set it to nullptr if you wish to retain ownership of the object.

## ◆ clear_custom_lowering_passes()

void Halide::Pipeline::clear_custom_lowering_passes | ( |  | ) |

Remove all previously-set custom lowering passes.

## ◆ custom_lowering_passes()

const std::vector< CustomLoweringPass > & Halide::Pipeline::custom_lowering_passes | ( |  | ) |

Get the custom lowering passes.

## ◆ realize() [1/4]

Realization Halide::Pipeline::realize | ( | std::vector< int32_t > | sizes = `{}`,
|  | const Target & | target = `Target()`
| ) |  |

See Func::realize.

Referenced by Halide::Internal::GeneratorBase::realize().

## ◆ realize() [2/4]

Realization Halide::Pipeline::realize | ( | JITUserContext * | context,
|  | std::vector< int32_t > | sizes = `{}`,
|  | const Target & | target = `Target()`
| ) |  |

Same as above, but takes a custom user-provided context to be passed to runtime functions.

A nullptr context is legal, and is equivalent to calling the variant of realize that does not take a context.

## ◆ realize() [3/4]

void Halide::Pipeline::realize | ( | RealizationArg | output,
|  | const Target & | target = `Target()`
| ) |  |

Evaluate this Pipeline into an existing allocated buffer or buffers.

If the buffer is also one of the arguments to the function, strange things may happen, as the pipeline isn't necessarily safe to run in-place. The realization should contain one Buffer per tuple component per output Func. For each individual output Func, all Buffers must have the same shape, but the shape can vary across the different output Funcs. This form of realize does not automatically copy data back from the GPU.

## ◆ realize() [4/4]

void Halide::Pipeline::realize | ( | JITUserContext * | context,
|  | RealizationArg | output,
|  | const Target & | target = `Target()`
| ) |  |

Same as above, but takes a custom user-provided context to be passed to runtime functions.

A nullptr context is legal, and is equivalent to calling the variant of realize that does not take a context.

## ◆ infer_input_bounds() [1/4]

void Halide::Pipeline::infer_input_bounds | ( | const std::vector< int32_t > & | sizes,
|  | const Target & | target = `get_jit_target_from_environment()`
| ) |  |

For a given size of output, or a given set of output buffers, determine the bounds required of all unbound ImageParams referenced.

Communicates the result by allocating new buffers of the appropriate size and binding them to the unbound ImageParams.

## ◆ infer_input_bounds() [2/4]

void Halide::Pipeline::infer_input_bounds | ( | RealizationArg | output,
|  | const Target & | target = `get_jit_target_from_environment()`
| ) |  |

## ◆ infer_input_bounds() [3/4]

void Halide::Pipeline::infer_input_bounds | ( | JITUserContext * | context,
|  | const std::vector< int32_t > & | sizes,
|  | const Target & | target = `get_jit_target_from_environment()`
| ) |  |

Variants of infer_inputs_bounds that take a custom user context.

## ◆ infer_input_bounds() [4/4]

void Halide::Pipeline::infer_input_bounds | ( | JITUserContext * | context,
|  | RealizationArg | output,
|  | const Target & | target = `get_jit_target_from_environment()`
| ) |  |

## ◆ infer_arguments() [2/2]

std::vector< Argument > Halide::Pipeline::infer_arguments | ( |  | ) |

Infer the arguments to the Pipeline, sorted into a canonical order: all buffers (sorted alphabetically by name), followed by all non-buffers (sorted alphabetically by name).

This lets you write things like:

pipeline.compile_to_assembly("/dev/stdout", pipeline.infer_arguments());

## ◆ defined()

bool Halide::Pipeline::defined | ( |  | ) | const

Check if this pipeline object is defined.

That is, does it have any outputs?

## ◆ invalidate_cache()

void Halide::Pipeline::invalidate_cache | ( |  | ) |

Invalidate any internal cached state, e.g.

because Funcs have been rescheduled.

## ◆ add_requirement() [1/2]

void Halide::Pipeline::add_requirement | ( | const Expr & | condition,
|  | const std::vector< Expr > & | error_args
| ) |  |

Add a top-level precondition to the generated pipeline, expressed as a boolean Expr.

The Expr may depend on parameters only, and may not call any Func or use a Var. If the condition is not true at runtime, the pipeline will call halide_error with the remaining arguments, and return halide_error_code_requirement_failed. Requirements are checked in the order added.

Referenced by add_requirement().

## ◆ add_requirement() [2/2]

template<typename... Args, typename = std::enable_if_t<Internal::all_are_printable_args<Args...>::value>>

HALIDE_NO_USER_CODE_INLINE void Halide::Pipeline::add_requirement | ( | const Expr & | condition,
|  | Args &&... | error_args
| ) |  |
| inline

Definition at line 487 of file Pipeline.h.

References add_requirement(), and Halide::Internal::collect_print_args().

## ◆ trace_pipeline()

void Halide::Pipeline::trace_pipeline | ( |  | ) |

Generate begin_pipeline and end_pipeline tracing calls for this pipeline.

Referenced by Halide::Internal::GeneratorBase::trace_pipeline().

The documentation for this class was generated from the following file:

- src/Pipeline.h