Halide 19.0.0
Halide compiler and libraries
Loading...
Searching...
No Matches
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.
 
 Pipeline (const Func &output)
 Make a pipeline that computes the given Func.
 
 Pipeline (const std::vector< Func > &outputs)
 Make a pipeline that computes the givens Funcs as outputs.
 
 Pipeline (const std::vector< Func > &outputs, const std::vector< Internal::Stmt > &requirements)
 Make a pipeline from deserialization.
 
std::vector< Argumentinfer_arguments (const Internal::Stmt &body)
 
std::vector< Funcoutputs () const
 Get the Funcs this pipeline outputs.
 
std::vector< Internal::Stmtrequirements () const
 Get the requirements of this pipeline.
 
AutoSchedulerResults apply_autoscheduler (const Target &target, const AutoschedulerParams &autoscheduler_params) const
 Generate a schedule for the pipeline using the specified autoscheduler.
 
Func get_func (size_t index)
 Return handle to the index-th Func within the pipeline based on the topological order.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
void print_loop_nest ()
 Write out the loop nests specified by the schedule for this Pipeline's Funcs.
 
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.
 
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.
 
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.
 
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).
 
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.
 
void compile_jit (const Target &target=get_jit_target_from_environment())
 Eagerly jit compile the function to machine code.
 
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.
 
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.
 
const std::map< std::string, JITExtern > & get_jit_externs ()
 Return the map of previously installed externs.
 
JITHandlersjit_handlers ()
 Get a struct containing the currently set custom functions used by JIT.
 
template<typename T >
void add_custom_lowering_pass (T *pass)
 Add a custom pass to be used during lowering.
 
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.
 
void clear_custom_lowering_passes ()
 Remove all previously-set custom lowering passes.
 
const std::vector< CustomLoweringPass > & custom_lowering_passes ()
 Get the custom lowering passes.
 
Realization realize (std::vector< int32_t > sizes={}, const Target &target=Target())
 See Func::realize.
 
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.
 
void realize (RealizationArg output, const Target &target=Target())
 Evaluate this Pipeline into an existing allocated buffer or buffers.
 
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.
 
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.
 
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.
 
void infer_input_bounds (JITUserContext *context, RealizationArg output, const Target &target=get_jit_target_from_environment())
 
std::vector< Argumentinfer_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).
 
bool defined () const
 Check if this pipeline object is defined.
 
void invalidate_cache ()
 Invalidate any internal cached state, e.g.
 
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.
 
template<typename... Args, typename = typename std::enable_if<Internal::all_are_printable_args<Args...>::value>::type>
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.
 

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.
 

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() )

◆ 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 = typename std::enable_if<Internal::all_are_printable_args<Args...>::value>::type>
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.


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