Halide
HalideRuntime.h File Reference

Set a custom malloc and free for halide to use. More...

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>

Go to the source code of this file.

Classes

struct  halide_mutex
 Cross-platform mutex. More...
 
struct  halide_type_t
 A runtime tag for a type in the halide type system. More...
 
struct  halide_trace_event_t
 
struct  halide_trace_packet_t
 The header of a packet in a binary trace. More...
 
struct  halide_device_interface_t
 Each GPU API provides a halide_device_interface_t struct pointing to the code that manages device allocations. More...
 
struct  halide_dimension_t
 
struct  halide_buffer_t
 The raw representation of an image passed around by generated Halide code. More...
 
struct  buffer_t
 
struct  halide_scalar_value_t
 halide_scalar_value_t is a simple union able to represent all the well-known scalar values in a filter argument. More...
 
struct  halide_filter_argument_t
 halide_filter_argument_t is essentially a plain-C-struct equivalent to Halide::Argument; most user code will never need to create one. More...
 
struct  halide_filter_metadata_t
 
struct  halide_profiler_func_stats
 The functions below here are relevant for pipelines compiled with the -profile target flag, which runs a sampling profiler thread alongside the pipeline. More...
 
struct  halide_profiler_pipeline_stats
 Per-pipeline state tracked by the sampling profiler. More...
 
struct  halide_profiler_state
 The global state of the profiler. More...
 

Macros

#define HALIDE_ALWAYS_INLINE   __attribute__((always_inline)) inline
 
#define HALIDE_ATTRIBUTE_ALIGN(x)   __attribute__((aligned(x)))
 
#define HALIDE_ATTRIBUTE_DEPRECATED(x)   __attribute__((deprecated(x)))
 
#define BUFFER_T_DEFINED
 The old buffer_t, included for compatibility with old code. More...
 

Typedefs

typedef int(* halide_do_par_for_t) (void *, halide_task_t, int, int, uint8_t *)
 Set a custom method for performing a parallel for loop. More...
 
typedef enum halide_type_code_t halide_type_code_t
 Types in the halide type system. More...
 
typedef int32_t(* halide_trace_t) (void *user_context, const struct halide_trace_event_t *)
 
typedef enum halide_target_feature_t halide_target_feature_t
 Optional features a compilation Target can have. More...
 
typedef struct halide_dimension_t halide_dimension_t
 
typedef struct halide_buffer_t halide_buffer_t
 The raw representation of an image passed around by generated Halide code. More...
 
typedef struct buffer_t buffer_t
 

Enumerations

enum  halide_type_code_t { halide_type_int = 0, halide_type_uint = 1, halide_type_float = 2, halide_type_handle = 3 }
 Types in the halide type system. More...
 
enum  halide_trace_event_code_t {
  halide_trace_load = 0, halide_trace_store = 1, halide_trace_begin_realization = 2, halide_trace_end_realization = 3,
  halide_trace_produce = 4, halide_trace_end_produce = 5, halide_trace_consume = 6, halide_trace_end_consume = 7,
  halide_trace_begin_pipeline = 8, halide_trace_end_pipeline = 9
}
 
enum  halide_error_code_t {
  halide_error_code_success = 0, halide_error_code_generic_error = -1, halide_error_code_explicit_bounds_too_small = -2, halide_error_code_bad_type = -3,
  halide_error_code_access_out_of_bounds = -4, halide_error_code_buffer_allocation_too_large = -5, halide_error_code_buffer_extents_too_large = -6, halide_error_code_constraints_make_required_region_smaller = -7,
  halide_error_code_constraint_violated = -8, halide_error_code_param_too_small = -9, halide_error_code_param_too_large = -10, halide_error_code_out_of_memory = -11,
  halide_error_code_buffer_argument_is_null = -12, halide_error_code_debug_to_file_failed = -13, halide_error_code_copy_to_host_failed = -14, halide_error_code_copy_to_device_failed = -15,
  halide_error_code_device_malloc_failed = -16, halide_error_code_device_sync_failed = -17, halide_error_code_device_free_failed = -18, halide_error_code_no_device_interface = -19,
  halide_error_code_matlab_init_failed = -20, halide_error_code_matlab_bad_param_type = -21, halide_error_code_internal_error = -22, halide_error_code_device_run_failed = -23,
  halide_error_code_unaligned_host_ptr = -24, halide_error_code_bad_fold = -25, halide_error_code_fold_factor_too_small = -26, halide_error_code_requirement_failed = -27,
  halide_error_code_buffer_extents_negative = -28, halide_error_code_failed_to_upgrade_buffer_t = -29, halide_error_code_failed_to_downgrade_buffer_t = -30, halide_error_code_specialize_fail = -31,
  halide_error_code_device_wrap_native_failed = -32, halide_error_code_device_detach_native_failed = -33, halide_error_code_host_is_null = -34, halide_error_code_bad_extern_fold = -35,
  halide_error_code_device_interface_no_device = -36, halide_error_code_host_and_device_dirty = -37, halide_error_code_buffer_is_null = -38, halide_error_code_device_buffer_copy_failed = -39,
  halide_error_code_device_crop_unsupported = -40, halide_error_code_device_crop_failed = -41, halide_error_code_incompatible_device_interface = -42
}
 The error codes that may be returned by a Halide pipeline. More...
 
enum  halide_target_feature_t {
  halide_target_feature_jit = 0, halide_target_feature_debug = 1, halide_target_feature_no_asserts = 2, halide_target_feature_no_bounds_query = 3,
  halide_target_feature_sse41 = 4, halide_target_feature_avx = 5, halide_target_feature_avx2 = 6, halide_target_feature_fma = 7,
  halide_target_feature_fma4 = 8, halide_target_feature_f16c = 9, halide_target_feature_armv7s = 10, halide_target_feature_no_neon = 11,
  halide_target_feature_vsx = 12, halide_target_feature_power_arch_2_07 = 13, halide_target_feature_cuda = 14, halide_target_feature_cuda_capability30 = 15,
  halide_target_feature_cuda_capability32 = 16, halide_target_feature_cuda_capability35 = 17, halide_target_feature_cuda_capability50 = 18, halide_target_feature_opencl = 19,
  halide_target_feature_cl_doubles = 20, halide_target_feature_opengl = 21, halide_target_feature_openglcompute = 22, halide_target_feature_unused_23 = 23,
  halide_target_feature_user_context = 24, halide_target_feature_matlab = 25, halide_target_feature_profile = 26, halide_target_feature_no_runtime = 27,
  halide_target_feature_metal = 28, halide_target_feature_mingw = 29, halide_target_feature_c_plus_plus_mangling = 30, halide_target_feature_large_buffers = 31,
  halide_target_feature_hvx_64 = 32, halide_target_feature_hvx_128 = 33, halide_target_feature_hvx_v62 = 34, halide_target_feature_fuzz_float_stores = 35,
  halide_target_feature_soft_float_abi = 36, halide_target_feature_msan = 37, halide_target_feature_avx512 = 38, halide_target_feature_avx512_knl = 39,
  halide_target_feature_avx512_skylake = 40, halide_target_feature_avx512_cannonlake = 41, halide_target_feature_hvx_use_shared_object = 42, halide_target_feature_trace_loads = 43,
  halide_target_feature_trace_stores = 44, halide_target_feature_trace_realizations = 45, halide_target_feature_cuda_capability61 = 46, halide_target_feature_hvx_v65 = 47,
  halide_target_feature_hvx_v66 = 48, halide_target_feature_end = 49
}
 Optional features a compilation Target can have. More...
 
enum  halide_buffer_flags { halide_buffer_flag_host_dirty = 1, halide_buffer_flag_device_dirty = 2 }
 
enum  halide_argument_kind_t { halide_argument_kind_input_scalar = 0, halide_argument_kind_input_buffer = 1, halide_argument_kind_output_buffer = 2 }
 
enum  { halide_profiler_outside_of_halide = -1, halide_profiler_please_stop = -2 }
 Profiler func ids with special meanings. More...
 

Functions

halide_do_par_for_t halide_set_custom_do_par_for (halide_do_par_for_t do_par_for)
 
struct halide_thread * halide_spawn_thread (void(*f)(void *), void *closure)
 Spawn a thread. More...
 
void halide_join_thread (struct halide_thread *)
 Join a thread. More...
 
int halide_set_num_threads (int n)
 Set the number of threads used by Halide's thread pool. More...
 
int32_t halide_debug_to_file (void *user_context, const char *filename, int32_t type_code, struct halide_buffer_t *buf)
 Called when debug_to_file is used inside Halide code. More...
 
int32_t halide_trace (void *user_context, const struct halide_trace_event_t *event)
 Called when Funcs are marked as trace_load, trace_store, or trace_realization. More...
 
int32_t halide_default_trace (void *user_context, const struct halide_trace_event_t *event)
 
halide_trace_t halide_set_custom_trace (halide_trace_t trace)
 
void halide_set_trace_file (int fd)
 Set the file descriptor that Halide should write binary trace events to. More...
 
int halide_get_trace_file (void *user_context)
 Halide calls this to retrieve the file descriptor to write binary trace events to. More...
 
int halide_shutdown_trace ()
 If tracing is writing to a file. More...
 
void halide_device_release (void *user_context, const struct halide_device_interface_t *device_interface)
 Release all data associated with the given device interface, in particular all resources (memory, texture, context handles) allocated by Halide. More...
 
int halide_copy_to_host (void *user_context, struct halide_buffer_t *buf)
 Copy image data from device memory to host memory. More...
 
int halide_copy_to_device (void *user_context, struct halide_buffer_t *buf, const struct halide_device_interface_t *device_interface)
 Copy image data from host memory to device memory. More...
 
int halide_buffer_copy (void *user_context, struct halide_buffer_t *src, const struct halide_device_interface_t *dst_device_interface, struct halide_buffer_t *dst)
 Copy data from one buffer to another. More...
 
int halide_device_crop (void *user_context, const struct halide_buffer_t *src, struct halide_buffer_t *dst)
 Give the destination buffer a device allocation which is an alias for the same coordinate range in the source buffer. More...
 
int halide_device_release_crop (void *user_context, struct halide_buffer_t *buf)
 Release any resources associated with a cropped view of another buffer. More...
 
int halide_device_sync (void *user_context, struct halide_buffer_t *buf)
 Wait for current GPU operations to complete. More...
 
int halide_device_malloc (void *user_context, struct halide_buffer_t *buf, const struct halide_device_interface_t *device_interface)
 Allocate device memory to back a halide_buffer_t. More...
 
int halide_device_free (void *user_context, struct halide_buffer_t *buf)
 Free device memory. More...
 
void halide_set_gpu_device (int n)
 Selects which gpu device to use. More...
 
int halide_get_gpu_device (void *user_context)
 Halide calls this to get the desired halide gpu device setting. More...
 
void halide_memoization_cache_set_size (int64_t size)
 Set the soft maximum amount of memory, in bytes, that the LRU cache will use to memoize Func results. More...
 
int halide_memoization_cache_lookup (void *user_context, const uint8_t *cache_key, int32_t size, struct halide_buffer_t *realized_bounds, int32_t tuple_count, struct halide_buffer_t **tuple_buffers)
 Given a cache key for a memoized result, currently constructed from the Func name and top-level Func name plus the arguments of the computation, determine if the result is in the cache and return it if so. More...
 
int halide_memoization_cache_store (void *user_context, const uint8_t *cache_key, int32_t size, struct halide_buffer_t *realized_bounds, int32_t tuple_count, struct halide_buffer_t **tuple_buffers)
 Given a cache key for a memoized result, currently constructed from the Func name and top-level Func name plus the arguments of the computation, store the result in the cache for futre access by halide_memoization_cache_lookup. More...
 
void halide_memoization_cache_release (void *user_context, void *host)
 If halide_memoization_cache_lookup succeeds, halide_memoization_cache_release must be called to signal the storage is no longer being used by the caller. More...
 
void halide_memoization_cache_cleanup ()
 Free all memory and resources associated with the memoization cache. More...
 
int halide_create_temp_file (void *user_context, const char *prefix, const char *suffix, char *path_buf, size_t path_buf_size)
 Create a unique file with a name of the form prefixXXXXXsuffix in an arbitrary (but writable) directory; this is typically $TMP or /tmp, but the specific location is not guaranteed. More...
 
void halide_msan_annotate_memory_is_initialized (void *user_context, const void *ptr, uint64_t len)
 Annotate that a given range of memory has been initialized; only used when Target::MSAN is enabled. More...
 
void halide_msan_annotate_buffer_is_initialized (void *user_context, struct halide_buffer_t *buffer)
 Mark the data pointed to by the buffer_t as initialized (but not the buffer_t itself), using halide_msan_annotate_memory_is_initialized() for marking. More...
 
void halide_msan_annotate_buffer_is_initialized_as_destructor (void *user_context, void *buffer)
 
int halide_error_bounds_inference_call_failed (void *user_context, const char *extern_stage_name, int result)
 Halide calls the functions below on various error conditions. More...
 
int halide_error_extern_stage_failed (void *user_context, const char *extern_stage_name, int result)
 A call to an extern stage failed. More...
 
int halide_default_can_use_target_features (uint64_t features)
 This is the default implementation of halide_can_use_target_features; it is provided for convenience of user code that may wish to extend halide_can_use_target_features but continue providing existing support, e.g. More...
 
int halide_upgrade_buffer_t (void *user_context, const char *name, const buffer_t *old_buf, halide_buffer_t *new_buf)
 Copies host pointer, mins, extents, strides, and device state from an old-style buffer_t into a new-style halide_buffer_t. More...
 
int halide_downgrade_buffer_t (void *user_context, const char *name, const halide_buffer_t *new_buf, buffer_t *old_buf)
 Copies the host pointer, mins, extents, strides, and device state from a halide_buffer_t to a buffer_t. More...
 
int halide_downgrade_buffer_t_device_fields (void *user_context, const char *name, const halide_buffer_t *new_buf, buffer_t *old_buf)
 Copies the dirty flags and device allocation state from a new buffer_t back to a legacy buffer_t. More...
 
struct halide_profiler_statehalide_profiler_get_state ()
 Get a pointer to the global profiler state for programmatic inspection. More...
 
struct halide_profiler_pipeline_statshalide_profiler_get_pipeline_state (const char *pipeline_name)
 Get a pointer to the pipeline state associated with pipeline_name. More...
 
void halide_profiler_reset ()
 Reset all profiler state. More...
 
void halide_profiler_report (void *user_context)
 Print out timing statistics for everything run since the last reset. More...
 
void halide_mutex_lock (struct halide_mutex *mutex)
 A basic set of mutex and condition variable functions, which call platform specific code for mutual exclusion. More...
 
void halide_mutex_unlock (struct halide_mutex *mutex)
 A basic set of mutex and condition variable functions, which call platform specific code for mutual exclusion. More...
 
void halide_mutex_destroy (struct halide_mutex *mutex)
 A basic set of mutex and condition variable functions, which call platform specific code for mutual exclusion. More...
 
int halide_default_do_par_for (void *user_context, halide_task_t task, int min, int size, uint8_t *closure)
 The default versions of do_task and do_par_for. More...
 
int halide_default_do_task (void *user_context, halide_task_t f, int idx, uint8_t *closure)
 The default versions of do_task and do_par_for. More...
 
int halide_device_wrap_native (void *user_context, struct halide_buffer_t *buf, uint64_t handle, const struct halide_device_interface_t *device_interface)
 Wrap or detach a native device handle, setting the device field and device_interface field as appropriate for the given GPU API. More...
 
int halide_device_detach_native (void *user_context, struct halide_buffer_t *buf)
 Wrap or detach a native device handle, setting the device field and device_interface field as appropriate for the given GPU API. More...
 
int halide_copy_to_host_legacy (void *user_context, struct buffer_t *buf)
 Versions of the above functions that accept legacy buffer_t structs. More...
 
int halide_copy_to_device_legacy (void *user_context, struct buffer_t *buf, const struct halide_device_interface_t *device_interface)
 Versions of the above functions that accept legacy buffer_t structs. More...
 
int halide_device_sync_legacy (void *user_context, struct buffer_t *buf)
 Versions of the above functions that accept legacy buffer_t structs. More...
 
int halide_device_malloc_legacy (void *user_context, struct buffer_t *buf, const struct halide_device_interface_t *device_interface)
 Versions of the above functions that accept legacy buffer_t structs. More...
 
int halide_device_free_legacy (void *user_context, struct buffer_t *buf)
 Versions of the above functions that accept legacy buffer_t structs. More...
 
int halide_error_explicit_bounds_too_small (void *user_context, const char *func_name, const char *var_name, int min_bound, int max_bound, int min_required, int max_required)
 Various other error conditions. More...
 
int halide_error_bad_type (void *user_context, const char *func_name, uint8_t code_given, uint8_t correct_code, uint8_t bits_given, uint8_t correct_bits, uint16_t lanes_given, uint16_t correct_lanes)
 Various other error conditions. More...
 
int halide_error_access_out_of_bounds (void *user_context, const char *func_name, int dimension, int min_touched, int max_touched, int min_valid, int max_valid)
 Various other error conditions. More...
 
int halide_error_buffer_allocation_too_large (void *user_context, const char *buffer_name, uint64_t allocation_size, uint64_t max_size)
 Various other error conditions. More...
 
int halide_error_buffer_extents_negative (void *user_context, const char *buffer_name, int dimension, int extent)
 Various other error conditions. More...
 
int halide_error_buffer_extents_too_large (void *user_context, const char *buffer_name, int64_t actual_size, int64_t max_size)
 Various other error conditions. More...
 
int halide_error_constraints_make_required_region_smaller (void *user_context, const char *buffer_name, int dimension, int constrained_min, int constrained_extent, int required_min, int required_extent)
 Various other error conditions. More...
 
int halide_error_constraint_violated (void *user_context, const char *var, int val, const char *constrained_var, int constrained_val)
 Various other error conditions. More...
 
int halide_error_param_too_small_i64 (void *user_context, const char *param_name, int64_t val, int64_t min_val)
 Various other error conditions. More...
 
int halide_error_param_too_small_u64 (void *user_context, const char *param_name, uint64_t val, uint64_t min_val)
 Various other error conditions. More...
 
int halide_error_param_too_small_f64 (void *user_context, const char *param_name, double val, double min_val)
 Various other error conditions. More...
 
int halide_error_param_too_large_i64 (void *user_context, const char *param_name, int64_t val, int64_t max_val)
 Various other error conditions. More...
 
int halide_error_param_too_large_u64 (void *user_context, const char *param_name, uint64_t val, uint64_t max_val)
 Various other error conditions. More...
 
int halide_error_param_too_large_f64 (void *user_context, const char *param_name, double val, double max_val)
 Various other error conditions. More...
 
int halide_error_out_of_memory (void *user_context)
 Various other error conditions. More...
 
int halide_error_buffer_argument_is_null (void *user_context, const char *buffer_name)
 Various other error conditions. More...
 
int halide_error_debug_to_file_failed (void *user_context, const char *func, const char *filename, int error_code)
 Various other error conditions. More...
 
int halide_error_unaligned_host_ptr (void *user_context, const char *func_name, int alignment)
 Various other error conditions. More...
 
int halide_error_host_is_null (void *user_context, const char *func_name)
 Various other error conditions. More...
 
int halide_error_failed_to_upgrade_buffer_t (void *user_context, const char *input_name, const char *reason)
 Various other error conditions. More...
 
int halide_error_failed_to_downgrade_buffer_t (void *user_context, const char *input_name, const char *reason)
 Various other error conditions. More...
 
int halide_error_bad_fold (void *user_context, const char *func_name, const char *var_name, const char *loop_name)
 Various other error conditions. More...
 
int halide_error_bad_extern_fold (void *user_context, const char *func_name, int dim, int min, int extent, int valid_min, int fold_factor)
 Various other error conditions. More...
 
int halide_error_fold_factor_too_small (void *user_context, const char *func_name, const char *var_name, int fold_factor, const char *loop_name, int required_extent)
 Various other error conditions. More...
 
int halide_error_requirement_failed (void *user_context, const char *condition, const char *message)
 Various other error conditions. More...
 
int halide_error_specialize_fail (void *user_context, const char *message)
 Various other error conditions. More...
 
int halide_error_no_device_interface (void *user_context)
 Various other error conditions. More...
 
int halide_error_device_interface_no_device (void *user_context)
 Various other error conditions. More...
 
int halide_error_host_and_device_dirty (void *user_context)
 Various other error conditions. More...
 
int halide_error_buffer_is_null (void *user_context, const char *routine)
 Various other error conditions. More...
 
"Float16" functions

These functions operate of bits (uint16_t) representing a half precision floating point number (IEEE-754 2008 binary16).

float halide_float16_bits_to_float (uint16_t)
 Read bits representing a half precision floating point number and return the float that represents the same value. More...
 
double halide_float16_bits_to_double (uint16_t)
 Read bits representing a half precision floating point number and return the double that represents the same value. More...
 
typedef void(* halide_print_t) (void *, const char *)
 Print a message to stderr. More...
 
void halide_print (void *user_context, const char *)
 Print a message to stderr. More...
 
void halide_default_print (void *user_context, const char *)
 Print a message to stderr. More...
 
halide_print_t halide_set_custom_print (halide_print_t print)
 Print a message to stderr. More...
 
typedef void(* halide_error_handler_t) (void *, const char *)
 Halide calls this function on runtime errors (for example bounds checking failures). More...
 
void halide_error (void *user_context, const char *)
 Halide calls this function on runtime errors (for example bounds checking failures). More...
 
void halide_default_error (void *user_context, const char *)
 Halide calls this function on runtime errors (for example bounds checking failures). More...
 
halide_error_handler_t halide_set_error_handler (halide_error_handler_t handler)
 Halide calls this function on runtime errors (for example bounds checking failures). More...
 
typedef int(* halide_task_t) (void *user_context, int task_number, uint8_t *closure)
 Define halide_do_par_for to replace the default thread pool implementation. More...
 
int halide_do_par_for (void *user_context, halide_task_t task, int min, int size, uint8_t *closure)
 Define halide_do_par_for to replace the default thread pool implementation. More...
 
void halide_shutdown_thread_pool ()
 Define halide_do_par_for to replace the default thread pool implementation. More...
 
typedef int(* halide_do_task_t) (void *, halide_task_t, int, uint8_t *)
 If you use the default do_par_for, you can still set a custom handler to perform each individual task. More...
 
halide_do_task_t halide_set_custom_do_task (halide_do_task_t do_task)
 If you use the default do_par_for, you can still set a custom handler to perform each individual task. More...
 
int halide_do_task (void *user_context, halide_task_t f, int idx, uint8_t *closure)
 If you use the default do_par_for, you can still set a custom handler to perform each individual task. More...
 
typedef void *(* halide_malloc_t) (void *, size_t)
 Halide calls these functions to allocate and free memory. More...
 
typedef void(* halide_free_t) (void *, void *)
 Halide calls these functions to allocate and free memory. More...
 
void * halide_malloc (void *user_context, size_t x)
 Halide calls these functions to allocate and free memory. More...
 
void halide_free (void *user_context, void *ptr)
 Halide calls these functions to allocate and free memory. More...
 
void * halide_default_malloc (void *user_context, size_t x)
 Halide calls these functions to allocate and free memory. More...
 
void halide_default_free (void *user_context, void *ptr)
 Halide calls these functions to allocate and free memory. More...
 
halide_malloc_t halide_set_custom_malloc (halide_malloc_t user_malloc)
 Halide calls these functions to allocate and free memory. More...
 
halide_free_t halide_set_custom_free (halide_free_t user_free)
 Halide calls these functions to allocate and free memory. More...
 
typedef void *(* halide_get_symbol_t) (const char *name)
 Halide calls these functions to interact with the underlying system runtime functions. More...
 
typedef void *(* halide_load_library_t) (const char *name)
 Halide calls these functions to interact with the underlying system runtime functions. More...
 
typedef void *(* halide_get_library_symbol_t) (void *lib, const char *name)
 Halide calls these functions to interact with the underlying system runtime functions. More...
 
void * halide_get_symbol (const char *name)
 Halide calls these functions to interact with the underlying system runtime functions. More...
 
void * halide_load_library (const char *name)
 Halide calls these functions to interact with the underlying system runtime functions. More...
 
void * halide_get_library_symbol (void *lib, const char *name)
 Halide calls these functions to interact with the underlying system runtime functions. More...
 
void * halide_default_get_symbol (const char *name)
 Halide calls these functions to interact with the underlying system runtime functions. More...
 
void * halide_default_load_library (const char *name)
 Halide calls these functions to interact with the underlying system runtime functions. More...
 
void * halide_default_get_library_symbol (void *lib, const char *name)
 Halide calls these functions to interact with the underlying system runtime functions. More...
 
halide_get_symbol_t halide_set_custom_get_symbol (halide_get_symbol_t user_get_symbol)
 Halide calls these functions to interact with the underlying system runtime functions. More...
 
halide_load_library_t halide_set_custom_load_library (halide_load_library_t user_load_library)
 Halide calls these functions to interact with the underlying system runtime functions. More...
 
halide_get_library_symbol_t halide_set_custom_get_library_symbol (halide_get_library_symbol_t user_get_library_symbol)
 Halide calls these functions to interact with the underlying system runtime functions. More...
 
typedef int(* halide_can_use_target_features_t) (uint64_t)
 This function is called internally by Halide in some situations to determine if the current execution environment can support the given set of halide_target_feature_t flags. More...
 
int halide_can_use_target_features (uint64_t features)
 This function is called internally by Halide in some situations to determine if the current execution environment can support the given set of halide_target_feature_t flags. More...
 
halide_can_use_target_features_t halide_set_custom_can_use_target_features (halide_can_use_target_features_t)
 This function is called internally by Halide in some situations to determine if the current execution environment can support the given set of halide_target_feature_t flags. More...
 

Detailed Description

Set a custom malloc and free for halide to use.

This file declares the routines used by Halide internally in its runtime.

Malloc should return 32-byte aligned chunks of memory, and it should be safe for Halide to read slightly out of bounds (up to 8 bytes before the start or beyond the end). If compiling statically, routines with appropriate signatures can be provided directly

extern "C" void *halide_malloc(void *, size_t)
extern "C" void halide_free(void *, void *)

These will clobber Halide's versions. See for declarations.

On platforms that support weak linking, these can be replaced with user-defined versions by defining an extern "C" function with the same name and signature.

When doing Just In Time (JIT) compilation methods on the Func being compiled must be called instead. The corresponding methods are documented below.

All of these functions take a "void *user_context" parameter as their first argument; if the Halide kernel that calls back to any of these functions has been compiled with the UserContext feature set on its Target, then the value of that pointer passed from the code that calls the Halide kernel is piped through to the function.

Some of these are also useful to call when using the default implementation. E.g. halide_shutdown_thread_pool.

Note that even on platforms with weak linking, some linker setups may not respect the override you provide. E.g. if the override is in a shared library and the halide object files are linked directly into the output, the builtin versions of the runtime functions will be called. See your linker documentation for more details. On Linux, LD_DYNAMIC_WEAK=1 may help.

Definition in file HalideRuntime.h.

Macro Definition Documentation

◆ HALIDE_ALWAYS_INLINE

◆ HALIDE_ATTRIBUTE_ALIGN

#define HALIDE_ATTRIBUTE_ALIGN (   x)    __attribute__((aligned(x)))

Definition at line 267 of file HalideRuntime.h.

◆ HALIDE_ATTRIBUTE_DEPRECATED

#define HALIDE_ATTRIBUTE_DEPRECATED (   x)    __attribute__((deprecated(x)))

◆ BUFFER_T_DEFINED

#define BUFFER_T_DEFINED

The old buffer_t, included for compatibility with old code.

Don't use it.

Definition at line 1298 of file HalideRuntime.h.

Typedef Documentation

◆ halide_print_t

typedef void(* halide_print_t) (void *, const char *)

Print a message to stderr.

Main use is to support tracing functionality, print, and print_when calls. Also called by the default halide_error. This function can be replaced in JITed code by using halide_custom_print and providing an implementation of halide_print in AOT code. See Func::set_custom_print.

Definition at line 72 of file HalideRuntime.h.

◆ halide_error_handler_t

typedef void(* halide_error_handler_t) (void *, const char *)

Halide calls this function on runtime errors (for example bounds checking failures).

This function can be replaced in JITed code by using Func::set_error_handler, or in AOT code by calling halide_set_error_handler. In AOT code on platforms that support weak linking (i.e. not Windows), you can also override it by simply defining your own halide_error.

Definition at line 86 of file HalideRuntime.h.

◆ halide_task_t

typedef int(* halide_task_t) (void *user_context, int task_number, uint8_t *closure)

Define halide_do_par_for to replace the default thread pool implementation.

halide_shutdown_thread_pool can also be called to release resources used by the default thread pool on platforms where it makes sense. (E.g. On Mac OS, Grand Central Dispatch is used so Halide does not own the threads backing the pool and they cannot be released.) See Func::set_custom_do_task and Func::set_custom_do_par_for. Should return zero if all the jobs return zero, or an arbitrarily chosen return value from one of the jobs otherwise.

Definition at line 124 of file HalideRuntime.h.

◆ halide_do_par_for_t

typedef int(* halide_do_par_for_t) (void *, halide_task_t, int, int, uint8_t *)

Set a custom method for performing a parallel for loop.

Returns the old do_par_for handler.

Definition at line 133 of file HalideRuntime.h.

◆ halide_do_task_t

typedef int(* halide_do_task_t) (void *, halide_task_t, int, uint8_t *)

If you use the default do_par_for, you can still set a custom handler to perform each individual task.

Returns the old handler.

Definition at line 139 of file HalideRuntime.h.

◆ halide_malloc_t

typedef void*(* halide_malloc_t) (void *, size_t)

Halide calls these functions to allocate and free memory.

To replace in AOT code, use the halide_set_custom_malloc and halide_set_custom_free, or (on platforms that support weak linking), simply define these functions yourself. In JIT-compiled code use Func::set_custom_allocator.

If you override them, and find yourself wanting to call the default implementation from within your override, use halide_default_malloc/free.

Note that halide_malloc must return a pointer aligned to the maximum meaningful alignment for the platform for the purpose of vector loads and stores. The default implementation uses 32-byte alignment, which is safe for arm and x86. Additionally, it must be safe to read at least 8 bytes before the start and beyond the end.

Definition at line 205 of file HalideRuntime.h.

◆ halide_free_t

typedef void(* halide_free_t) (void *, void *)

Halide calls these functions to allocate and free memory.

To replace in AOT code, use the halide_set_custom_malloc and halide_set_custom_free, or (on platforms that support weak linking), simply define these functions yourself. In JIT-compiled code use Func::set_custom_allocator.

If you override them, and find yourself wanting to call the default implementation from within your override, use halide_default_malloc/free.

Note that halide_malloc must return a pointer aligned to the maximum meaningful alignment for the platform for the purpose of vector loads and stores. The default implementation uses 32-byte alignment, which is safe for arm and x86. Additionally, it must be safe to read at least 8 bytes before the start and beyond the end.

Definition at line 206 of file HalideRuntime.h.

◆ halide_get_symbol_t

typedef void*(* halide_get_symbol_t) (const char *name)

Halide calls these functions to interact with the underlying system runtime functions.

To replace in AOT code on platforms that support weak linking, define these functions yourself, or use the halide_set_custom_load_library() and halide_set_custom_get_library_symbol() functions. In JIT-compiled code, use JITSharedRuntime::set_default_handlers().

halide_load_library and halide_get_library_symbol are equivalent to dlopen and dlsym. halide_get_symbol(sym) is equivalent to dlsym(RTLD_DEFAULT, sym).

Definition at line 228 of file HalideRuntime.h.

◆ halide_load_library_t

typedef void*(* halide_load_library_t) (const char *name)

Halide calls these functions to interact with the underlying system runtime functions.

To replace in AOT code on platforms that support weak linking, define these functions yourself, or use the halide_set_custom_load_library() and halide_set_custom_get_library_symbol() functions. In JIT-compiled code, use JITSharedRuntime::set_default_handlers().

halide_load_library and halide_get_library_symbol are equivalent to dlopen and dlsym. halide_get_symbol(sym) is equivalent to dlsym(RTLD_DEFAULT, sym).

Definition at line 229 of file HalideRuntime.h.

◆ halide_get_library_symbol_t

typedef void*(* halide_get_library_symbol_t) (void *lib, const char *name)

Halide calls these functions to interact with the underlying system runtime functions.

To replace in AOT code on platforms that support weak linking, define these functions yourself, or use the halide_set_custom_load_library() and halide_set_custom_get_library_symbol() functions. In JIT-compiled code, use JITSharedRuntime::set_default_handlers().

halide_load_library and halide_get_library_symbol are equivalent to dlopen and dlsym. halide_get_symbol(sym) is equivalent to dlsym(RTLD_DEFAULT, sym).

Definition at line 230 of file HalideRuntime.h.

◆ halide_type_code_t

Types in the halide type system.

They can be ints, unsigned ints, or floats (of various bit-widths), or a handle (which is always 64-bits). Note that the int/uint/float values do not imply a specific bit width (the bit width is expected to be encoded in a separate value).

◆ halide_trace_t

typedef int32_t(* halide_trace_t) (void *user_context, const struct halide_trace_event_t *)

Definition at line 409 of file HalideRuntime.h.

◆ halide_target_feature_t

Optional features a compilation Target can have.

◆ halide_can_use_target_features_t

typedef int(* halide_can_use_target_features_t) (uint64_t)

This function is called internally by Halide in some situations to determine if the current execution environment can support the given set of halide_target_feature_t flags.

The implementation must do the following:

– If there are flags set in features that the function knows cannot be supported, return 0. – Otherwise, return 1. – Note that any flags set in features that the function doesn't know how to test should be ignored; this implies that a return value of 1 means "not known to be bad" rather than "known to be good".

In other words: a return value of 0 means "It is not safe to use code compiled with these features", while a return value of 1 means "It is not obviously unsafe to use code compiled with these features".

The default implementation simply calls halide_default_can_use_target_features.

Definition at line 1093 of file HalideRuntime.h.

◆ halide_dimension_t

◆ halide_buffer_t

The raw representation of an image passed around by generated Halide code.

It includes some stuff to track whether the image is not actually in main memory, but instead on a device (like a GPU). For a more convenient C++ wrapper, use Halide::Buffer<T>.

◆ buffer_t

typedef struct buffer_t buffer_t

Enumeration Type Documentation

◆ halide_type_code_t

Types in the halide type system.

They can be ints, unsigned ints, or floats (of various bit-widths), or a handle (which is always 64-bits). Note that the int/uint/float values do not imply a specific bit width (the bit width is expected to be encoded in a separate value).

Enumerator
halide_type_int 

signed integers

halide_type_uint 

unsigned integers

halide_type_float 

floating point numbers

halide_type_handle 

opaque pointer type (void *)

Definition at line 250 of file HalideRuntime.h.

◆ halide_trace_event_code_t

Enumerator
halide_trace_load 
halide_trace_store 
halide_trace_begin_realization 
halide_trace_end_realization 
halide_trace_produce 
halide_trace_end_produce 
halide_trace_consume 
halide_trace_end_consume 
halide_trace_begin_pipeline 
halide_trace_end_pipeline 

Definition at line 319 of file HalideRuntime.h.

◆ halide_error_code_t

The error codes that may be returned by a Halide pipeline.

Enumerator
halide_error_code_success 

There was no error.

This is the value returned by Halide on success.

halide_error_code_generic_error 

An uncategorized error occurred.

Refer to the string passed to halide_error.

halide_error_code_explicit_bounds_too_small 

A Func was given an explicit bound via Func::bound, but this was not large enough to encompass the region that is used of the Func by the rest of the pipeline.

halide_error_code_bad_type 

The elem_size field of a halide_buffer_t does not match the size in bytes of the type of that ImageParam.

Probable type mismatch.

halide_error_code_access_out_of_bounds 

A pipeline would access memory outside of the halide_buffer_t passed in.

halide_error_code_buffer_allocation_too_large 

A halide_buffer_t was given that spans more than 2GB of memory.

halide_error_code_buffer_extents_too_large 

A halide_buffer_t was given with extents that multiply to a number greater than 2^31-1.

halide_error_code_constraints_make_required_region_smaller 

Applying explicit constraints on the size of an input or output buffer shrank the size of that buffer below what will be accessed by the pipeline.

halide_error_code_constraint_violated 

A constraint on a size or stride of an input or output buffer was not met by the halide_buffer_t passed in.

halide_error_code_param_too_small 

A scalar parameter passed in was smaller than its minimum declared value.

halide_error_code_param_too_large 

A scalar parameter passed in was greater than its minimum declared value.

halide_error_code_out_of_memory 

A call to halide_malloc returned NULL.

halide_error_code_buffer_argument_is_null 

A halide_buffer_t pointer passed in was NULL.

halide_error_code_debug_to_file_failed 

debug_to_file failed to open or write to the specified file.

halide_error_code_copy_to_host_failed 

The Halide runtime encountered an error while trying to copy from device to host.

Turn on -debug in your target string to see more details.

halide_error_code_copy_to_device_failed 

The Halide runtime encountered an error while trying to copy from host to device.

Turn on -debug in your target string to see more details.

halide_error_code_device_malloc_failed 

The Halide runtime encountered an error while trying to allocate memory on device.

Turn on -debug in your target string to see more details.

halide_error_code_device_sync_failed 

The Halide runtime encountered an error while trying to synchronize with a device.

Turn on -debug in your target string to see more details.

halide_error_code_device_free_failed 

The Halide runtime encountered an error while trying to free a device allocation.

Turn on -debug in your target string to see more details.

halide_error_code_no_device_interface 

Buffer has a non-zero device but no device interface, which violates a Halide invariant.

halide_error_code_matlab_init_failed 

An error occurred when attempting to initialize the Matlab runtime.

halide_error_code_matlab_bad_param_type 

The type of an mxArray did not match the expected type.

halide_error_code_internal_error 

There is a bug in the Halide compiler.

halide_error_code_device_run_failed 

The Halide runtime encountered an error while trying to launch a GPU kernel.

Turn on -debug in your target string to see more details.

halide_error_code_unaligned_host_ptr 

The Halide runtime encountered a host pointer that violated the alignment set for it by way of a call to set_host_alignment.

halide_error_code_bad_fold 

A fold_storage directive was used on a dimension that is not accessed in a monotonically increasing or decreasing fashion.

halide_error_code_fold_factor_too_small 

A fold_storage directive was used with a fold factor that was too small to store all the values of a producer needed by the consumer.

halide_error_code_requirement_failed 

User-specified require() expression was not satisfied.

halide_error_code_buffer_extents_negative 

At least one of the buffer's extents are negative.

halide_error_code_failed_to_upgrade_buffer_t 

A compiled pipeline was passed the old deprecated buffer_t struct, and it could not be upgraded to a halide_buffer_t.

halide_error_code_failed_to_downgrade_buffer_t 

A compiled pipeline was passed the old deprecated buffer_t struct in bounds inference mode, but the returned information can't be expressed in the old buffer_t.

halide_error_code_specialize_fail 

A specialize_fail() schedule branch was selected at runtime.

halide_error_code_device_wrap_native_failed 

The Halide runtime encountered an error while trying to wrap a native device handle.

Turn on -debug in your target string to see more details.

halide_error_code_device_detach_native_failed 

The Halide runtime encountered an error while trying to detach a native device handle.

Turn on -debug in your target string to see more details.

halide_error_code_host_is_null 

The host field on an input or output was null, the device field was not zero, and the pipeline tries to use the buffer on the host.

You may be passing a GPU-only buffer to a pipeline which is scheduled to use it on the CPU.

halide_error_code_bad_extern_fold 

A folded buffer was passed to an extern stage, but the region touched wraps around the fold boundary.

halide_error_code_device_interface_no_device 

Buffer has a non-null device_interface but device is 0, which violates a Halide invariant.

halide_error_code_host_and_device_dirty 

Buffer has both host and device dirty bits set, which violates a Halide invariant.

halide_error_code_buffer_is_null 

The halide_buffer_t * passed to a halide runtime routine is nullptr and this is not allowed.

halide_error_code_device_buffer_copy_failed 

The Halide runtime encountered an error while trying to copy from one buffer to another.

Turn on -debug in your target string to see more details.

halide_error_code_device_crop_unsupported 

Attempted to make cropped alias of a buffer with a device field, but the device_interface does not support cropping.

halide_error_code_device_crop_failed 

Cropping a buffer failed for some other reason.

Turn on -debug in your target string.

halide_error_code_incompatible_device_interface 

An operation on a buffer required an allocation on a particular device interface, but a device allocation already existed on a different device interface.

Free the old one first.

Definition at line 749 of file HalideRuntime.h.

◆ halide_target_feature_t

Optional features a compilation Target can have.

Enumerator
halide_target_feature_jit 

Generate code that will run immediately inside the calling process.

halide_target_feature_debug 

Turn on debug info and output for runtime code.

halide_target_feature_no_asserts 

Disable all runtime checks, for slightly tighter code.

halide_target_feature_no_bounds_query 

Disable the bounds querying functionality.

halide_target_feature_sse41 

Use SSE 4.1 and earlier instructions. Only relevant on x86.

halide_target_feature_avx 

Use AVX 1 instructions. Only relevant on x86.

halide_target_feature_avx2 

Use AVX 2 instructions. Only relevant on x86.

halide_target_feature_fma 

Enable x86 FMA instruction.

halide_target_feature_fma4 

Enable x86 (AMD) FMA4 instruction set.

halide_target_feature_f16c 

Enable x86 16-bit float support.

halide_target_feature_armv7s 

Generate code for ARMv7s. Only relevant for 32-bit ARM.

halide_target_feature_no_neon 

Avoid using NEON instructions. Only relevant for 32-bit ARM.

halide_target_feature_vsx 

Use VSX instructions. Only relevant on POWERPC.

halide_target_feature_power_arch_2_07 

Use POWER ISA 2.07 new instructions. Only relevant on POWERPC.

halide_target_feature_cuda 

Enable the CUDA runtime. Defaults to compute capability 2.0 (Fermi)

halide_target_feature_cuda_capability30 

Enable CUDA compute capability 3.0 (Kepler)

halide_target_feature_cuda_capability32 

Enable CUDA compute capability 3.2 (Tegra K1)

halide_target_feature_cuda_capability35 

Enable CUDA compute capability 3.5 (Kepler)

halide_target_feature_cuda_capability50 

Enable CUDA compute capability 5.0 (Maxwell)

halide_target_feature_opencl 

Enable the OpenCL runtime.

halide_target_feature_cl_doubles 

Enable double support on OpenCL targets.

halide_target_feature_opengl 

Enable the OpenGL runtime.

halide_target_feature_openglcompute 

Enable OpenGL Compute runtime.

halide_target_feature_unused_23 

Unused. (Formerly: Enable the RenderScript runtime.)

halide_target_feature_user_context 

Generated code takes a user_context pointer as first argument.

halide_target_feature_matlab 

Generate a mexFunction compatible with Matlab mex libraries. See tools/mex_halide.m.

halide_target_feature_profile 

Launch a sampling profiler alongside the Halide pipeline that monitors and reports the runtime used by each Func.

halide_target_feature_no_runtime 

Do not include a copy of the Halide runtime in any generated object file or assembly.

halide_target_feature_metal 

Enable the (Apple) Metal runtime.

halide_target_feature_mingw 

For Windows compile to MinGW toolset rather then Visual Studio.

halide_target_feature_c_plus_plus_mangling 

Generate C++ mangled names for result function, et al.

halide_target_feature_large_buffers 

Enable 64-bit buffer indexing to support buffers > 2GB. Ignored if bits != 64.

halide_target_feature_hvx_64 

Enable HVX 64 byte mode.

halide_target_feature_hvx_128 

Enable HVX 128 byte mode.

halide_target_feature_hvx_v62 

Enable Hexagon v62 architecture.

halide_target_feature_fuzz_float_stores 

On every floating point store, set the last bit of the mantissa to zero. Pipelines for which the output is very different with this feature enabled may also produce very different output on different processors.

halide_target_feature_soft_float_abi 

Enable soft float ABI. This only enables the soft float ABI calling convention, which does not necessarily use soft floats.

halide_target_feature_msan 

Enable hooks for MSAN support.

halide_target_feature_avx512 

Enable the base AVX512 subset supported by all AVX512 architectures. The specific feature sets are AVX-512F and AVX512-CD. See https://en.wikipedia.org/wiki/AVX-512 for a description of each AVX subset.

halide_target_feature_avx512_knl 

Enable the AVX512 features supported by Knight's Landing chips, such as the Xeon Phi x200. This includes the base AVX512 set, and also AVX512-CD and AVX512-ER.

halide_target_feature_avx512_skylake 

Enable the AVX512 features supported by Skylake Xeon server processors. This adds AVX512-VL, AVX512-BW, and AVX512-DQ to the base set. The main difference from the base AVX512 set is better support for small integer ops. Note that this does not include the Knight's Landing features. Note also that these features are not available on Skylake desktop and mobile processors.

halide_target_feature_avx512_cannonlake 

Enable the AVX512 features expected to be supported by future Cannonlake processors. This includes all of the Skylake features, plus AVX512-IFMA and AVX512-VBMI.

halide_target_feature_hvx_use_shared_object 

Deprecated.

halide_target_feature_trace_loads 

Trace all loads done by the pipeline. Equivalent to calling Func::trace_loads on every non-inlined Func.

halide_target_feature_trace_stores 

Trace all stores done by the pipeline. Equivalent to calling Func::trace_stores on every non-inlined Func.

halide_target_feature_trace_realizations 

Trace all realizations done by the pipeline. Equivalent to calling Func::trace_realizations on every non-inlined Func.

halide_target_feature_cuda_capability61 

Enable CUDA compute capability 6.1 (Pascal)

halide_target_feature_hvx_v65 

Enable Hexagon v65 architecture.

halide_target_feature_hvx_v66 

Enable Hexagon v66 architecture.

halide_target_feature_end 

A sentinel. Every target is considered to have this feature, and setting this feature does nothing.

Definition at line 1010 of file HalideRuntime.h.

◆ halide_buffer_flags

Enumerator
halide_buffer_flag_host_dirty 
halide_buffer_flag_device_dirty 

Definition at line 1142 of file HalideRuntime.h.

◆ halide_argument_kind_t

Enumerator
halide_argument_kind_input_scalar 
halide_argument_kind_input_buffer 
halide_argument_kind_output_buffer 

Definition at line 1356 of file HalideRuntime.h.

◆ anonymous enum

anonymous enum

Profiler func ids with special meanings.

Enumerator
halide_profiler_outside_of_halide 

current_func takes on this value when not inside Halide code

halide_profiler_please_stop 

Set current_func to this value to tell the profiling thread to halt.

It will start up again next time you run a pipeline with profiling enabled.

Definition at line 1521 of file HalideRuntime.h.

Function Documentation

◆ halide_print()

void halide_print ( void *  user_context,
const char *   
)

Print a message to stderr.

Main use is to support tracing functionality, print, and print_when calls. Also called by the default halide_error. This function can be replaced in JITed code by using halide_custom_print and providing an implementation of halide_print in AOT code. See Func::set_custom_print.

◆ halide_default_print()

void halide_default_print ( void *  user_context,
const char *   
)

Print a message to stderr.

Main use is to support tracing functionality, print, and print_when calls. Also called by the default halide_error. This function can be replaced in JITed code by using halide_custom_print and providing an implementation of halide_print in AOT code. See Func::set_custom_print.

◆ halide_set_custom_print()

halide_print_t halide_set_custom_print ( halide_print_t  print)

Print a message to stderr.

Main use is to support tracing functionality, print, and print_when calls. Also called by the default halide_error. This function can be replaced in JITed code by using halide_custom_print and providing an implementation of halide_print in AOT code. See Func::set_custom_print.

◆ halide_error()

void halide_error ( void *  user_context,
const char *   
)

Halide calls this function on runtime errors (for example bounds checking failures).

This function can be replaced in JITed code by using Func::set_error_handler, or in AOT code by calling halide_set_error_handler. In AOT code on platforms that support weak linking (i.e. not Windows), you can also override it by simply defining your own halide_error.

Referenced by halide_set_num_threads().

◆ halide_default_error()

void halide_default_error ( void *  user_context,
const char *   
)

Halide calls this function on runtime errors (for example bounds checking failures).

This function can be replaced in JITed code by using Func::set_error_handler, or in AOT code by calling halide_set_error_handler. In AOT code on platforms that support weak linking (i.e. not Windows), you can also override it by simply defining your own halide_error.

◆ halide_set_error_handler()

halide_error_handler_t halide_set_error_handler ( halide_error_handler_t  handler)

Halide calls this function on runtime errors (for example bounds checking failures).

This function can be replaced in JITed code by using Func::set_error_handler, or in AOT code by calling halide_set_error_handler. In AOT code on platforms that support weak linking (i.e. not Windows), you can also override it by simply defining your own halide_error.

◆ halide_mutex_lock()

void halide_mutex_lock ( struct halide_mutex mutex)

A basic set of mutex and condition variable functions, which call platform specific code for mutual exclusion.

Equivalent to posix calls. Mutexes should initially be set to zero'd memory. Any resources required are created on first lock. Calling destroy re-zeros the memory.

Referenced by halide_default_do_par_for(), halide_set_num_threads(), halide_shutdown_thread_pool(), Halide::Runtime::Internal::ScopedMutexLock::ScopedMutexLock(), Halide::Runtime::Internal::worker_thread(), and Halide::Runtime::Internal::worker_thread_already_locked().

◆ halide_mutex_unlock()

void halide_mutex_unlock ( struct halide_mutex mutex)

A basic set of mutex and condition variable functions, which call platform specific code for mutual exclusion.

Equivalent to posix calls. Mutexes should initially be set to zero'd memory. Any resources required are created on first lock. Calling destroy re-zeros the memory.

Referenced by halide_default_do_par_for(), halide_set_num_threads(), halide_shutdown_thread_pool(), Halide::Runtime::Internal::worker_thread(), Halide::Runtime::Internal::worker_thread_already_locked(), and Halide::Runtime::Internal::ScopedMutexLock::~ScopedMutexLock().

◆ halide_mutex_destroy()

void halide_mutex_destroy ( struct halide_mutex mutex)

A basic set of mutex and condition variable functions, which call platform specific code for mutual exclusion.

Equivalent to posix calls. Mutexes should initially be set to zero'd memory. Any resources required are created on first lock. Calling destroy re-zeros the memory.

Referenced by halide_shutdown_thread_pool().

◆ halide_do_par_for()

int halide_do_par_for ( void *  user_context,
halide_task_t  task,
int  min,
int  size,
uint8_t closure 
)

Define halide_do_par_for to replace the default thread pool implementation.

halide_shutdown_thread_pool can also be called to release resources used by the default thread pool on platforms where it makes sense. (E.g. On Mac OS, Grand Central Dispatch is used so Halide does not own the threads backing the pool and they cannot be released.) See Func::set_custom_do_task and Func::set_custom_do_par_for. Should return zero if all the jobs return zero, or an arbitrarily chosen return value from one of the jobs otherwise.

◆ halide_shutdown_thread_pool()

void halide_shutdown_thread_pool ( )

Define halide_do_par_for to replace the default thread pool implementation.

halide_shutdown_thread_pool can also be called to release resources used by the default thread pool on platforms where it makes sense. (E.g. On Mac OS, Grand Central Dispatch is used so Halide does not own the threads backing the pool and they cannot be released.) See Func::set_custom_do_task and Func::set_custom_do_par_for. Should return zero if all the jobs return zero, or an arbitrarily chosen return value from one of the jobs otherwise.

Definition at line 273 of file thread_pool_common.h.

References halide_cond_broadcast(), halide_cond_destroy(), halide_join_thread(), halide_mutex_destroy(), halide_mutex_lock(), halide_mutex_unlock(), Halide::Runtime::Internal::work_queue_t::initialized, Halide::Runtime::Internal::work_queue_t::mutex, Halide::Runtime::Internal::work_queue_t::shutdown, Halide::Runtime::Internal::work_queue_t::threads, Halide::Runtime::Internal::work_queue_t::threads_created, Halide::Runtime::Internal::work_queue_t::wakeup_a_team, Halide::Runtime::Internal::work_queue_t::wakeup_b_team, Halide::Runtime::Internal::work_queue_t::wakeup_owners, and Halide::Runtime::Internal::work_queue.

◆ halide_set_custom_do_par_for()

halide_do_par_for_t halide_set_custom_do_par_for ( halide_do_par_for_t  do_par_for)

◆ halide_set_custom_do_task()

halide_do_task_t halide_set_custom_do_task ( halide_do_task_t  do_task)

If you use the default do_par_for, you can still set a custom handler to perform each individual task.

Returns the old handler.

◆ halide_do_task()

int halide_do_task ( void *  user_context,
halide_task_t  f,
int  idx,
uint8_t closure 
)

If you use the default do_par_for, you can still set a custom handler to perform each individual task.

Returns the old handler.

Referenced by Halide::Runtime::Internal::worker_thread_already_locked().

◆ halide_default_do_par_for()

int halide_default_do_par_for ( void *  user_context,
halide_task_t  task,
int  min,
int  size,
uint8_t closure 
)

The default versions of do_task and do_par_for.

Can be convenient to call from overrides in certain circumstances.

Definition at line 169 of file thread_pool_common.h.

References Halide::Runtime::Internal::work_queue_t::a_team_size, Halide::Runtime::Internal::work::active_workers, Halide::Runtime::Internal::clamp_num_threads(), Halide::Runtime::Internal::work::closure, Halide::Runtime::Internal::default_desired_num_threads(), Halide::Runtime::Internal::work_queue_t::desired_num_threads, Halide::Runtime::Internal::work::exit_status, Halide::Runtime::Internal::work::f, halide_cond_broadcast(), halide_cond_init(), halide_mutex_lock(), halide_mutex_unlock(), halide_spawn_thread(), Halide::Runtime::Internal::work_queue_t::initialized, Halide::Runtime::Internal::work_queue_t::jobs, Halide::Runtime::Internal::work::max, Halide::min(), Halide::Runtime::Internal::work_queue_t::mutex, Halide::Runtime::Internal::work::next, Halide::Runtime::Internal::work::next_job, NULL, Halide::Runtime::Internal::work_queue_t::shutdown, Halide::Runtime::Internal::work_queue_t::target_a_team_size, Halide::Runtime::Internal::work_queue_t::threads, Halide::Runtime::Internal::work_queue_t::threads_created, Halide::Runtime::Internal::work::user_context, Halide::Runtime::Internal::work_queue_t::wakeup_a_team, Halide::Runtime::Internal::work_queue_t::wakeup_b_team, Halide::Runtime::Internal::work_queue_t::wakeup_owners, Halide::Runtime::Internal::work_queue, Halide::Runtime::Internal::worker_thread(), and Halide::Runtime::Internal::worker_thread_already_locked().

◆ halide_default_do_task()

int halide_default_do_task ( void *  user_context,
halide_task_t  f,
int  idx,
uint8_t closure 
)

The default versions of do_task and do_par_for.

Can be convenient to call from overrides in certain circumstances.

Definition at line 164 of file thread_pool_common.h.

References Halide::Runtime::Internal::work::f.

◆ halide_spawn_thread()

struct halide_thread* halide_spawn_thread ( void(*)(void *)  f,
void *  closure 
)

Spawn a thread.

Returns a handle to the thread for the purposes of joining it. The thread must be joined in order to clean up any resources associated with it.

Referenced by halide_default_do_par_for().

◆ halide_join_thread()

void halide_join_thread ( struct halide_thread *  )

Join a thread.

Referenced by halide_shutdown_thread_pool().

◆ halide_set_num_threads()

int halide_set_num_threads ( int  n)

Set the number of threads used by Halide's thread pool.

Returns the old number.

n < 0 : error condition n == 0 : use a reasonable system default (typically, number of cpus online). n == 1 : use exactly one thread; this will always enforce serial execution n > 1 : use a pool of exactly n threads.

Note that the default iOS and OSX behavior will treat n > 1 like n == 0; that is, any positive value other than 1 will use a system-determined number of threads.

(Note that this is only guaranteed when using the default implementations of halide_do_par_for(); custom implementations may completely ignore values passed to halide_set_num_threads().)

Definition at line 256 of file thread_pool_common.h.

References Halide::Runtime::Internal::clamp_num_threads(), Halide::Runtime::Internal::default_desired_num_threads(), Halide::Runtime::Internal::work_queue_t::desired_num_threads, halide_error(), halide_mutex_lock(), halide_mutex_unlock(), Halide::Runtime::Internal::work_queue_t::mutex, NULL, and Halide::Runtime::Internal::work_queue.

◆ halide_malloc()

void* halide_malloc ( void *  user_context,
size_t  x 
)

Halide calls these functions to allocate and free memory.

To replace in AOT code, use the halide_set_custom_malloc and halide_set_custom_free, or (on platforms that support weak linking), simply define these functions yourself. In JIT-compiled code use Func::set_custom_allocator.

If you override them, and find yourself wanting to call the default implementation from within your override, use halide_default_malloc/free.

Note that halide_malloc must return a pointer aligned to the maximum meaningful alignment for the platform for the purpose of vector loads and stores. The default implementation uses 32-byte alignment, which is safe for arm and x86. Additionally, it must be safe to read at least 8 bytes before the start and beyond the end.

◆ halide_free()

void halide_free ( void *  user_context,
void *  ptr 
)

Halide calls these functions to allocate and free memory.

To replace in AOT code, use the halide_set_custom_malloc and halide_set_custom_free, or (on platforms that support weak linking), simply define these functions yourself. In JIT-compiled code use Func::set_custom_allocator.

If you override them, and find yourself wanting to call the default implementation from within your override, use halide_default_malloc/free.

Note that halide_malloc must return a pointer aligned to the maximum meaningful alignment for the platform for the purpose of vector loads and stores. The default implementation uses 32-byte alignment, which is safe for arm and x86. Additionally, it must be safe to read at least 8 bytes before the start and beyond the end.

◆ halide_default_malloc()

void* halide_default_malloc ( void *  user_context,
size_t  x 
)

Halide calls these functions to allocate and free memory.

To replace in AOT code, use the halide_set_custom_malloc and halide_set_custom_free, or (on platforms that support weak linking), simply define these functions yourself. In JIT-compiled code use Func::set_custom_allocator.

If you override them, and find yourself wanting to call the default implementation from within your override, use halide_default_malloc/free.

Note that halide_malloc must return a pointer aligned to the maximum meaningful alignment for the platform for the purpose of vector loads and stores. The default implementation uses 32-byte alignment, which is safe for arm and x86. Additionally, it must be safe to read at least 8 bytes before the start and beyond the end.

◆ halide_default_free()

void halide_default_free ( void *  user_context,
void *  ptr 
)

Halide calls these functions to allocate and free memory.

To replace in AOT code, use the halide_set_custom_malloc and halide_set_custom_free, or (on platforms that support weak linking), simply define these functions yourself. In JIT-compiled code use Func::set_custom_allocator.

If you override them, and find yourself wanting to call the default implementation from within your override, use halide_default_malloc/free.

Note that halide_malloc must return a pointer aligned to the maximum meaningful alignment for the platform for the purpose of vector loads and stores. The default implementation uses 32-byte alignment, which is safe for arm and x86. Additionally, it must be safe to read at least 8 bytes before the start and beyond the end.

◆ halide_set_custom_malloc()

halide_malloc_t halide_set_custom_malloc ( halide_malloc_t  user_malloc)

Halide calls these functions to allocate and free memory.

To replace in AOT code, use the halide_set_custom_malloc and halide_set_custom_free, or (on platforms that support weak linking), simply define these functions yourself. In JIT-compiled code use Func::set_custom_allocator.

If you override them, and find yourself wanting to call the default implementation from within your override, use halide_default_malloc/free.

Note that halide_malloc must return a pointer aligned to the maximum meaningful alignment for the platform for the purpose of vector loads and stores. The default implementation uses 32-byte alignment, which is safe for arm and x86. Additionally, it must be safe to read at least 8 bytes before the start and beyond the end.

◆ halide_set_custom_free()

halide_free_t halide_set_custom_free ( halide_free_t  user_free)

Halide calls these functions to allocate and free memory.

To replace in AOT code, use the halide_set_custom_malloc and halide_set_custom_free, or (on platforms that support weak linking), simply define these functions yourself. In JIT-compiled code use Func::set_custom_allocator.

If you override them, and find yourself wanting to call the default implementation from within your override, use halide_default_malloc/free.

Note that halide_malloc must return a pointer aligned to the maximum meaningful alignment for the platform for the purpose of vector loads and stores. The default implementation uses 32-byte alignment, which is safe for arm and x86. Additionally, it must be safe to read at least 8 bytes before the start and beyond the end.

◆ halide_get_symbol()

void* halide_get_symbol ( const char *  name)

Halide calls these functions to interact with the underlying system runtime functions.

To replace in AOT code on platforms that support weak linking, define these functions yourself, or use the halide_set_custom_load_library() and halide_set_custom_get_library_symbol() functions. In JIT-compiled code, use JITSharedRuntime::set_default_handlers().

halide_load_library and halide_get_library_symbol are equivalent to dlopen and dlsym. halide_get_symbol(sym) is equivalent to dlsym(RTLD_DEFAULT, sym).

◆ halide_load_library()

void* halide_load_library ( const char *  name)

Halide calls these functions to interact with the underlying system runtime functions.

To replace in AOT code on platforms that support weak linking, define these functions yourself, or use the halide_set_custom_load_library() and halide_set_custom_get_library_symbol() functions. In JIT-compiled code, use JITSharedRuntime::set_default_handlers().

halide_load_library and halide_get_library_symbol are equivalent to dlopen and dlsym. halide_get_symbol(sym) is equivalent to dlsym(RTLD_DEFAULT, sym).

◆ halide_get_library_symbol()

void* halide_get_library_symbol ( void *  lib,
const char *  name 
)

Halide calls these functions to interact with the underlying system runtime functions.

To replace in AOT code on platforms that support weak linking, define these functions yourself, or use the halide_set_custom_load_library() and halide_set_custom_get_library_symbol() functions. In JIT-compiled code, use JITSharedRuntime::set_default_handlers().

halide_load_library and halide_get_library_symbol are equivalent to dlopen and dlsym. halide_get_symbol(sym) is equivalent to dlsym(RTLD_DEFAULT, sym).

◆ halide_default_get_symbol()

void* halide_default_get_symbol ( const char *  name)

Halide calls these functions to interact with the underlying system runtime functions.

To replace in AOT code on platforms that support weak linking, define these functions yourself, or use the halide_set_custom_load_library() and halide_set_custom_get_library_symbol() functions. In JIT-compiled code, use JITSharedRuntime::set_default_handlers().

halide_load_library and halide_get_library_symbol are equivalent to dlopen and dlsym. halide_get_symbol(sym) is equivalent to dlsym(RTLD_DEFAULT, sym).

◆ halide_default_load_library()

void* halide_default_load_library ( const char *  name)

Halide calls these functions to interact with the underlying system runtime functions.

To replace in AOT code on platforms that support weak linking, define these functions yourself, or use the halide_set_custom_load_library() and halide_set_custom_get_library_symbol() functions. In JIT-compiled code, use JITSharedRuntime::set_default_handlers().

halide_load_library and halide_get_library_symbol are equivalent to dlopen and dlsym. halide_get_symbol(sym) is equivalent to dlsym(RTLD_DEFAULT, sym).

◆ halide_default_get_library_symbol()

void* halide_default_get_library_symbol ( void *  lib,
const char *  name 
)

Halide calls these functions to interact with the underlying system runtime functions.

To replace in AOT code on platforms that support weak linking, define these functions yourself, or use the halide_set_custom_load_library() and halide_set_custom_get_library_symbol() functions. In JIT-compiled code, use JITSharedRuntime::set_default_handlers().

halide_load_library and halide_get_library_symbol are equivalent to dlopen and dlsym. halide_get_symbol(sym) is equivalent to dlsym(RTLD_DEFAULT, sym).

◆ halide_set_custom_get_symbol()

halide_get_symbol_t halide_set_custom_get_symbol ( halide_get_symbol_t  user_get_symbol)

Halide calls these functions to interact with the underlying system runtime functions.

To replace in AOT code on platforms that support weak linking, define these functions yourself, or use the halide_set_custom_load_library() and halide_set_custom_get_library_symbol() functions. In JIT-compiled code, use JITSharedRuntime::set_default_handlers().

halide_load_library and halide_get_library_symbol are equivalent to dlopen and dlsym. halide_get_symbol(sym) is equivalent to dlsym(RTLD_DEFAULT, sym).

◆ halide_set_custom_load_library()

halide_load_library_t halide_set_custom_load_library ( halide_load_library_t  user_load_library)

Halide calls these functions to interact with the underlying system runtime functions.

To replace in AOT code on platforms that support weak linking, define these functions yourself, or use the halide_set_custom_load_library() and halide_set_custom_get_library_symbol() functions. In JIT-compiled code, use JITSharedRuntime::set_default_handlers().

halide_load_library and halide_get_library_symbol are equivalent to dlopen and dlsym. halide_get_symbol(sym) is equivalent to dlsym(RTLD_DEFAULT, sym).

◆ halide_set_custom_get_library_symbol()

halide_get_library_symbol_t halide_set_custom_get_library_symbol ( halide_get_library_symbol_t  user_get_library_symbol)

Halide calls these functions to interact with the underlying system runtime functions.

To replace in AOT code on platforms that support weak linking, define these functions yourself, or use the halide_set_custom_load_library() and halide_set_custom_get_library_symbol() functions. In JIT-compiled code, use JITSharedRuntime::set_default_handlers().

halide_load_library and halide_get_library_symbol are equivalent to dlopen and dlsym. halide_get_symbol(sym) is equivalent to dlsym(RTLD_DEFAULT, sym).

◆ halide_debug_to_file()

int32_t halide_debug_to_file ( void *  user_context,
const char *  filename,
int32_t  type_code,
struct halide_buffer_t buf 
)

Called when debug_to_file is used inside Halide code.

See Func::debug_to_file for how this is called

Cannot be replaced in JITted code at present.

◆ halide_trace()

int32_t halide_trace ( void *  user_context,
const struct halide_trace_event_t event 
)

Called when Funcs are marked as trace_load, trace_store, or trace_realization.

See Func::set_custom_trace. The default implementation either prints events via halide_print, or if HL_TRACE_FILE is defined, dumps the trace to that file in a sequence of trace packets. The header for a trace packet is defined below. If the trace is going to be large, you may want to make the file a named pipe, and then read from that pipe into gzip.

halide_trace returns a unique ID which will be passed to future events that "belong" to the earlier event as the parent id. The ownership hierarchy looks like:

begin_pipeline +–begin_realization | +–produce | | +–load/store | | +–end_produce | +–consume | | +–load | | +–end_consume | +–end_realization +–end_pipeline

Threading means that ownership cannot be inferred from the ordering of events. There can be many active realizations of a given function, or many active productions for a single realization. Within a single production, the ordering of events is meaningful.

◆ halide_default_trace()

int32_t halide_default_trace ( void *  user_context,
const struct halide_trace_event_t event 
)

◆ halide_set_custom_trace()

halide_trace_t halide_set_custom_trace ( halide_trace_t  trace)

◆ halide_set_trace_file()

void halide_set_trace_file ( int  fd)

Set the file descriptor that Halide should write binary trace events to.

If called with 0 as the argument, Halide outputs trace information to stdout in a human-readable format. If never called, Halide checks the for existence of an environment variable called HL_TRACE_FILE and opens that file. If HL_TRACE_FILE is not defined, it outputs trace information to stdout in a human-readable format.

◆ halide_get_trace_file()

int halide_get_trace_file ( void *  user_context)

Halide calls this to retrieve the file descriptor to write binary trace events to.

The default implementation returns the value set by halide_set_trace_file. Implement it yourself if you wish to use a custom file descriptor per user_context. Return zero from your implementation to tell Halide to print human-readable trace information to stdout.

◆ halide_shutdown_trace()

int halide_shutdown_trace ( )

If tracing is writing to a file.

This call closes that file (flushing the trace). Returns zero on success.

◆ halide_device_release()

void halide_device_release ( void *  user_context,
const struct halide_device_interface_t device_interface 
)

Release all data associated with the given device interface, in particular all resources (memory, texture, context handles) allocated by Halide.

Must be called explicitly when using AOT compilation.

◆ halide_copy_to_host()

int halide_copy_to_host ( void *  user_context,
struct halide_buffer_t buf 
)

Copy image data from device memory to host memory.

This must be called explicitly to copy back the results of a GPU-based filter.

◆ halide_copy_to_device()

int halide_copy_to_device ( void *  user_context,
struct halide_buffer_t buf,
const struct halide_device_interface_t device_interface 
)

Copy image data from host memory to device memory.

This should not be called directly; Halide handles copying to the device automatically. If interface is NULL and the bug has a non-zero dev field, the device associated with the dev handle will be used. Otherwise if the dev field is 0 and interface is NULL, an error is returned.

◆ halide_buffer_copy()

int halide_buffer_copy ( void *  user_context,
struct halide_buffer_t src,
const struct halide_device_interface_t dst_device_interface,
struct halide_buffer_t dst 
)

Copy data from one buffer to another.

The buffers may have different shapes and sizes, but the destination buffer's shape must be contained within the source buffer's shape. That is, for each dimension, the min on the destination buffer must be greater than or equal to the min on the source buffer, and min+extent on the destination buffer must be less that or equal to min+extent on the source buffer. The source data is pulled from either device or host memory on the source, depending on the dirty flags. host is preferred if both are valid. The dst_device_interface parameter controls the destination memory space. NULL means host memory.

◆ halide_device_crop()

int halide_device_crop ( void *  user_context,
const struct halide_buffer_t src,
struct halide_buffer_t dst 
)

Give the destination buffer a device allocation which is an alias for the same coordinate range in the source buffer.

Modifies the device, device_interface, and the device_dirty flag only. Only supported by some device APIs (others will return halide_error_code_device_crop_unsupported). Call halide_device_release_crop instead of halide_device_free to clean up resources associated with the cropped view. Do not free the device allocation on the source buffer while the destination buffer still lives. Note that the two buffers do not share dirty flags, so care must be taken to update them together as needed. Note also that device interfaces which support cropping may still not support cropping a crop. Instead, create a new crop of the parent buffer.

◆ halide_device_release_crop()

int halide_device_release_crop ( void *  user_context,
struct halide_buffer_t buf 
)

Release any resources associated with a cropped view of another buffer.

◆ halide_device_sync()

int halide_device_sync ( void *  user_context,
struct halide_buffer_t buf 
)

Wait for current GPU operations to complete.

Calling this explicitly should rarely be necessary, except maybe for profiling.

◆ halide_device_malloc()

int halide_device_malloc ( void *  user_context,
struct halide_buffer_t buf,
const struct halide_device_interface_t device_interface 
)

Allocate device memory to back a halide_buffer_t.

◆ halide_device_free()

int halide_device_free ( void *  user_context,
struct halide_buffer_t buf 
)

Free device memory.

◆ halide_device_wrap_native()

int halide_device_wrap_native ( void *  user_context,
struct halide_buffer_t buf,
uint64_t  handle,
const struct halide_device_interface_t device_interface 
)

Wrap or detach a native device handle, setting the device field and device_interface field as appropriate for the given GPU API.

The meaning of the opaque handle is specific to the device interface, so if you know the device interface in use, call the more specific functions in the runtime headers for your specific device API instead (e.g. HalideRuntimeCuda.h).

◆ halide_device_detach_native()

int halide_device_detach_native ( void *  user_context,
struct halide_buffer_t buf 
)

Wrap or detach a native device handle, setting the device field and device_interface field as appropriate for the given GPU API.

The meaning of the opaque handle is specific to the device interface, so if you know the device interface in use, call the more specific functions in the runtime headers for your specific device API instead (e.g. HalideRuntimeCuda.h).

◆ halide_copy_to_host_legacy()

int halide_copy_to_host_legacy ( void *  user_context,
struct buffer_t buf 
)

Versions of the above functions that accept legacy buffer_t structs.

◆ halide_copy_to_device_legacy()

int halide_copy_to_device_legacy ( void *  user_context,
struct buffer_t buf,
const struct halide_device_interface_t device_interface 
)

Versions of the above functions that accept legacy buffer_t structs.

◆ halide_device_sync_legacy()

int halide_device_sync_legacy ( void *  user_context,
struct buffer_t buf 
)

Versions of the above functions that accept legacy buffer_t structs.

◆ halide_device_malloc_legacy()

int halide_device_malloc_legacy ( void *  user_context,
struct buffer_t buf,
const struct halide_device_interface_t device_interface 
)

Versions of the above functions that accept legacy buffer_t structs.

◆ halide_device_free_legacy()

int halide_device_free_legacy ( void *  user_context,
struct buffer_t buf 
)

Versions of the above functions that accept legacy buffer_t structs.

◆ halide_set_gpu_device()

void halide_set_gpu_device ( int  n)

Selects which gpu device to use.

0 is usually the display device. If never called, Halide uses the environment variable HL_GPU_DEVICE. If that variable is unset, Halide uses the last device. Set this to -1 to use the last device.

◆ halide_get_gpu_device()

int halide_get_gpu_device ( void *  user_context)

Halide calls this to get the desired halide gpu device setting.

Implement this yourself to use a different gpu device per user_context. The default implementation returns the value set by halide_set_gpu_device, or the environment variable HL_GPU_DEVICE.

◆ halide_memoization_cache_set_size()

void halide_memoization_cache_set_size ( int64_t  size)

Set the soft maximum amount of memory, in bytes, that the LRU cache will use to memoize Func results.

This is not a strict maximum in that concurrency and simultaneous use of memoized reults larger than the cache size can both cause it to temporariliy be larger than the size specified here.

◆ halide_memoization_cache_lookup()

int halide_memoization_cache_lookup ( void *  user_context,
const uint8_t cache_key,
int32_t  size,
struct halide_buffer_t realized_bounds,
int32_t  tuple_count,
struct halide_buffer_t **  tuple_buffers 
)

Given a cache key for a memoized result, currently constructed from the Func name and top-level Func name plus the arguments of the computation, determine if the result is in the cache and return it if so.

(The internals of the cache key should be considered opaque by this function.) If this routine returns true, it is a cache miss. Otherwise, it will return false and the buffers passed in will be filled, via copying, with memoized data. The last argument is a list if halide_buffer_t pointers which represents the outputs of the memoized Func. If the Func does not return a Tuple, there will only be one halide_buffer_t in the list. The tuple_count parameters determines the length of the list.

The return values are: -1: Signals an error. 0: Success and cache hit. 1: Success and cache miss.

◆ halide_memoization_cache_store()

int halide_memoization_cache_store ( void *  user_context,
const uint8_t cache_key,
int32_t  size,
struct halide_buffer_t realized_bounds,
int32_t  tuple_count,
struct halide_buffer_t **  tuple_buffers 
)

Given a cache key for a memoized result, currently constructed from the Func name and top-level Func name plus the arguments of the computation, store the result in the cache for futre access by halide_memoization_cache_lookup.

(The internals of the cache key should be considered opaque by this function.) Data is copied out from the inputs and inputs are unmodified. The last argument is a list if halide_buffer_t pointers which represents the outputs of the memoized Func. If the Func does not return a Tuple, there will only be one halide_buffer_t in the list. The tuple_count parameters determines the length of the list.

If there is a memory allocation failure, the store does not store the data into the cache.

◆ halide_memoization_cache_release()

void halide_memoization_cache_release ( void *  user_context,
void *  host 
)

If halide_memoization_cache_lookup succeeds, halide_memoization_cache_release must be called to signal the storage is no longer being used by the caller.

It will be passed the host pointer of one the buffers returned by halide_memoization_cache_lookup. That is halide_memoization_cache_release will be called multiple times for the case where halide_memoization_cache_lookup is handling multiple buffers. (This corresponds to memoizing a Tuple in Halide.) Note that the host pointer must be sufficient to get to all information the relase operation needs. The default Halide cache impleemntation accomplishes this by storing extra data before the start of the user modifiable host storage.

This call is like free and does not have a failure return.

◆ halide_memoization_cache_cleanup()

void halide_memoization_cache_cleanup ( )

Free all memory and resources associated with the memoization cache.

Must be called at a time when no other threads are accessing the cache.

◆ halide_create_temp_file()

int halide_create_temp_file ( void *  user_context,
const char *  prefix,
const char *  suffix,
char *  path_buf,
size_t  path_buf_size 
)

Create a unique file with a name of the form prefixXXXXXsuffix in an arbitrary (but writable) directory; this is typically $TMP or /tmp, but the specific location is not guaranteed.

(Note that the exact form of the file name may vary; in particular, the suffix may be ignored on non-Posix systems.) The file is created (but not opened), thus this can be called from different threads (or processes, e.g. when building with parallel make) without risking collision. Note that the caller is always responsible for deleting this file. Returns nonzero value if an error occurs.

◆ halide_msan_annotate_memory_is_initialized()

void halide_msan_annotate_memory_is_initialized ( void *  user_context,
const void *  ptr,
uint64_t  len 
)

Annotate that a given range of memory has been initialized; only used when Target::MSAN is enabled.

The default implementation uses the LLVM-provided AnnotateMemoryIsInitialized() function.

◆ halide_msan_annotate_buffer_is_initialized()

void halide_msan_annotate_buffer_is_initialized ( void *  user_context,
struct halide_buffer_t buffer 
)

Mark the data pointed to by the buffer_t as initialized (but not the buffer_t itself), using halide_msan_annotate_memory_is_initialized() for marking.

The default implementation takes pains to only mark the active memory ranges (skipping padding), and sorting into ranges to always mark the smallest number of ranges, in monotonically increasing memory order.

Most client code should never need to replace the default implementation.

◆ halide_msan_annotate_buffer_is_initialized_as_destructor()

void halide_msan_annotate_buffer_is_initialized_as_destructor ( void *  user_context,
void *  buffer 
)

◆ halide_error_bounds_inference_call_failed()

int halide_error_bounds_inference_call_failed ( void *  user_context,
const char *  extern_stage_name,
int  result 
)

Halide calls the functions below on various error conditions.

The default implementations construct an error message, call halide_error, then return the matching error code above. On platforms that support weak linking, you can override these to catch the errors individually. A call into an extern stage for the purposes of bounds inference failed. Returns the error code given by the extern stage.

◆ halide_error_extern_stage_failed()

int halide_error_extern_stage_failed ( void *  user_context,
const char *  extern_stage_name,
int  result 
)

A call to an extern stage failed.

Returned the error code given by the extern stage.

◆ halide_error_explicit_bounds_too_small()

int halide_error_explicit_bounds_too_small ( void *  user_context,
const char *  func_name,
const char *  var_name,
int  min_bound,
int  max_bound,
int  min_required,
int  max_required 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_bad_type()

int halide_error_bad_type ( void *  user_context,
const char *  func_name,
uint8_t  code_given,
uint8_t  correct_code,
uint8_t  bits_given,
uint8_t  correct_bits,
uint16_t  lanes_given,
uint16_t  correct_lanes 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_access_out_of_bounds()

int halide_error_access_out_of_bounds ( void *  user_context,
const char *  func_name,
int  dimension,
int  min_touched,
int  max_touched,
int  min_valid,
int  max_valid 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_buffer_allocation_too_large()

int halide_error_buffer_allocation_too_large ( void *  user_context,
const char *  buffer_name,
uint64_t  allocation_size,
uint64_t  max_size 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_buffer_extents_negative()

int halide_error_buffer_extents_negative ( void *  user_context,
const char *  buffer_name,
int  dimension,
int  extent 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_buffer_extents_too_large()

int halide_error_buffer_extents_too_large ( void *  user_context,
const char *  buffer_name,
int64_t  actual_size,
int64_t  max_size 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_constraints_make_required_region_smaller()

int halide_error_constraints_make_required_region_smaller ( void *  user_context,
const char *  buffer_name,
int  dimension,
int  constrained_min,
int  constrained_extent,
int  required_min,
int  required_extent 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_constraint_violated()

int halide_error_constraint_violated ( void *  user_context,
const char *  var,
int  val,
const char *  constrained_var,
int  constrained_val 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_param_too_small_i64()

int halide_error_param_too_small_i64 ( void *  user_context,
const char *  param_name,
int64_t  val,
int64_t  min_val 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_param_too_small_u64()

int halide_error_param_too_small_u64 ( void *  user_context,
const char *  param_name,
uint64_t  val,
uint64_t  min_val 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_param_too_small_f64()

int halide_error_param_too_small_f64 ( void *  user_context,
const char *  param_name,
double  val,
double  min_val 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_param_too_large_i64()

int halide_error_param_too_large_i64 ( void *  user_context,
const char *  param_name,
int64_t  val,
int64_t  max_val 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_param_too_large_u64()

int halide_error_param_too_large_u64 ( void *  user_context,
const char *  param_name,
uint64_t  val,
uint64_t  max_val 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_param_too_large_f64()

int halide_error_param_too_large_f64 ( void *  user_context,
const char *  param_name,
double  val,
double  max_val 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_out_of_memory()

int halide_error_out_of_memory ( void *  user_context)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_buffer_argument_is_null()

int halide_error_buffer_argument_is_null ( void *  user_context,
const char *  buffer_name 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_debug_to_file_failed()

int halide_error_debug_to_file_failed ( void *  user_context,
const char *  func,
const char *  filename,
int  error_code 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_unaligned_host_ptr()

int halide_error_unaligned_host_ptr ( void *  user_context,
const char *  func_name,
int  alignment 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_host_is_null()

int halide_error_host_is_null ( void *  user_context,
const char *  func_name 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_failed_to_upgrade_buffer_t()

int halide_error_failed_to_upgrade_buffer_t ( void *  user_context,
const char *  input_name,
const char *  reason 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_failed_to_downgrade_buffer_t()

int halide_error_failed_to_downgrade_buffer_t ( void *  user_context,
const char *  input_name,
const char *  reason 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_bad_fold()

int halide_error_bad_fold ( void *  user_context,
const char *  func_name,
const char *  var_name,
const char *  loop_name 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_bad_extern_fold()

int halide_error_bad_extern_fold ( void *  user_context,
const char *  func_name,
int  dim,
int  min,
int  extent,
int  valid_min,
int  fold_factor 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_fold_factor_too_small()

int halide_error_fold_factor_too_small ( void *  user_context,
const char *  func_name,
const char *  var_name,
int  fold_factor,
const char *  loop_name,
int  required_extent 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_requirement_failed()

int halide_error_requirement_failed ( void *  user_context,
const char *  condition,
const char *  message 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_specialize_fail()

int halide_error_specialize_fail ( void *  user_context,
const char *  message 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_no_device_interface()

int halide_error_no_device_interface ( void *  user_context)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_device_interface_no_device()

int halide_error_device_interface_no_device ( void *  user_context)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_host_and_device_dirty()

int halide_error_host_and_device_dirty ( void *  user_context)

Various other error conditions.

See the enum above for a description of each.

◆ halide_error_buffer_is_null()

int halide_error_buffer_is_null ( void *  user_context,
const char *  routine 
)

Various other error conditions.

See the enum above for a description of each.

◆ halide_can_use_target_features()

int halide_can_use_target_features ( uint64_t  features)

This function is called internally by Halide in some situations to determine if the current execution environment can support the given set of halide_target_feature_t flags.

The implementation must do the following:

– If there are flags set in features that the function knows cannot be supported, return 0. – Otherwise, return 1. – Note that any flags set in features that the function doesn't know how to test should be ignored; this implies that a return value of 1 means "not known to be bad" rather than "known to be good".

In other words: a return value of 0 means "It is not safe to use code compiled with these features", while a return value of 1 means "It is not obviously unsafe to use code compiled with these features".

The default implementation simply calls halide_default_can_use_target_features.

◆ halide_set_custom_can_use_target_features()

halide_can_use_target_features_t halide_set_custom_can_use_target_features ( halide_can_use_target_features_t  )

This function is called internally by Halide in some situations to determine if the current execution environment can support the given set of halide_target_feature_t flags.

The implementation must do the following:

– If there are flags set in features that the function knows cannot be supported, return 0. – Otherwise, return 1. – Note that any flags set in features that the function doesn't know how to test should be ignored; this implies that a return value of 1 means "not known to be bad" rather than "known to be good".

In other words: a return value of 0 means "It is not safe to use code compiled with these features", while a return value of 1 means "It is not obviously unsafe to use code compiled with these features".

The default implementation simply calls halide_default_can_use_target_features.

◆ halide_default_can_use_target_features()

int halide_default_can_use_target_features ( uint64_t  features)

This is the default implementation of halide_can_use_target_features; it is provided for convenience of user code that may wish to extend halide_can_use_target_features but continue providing existing support, e.g.

int halide_can_use_target_features(uint64_t features) { if (features & halide_target_somefeature) { if (!can_use_somefeature()) { return 0; } } return halide_default_can_use_target_features(features); }

◆ halide_upgrade_buffer_t()

int halide_upgrade_buffer_t ( void *  user_context,
const char *  name,
const buffer_t old_buf,
halide_buffer_t new_buf 
)

Copies host pointer, mins, extents, strides, and device state from an old-style buffer_t into a new-style halide_buffer_t.

The dimensions and type fields of the new buffer_t should already be set. Returns an error code if the upgrade could not be performed.

◆ halide_downgrade_buffer_t()

int halide_downgrade_buffer_t ( void *  user_context,
const char *  name,
const halide_buffer_t new_buf,
buffer_t old_buf 
)

Copies the host pointer, mins, extents, strides, and device state from a halide_buffer_t to a buffer_t.

Also sets elem_size. Useful for backporting the results of bounds inference.

◆ halide_downgrade_buffer_t_device_fields()

int halide_downgrade_buffer_t_device_fields ( void *  user_context,
const char *  name,
const halide_buffer_t new_buf,
buffer_t old_buf 
)

Copies the dirty flags and device allocation state from a new buffer_t back to a legacy buffer_t.

◆ halide_profiler_get_state()

struct halide_profiler_state* halide_profiler_get_state ( )

Get a pointer to the global profiler state for programmatic inspection.

Lock it before using to pause the profiler.

◆ halide_profiler_get_pipeline_state()

struct halide_profiler_pipeline_stats* halide_profiler_get_pipeline_state ( const char *  pipeline_name)

Get a pointer to the pipeline state associated with pipeline_name.

This function grabs the global profiler state's lock on entry.

◆ halide_profiler_reset()

void halide_profiler_reset ( )

Reset all profiler state.

WARNING: Do NOT call this method while any halide pipeline is running; halide_profiler_memory_allocate/free and halide_profiler_stack_peak_update update the profiler pipeline's state without grabbing the global profiler state's lock.

◆ halide_profiler_report()

void halide_profiler_report ( void *  user_context)

Print out timing statistics for everything run since the last reset.

Also happens at process exit.

◆ halide_float16_bits_to_float()

float halide_float16_bits_to_float ( uint16_t  )

Read bits representing a half precision floating point number and return the float that represents the same value.

◆ halide_float16_bits_to_double()

double halide_float16_bits_to_double ( uint16_t  )

Read bits representing a half precision floating point number and return the double that represents the same value.