Halide
Halide::Pipeline Class Reference

A class representing a Halide pipeline. More...

#include <Pipeline.h>

Public Member Functions

EXPORT Pipeline ()
 Make an undefined Pipeline object. More...
 
EXPORT Pipeline (Func output)
 Make a pipeline that computes the given Func. More...
 
EXPORT Pipeline (const std::vector< Func > &outputs)
 Make a pipeline that computes the givens Funcs as outputs. More...
 
EXPORT std::vector< Funcoutputs () const
 Get the Funcs this pipeline outputs. More...
 
EXPORT Func get_func (size_t index)
 Return handle to the index-th Func within the pipeline based on the realization order. More...
 
EXPORT void compile_to (const Outputs &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...
 
EXPORT 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...
 
EXPORT 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...
 
EXPORT 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...
 
EXPORT 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...
 
EXPORT 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...
 
EXPORT 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...
 
EXPORT 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...
 
EXPORT void print_loop_nest ()
 Write out the loop nests specified by the schedule for this Pipeline's Funcs. More...
 
EXPORT 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...
 
EXPORT 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...
 
EXPORT 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...
 
EXPORT Module compile_to_module (const std::vector< Argument > &args, const std::string &fn_name, const Target &target=get_target_from_environment(), const Internal::LoweredFunc::LinkageType linkage_type=Internal::LoweredFunc::ExternalPlusMetadata)
 Create an internal representation of lowered code as a self contained Module suitable for further compilation. More...
 
EXPORT void * compile_jit (const Target &target=get_jit_target_from_environment())
 Eagerly jit compile the function to machine code. More...
 
EXPORT void set_error_handler (void(*handler)(void *, const char *))
 Set the error handler function that be called in the case of runtime errors during halide pipelines. More...
 
EXPORT void set_custom_allocator (void *(*malloc)(void *, size_t), void(*free)(void *, void *))
 
EXPORT void set_custom_do_task (int(*custom_do_task)(void *, int(*)(void *, int, uint8_t *), int, uint8_t *))
 Set a custom task handler to be called by the parallel for loop. More...
 
EXPORT void set_custom_do_par_for (int(*custom_do_par_for)(void *, int(*)(void *, int, uint8_t *), int, int, uint8_t *))
 Set a custom parallel for loop launcher. More...
 
EXPORT void set_custom_trace (int(*trace_fn)(void *, const halide_trace_event_t *))
 Set custom routines to call when tracing is enabled. More...
 
EXPORT void set_custom_print (void(*handler)(void *, const char *))
 Set the function called to print messages from the runtime. More...
 
EXPORT 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...
 
EXPORT const std::map< std::string, JITExtern > & get_jit_externs ()
 Return the map of previously installed externs. More...
 
EXPORT const Internal::JITHandlersjit_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...
 
EXPORT void add_custom_lowering_pass (Internal::IRMutator2 *pass, void(*deleter)(Internal::IRMutator2 *))
 Add a custom pass to be used during lowering, with the function that will be called to delete it also passed in. More...
 
EXPORT void clear_custom_lowering_passes ()
 Remove all previously-set custom lowering passes. More...
 
EXPORT const std::vector< CustomLoweringPass > & custom_lowering_passes ()
 Get the custom lowering passes. More...
 
EXPORT void realize (Realization dst, const Target &target=Target())
 Evaluate this Pipeline into an existing allocated buffer or buffers. More...
 
EXPORT 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). More...
 
EXPORT bool defined () const
 Check if this pipeline object is defined. More...
 
EXPORT void invalidate_cache ()
 Invalidate any internal cached state, e.g. More...
 
EXPORT std::string auto_schedule (const Target &target, const MachineParams &arch_params=MachineParams::generic())
 Generate a schedule for the pipeline. More...
 
EXPORT Realization realize (std::vector< int32_t > sizes, const Target &target=Target())
 See Func::realize. More...
 
EXPORT Realization realize (int x_size, int y_size, int z_size, int w_size, const Target &target=Target())
 See Func::realize. More...
 
EXPORT Realization realize (int x_size, int y_size, int z_size, const Target &target=Target())
 See Func::realize. More...
 
EXPORT Realization realize (int x_size, int y_size, const Target &target=Target())
 See Func::realize. More...
 
EXPORT Realization realize (int x_size, const Target &target=Target())
 See Func::realize. More...
 
EXPORT Realization realize (const Target &target=Target())
 See Func::realize. More...
 
EXPORT void infer_input_bounds (int x_size=0, int y_size=0, int z_size=0, int w_size=0)
 For a given size of output, or a given set of output buffers, determine the bounds required of all unbound ImageParams referenced. More...
 
EXPORT void infer_input_bounds (Realization dst)
 For a given size of output, or a given set of output buffers, determine the bounds required of all unbound ImageParams referenced. More...
 

Detailed Description

A class representing a Halide pipeline.

Constructed from the Func or Funcs that it outputs.

Definition at line 58 of file Pipeline.h.

Constructor & Destructor Documentation

◆ Pipeline() [1/3]

EXPORT Halide::Pipeline::Pipeline ( )

Make an undefined Pipeline object.

◆ Pipeline() [2/3]

EXPORT Halide::Pipeline::Pipeline ( Func  output)

Make a pipeline that computes the given Func.

Schedules the Func compute_root().

◆ Pipeline() [3/3]

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

Make a pipeline that computes the givens Funcs as outputs.

Schedules the Funcs compute_root().

Member Function Documentation

◆ outputs()

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

Get the Funcs this pipeline outputs.

◆ auto_schedule()

EXPORT std::string Halide::Pipeline::auto_schedule ( const Target target,
const MachineParams arch_params = MachineParams::generic() 
)

Generate a schedule for the pipeline.

◆ get_func()

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

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

◆ compile_to()

EXPORT void Halide::Pipeline::compile_to ( const Outputs 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 struct.

◆ compile_to_bitcode()

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

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

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

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

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

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

EXPORT 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.

◆ print_loop_nest()

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

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

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

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

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

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

◆ compile_jit()

EXPORT 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. Returns the raw function pointer to the compiled pipeline. Default is to use the Target returned from Halide::get_jit_target_from_environment()

◆ set_error_handler()

EXPORT void Halide::Pipeline::set_error_handler ( void(*)(void *, const char *)  handler)

Set the error handler function that be called in the case of runtime errors during halide pipelines.

If you are compiling statically, you can also just define your own function with signature

extern "C" void halide_error(void *user_context, const char *);

This will clobber Halide's version.

◆ set_custom_allocator()

EXPORT void Halide::Pipeline::set_custom_allocator ( void *(*)(void *, size_t malloc,
void(*)(void *, void *)  free 
)

◆ set_custom_do_task()

EXPORT void Halide::Pipeline::set_custom_do_task ( int(*)(void *, int(*)(void *, int, uint8_t *), int, uint8_t *)  custom_do_task)

Set a custom task handler to be called by the parallel for loop.

It is useful to set this if you want to do some additional bookkeeping at the granularity of parallel tasks. The default implementation does this:

extern "C" int halide_do_task(void *user_context,
int (*f)(void *, int, uint8_t *),
int idx, uint8_t *state) {
return f(user_context, idx, state);
}

If you are statically compiling, you can also just define your own version of the above function, and it will clobber Halide's version.

If you're trying to use a custom parallel runtime, you probably don't want to call this. See instead Func::set_custom_do_par_for .

◆ set_custom_do_par_for()

EXPORT void Halide::Pipeline::set_custom_do_par_for ( int(*)(void *, int(*)(void *, int, uint8_t *), int, int, uint8_t *)  custom_do_par_for)

Set a custom parallel for loop launcher.

Useful if your app already manages a thread pool. The default implementation is equivalent to this:

extern "C" int halide_do_par_for(void *user_context,
int (*f)(void *, int, uint8_t *),
int min, int extent, uint8_t *state) {
int exit_status = 0;
parallel for (int idx = min; idx < min+extent; idx++) {
int job_status = halide_do_task(user_context, f, idx, state);
if (job_status) exit_status = job_status;
}
return exit_status;
}

However, notwithstanding the above example code, if one task fails, we may skip over other tasks, and if two tasks return different error codes, we may select one arbitrarily to return.

If you are statically compiling, you can also just define your own version of the above function, and it will clobber Halide's version.

◆ set_custom_trace()

EXPORT void Halide::Pipeline::set_custom_trace ( int(*)(void *, const halide_trace_event_t *)  trace_fn)

Set custom routines to call when tracing is enabled.

Call this on the output Func of your pipeline. This then sets custom routines for the entire pipeline, not just calls to this Func.

If you are statically compiling, you can also just define your own versions of the tracing functions (see HalideRuntime.h), and they will clobber Halide's versions.

◆ set_custom_print()

EXPORT void Halide::Pipeline::set_custom_print ( void(*)(void *, const char *)  handler)

Set the function called to print messages from the runtime.

If you are compiling statically, you can also just define your own function with signature

extern "C" void halide_print(void *user_context, const char *);

This will clobber Halide's version.

◆ set_jit_externs()

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

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

EXPORT const Internal::JITHandlers& Halide::Pipeline::jit_handlers ( )

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

◆ 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 332 of file Pipeline.h.

References EXPORT, and Halide::Internal::infer_arguments().

◆ add_custom_lowering_pass() [2/2]

EXPORT void Halide::Pipeline::add_custom_lowering_pass ( Internal::IRMutator2 pass,
void(*)(Internal::IRMutator2 *)  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()

EXPORT void Halide::Pipeline::clear_custom_lowering_passes ( )

Remove all previously-set custom lowering passes.

◆ custom_lowering_passes()

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

Get the custom lowering passes.

◆ realize() [1/7]

EXPORT Realization Halide::Pipeline::realize ( std::vector< int32_t sizes,
const Target target = Target() 
)

◆ realize() [2/7]

EXPORT Realization Halide::Pipeline::realize ( int  x_size,
int  y_size,
int  z_size,
int  w_size,
const Target target = Target() 
)

◆ realize() [3/7]

EXPORT Realization Halide::Pipeline::realize ( int  x_size,
int  y_size,
int  z_size,
const Target target = Target() 
)

◆ realize() [4/7]

EXPORT Realization Halide::Pipeline::realize ( int  x_size,
int  y_size,
const Target target = Target() 
)

◆ realize() [5/7]

EXPORT Realization Halide::Pipeline::realize ( int  x_size,
const Target target = Target() 
)

◆ realize() [6/7]

EXPORT Realization Halide::Pipeline::realize ( const Target target = Target())

◆ realize() [7/7]

EXPORT void Halide::Pipeline::realize ( Realization  dst,
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.

◆ infer_input_bounds() [1/2]

EXPORT void Halide::Pipeline::infer_input_bounds ( int  x_size = 0,
int  y_size = 0,
int  z_size = 0,
int  w_size = 0 
)

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/2]

EXPORT void Halide::Pipeline::infer_input_bounds ( Realization  dst)

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

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

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

Check if this pipeline object is defined.

That is, does it have any outputs?

◆ invalidate_cache()

EXPORT void Halide::Pipeline::invalidate_cache ( )

Invalidate any internal cached state, e.g.

because Funcs have been rescheduled.


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