Crate weld

Weld is a runtime for improving the performance of data-intensive applications. It optimizes across libraries and functions by expressing the core computations in libraries using a small common intermediate representation, similar to CUDA and OpenCL.

Using Weld

Weld is a small programming language that supports parallel loops and builders, which are declarative objects that specify how to build results. The parallel loops can be used in conjunction with the builders to build a result in parallel.

This crate contains the Weld compiler and runtime, though users only interact with the compiler. Users use Weld by constructing a Weld program (currently as a string), compiling the string into a runnable module, and then running the module with in-memory data.

Weld JITs code into the current process using LLVM. As a result, Weld users must have a version of LLVM installed on their machine (currently, Weld uses LLVM 6).

Example

The following program shows a minimal Weld program that adds two numbers:

#[repr(C)]
struct MyArgs {
    a: i32,
    b: i32,
}

let code = "|a: i32, b: i32| a + b";
let conf = &WeldConf::new();
let mut module = WeldModule::compile(code, conf).unwrap();

// Weld accepts a packed C struct as an argument.
let args = &MyArgs { a: 1, b: 50 };
let input = &WeldValue::new_from_data(args as *const _ as Data);

// A context manages memory.
let context = &mut WeldContext::new(conf).unwrap();

// Running a Weld module and reading a value out of it is unsafe!
unsafe {
    // Run the module, which returns a wrapper `WeldValue`.
    let result = module.run(context, input).unwrap();
    // The data is just a pointer: cast it to the expected type
    let data = result.data() as *const i32;

    let result = (*data).clone();
    assert_eq!(args.a + args.b, result);
}

Users write a Weld program as a string, compile it into a module, and then pass packed arguments into it to run the JITed code. The result is a pointer that represents the output of the Weld program: we can cast that to the appropriate pointer type and read it by dereferencing.

Modules

The WeldModule is the main entry point into Weld. Users can compile Weld programs using WeldModule::compile, and then run compiled programs using WeldModule::run.

The module functions can be configured in several ways. This configuration is controlled using the WeldConf struct, which is effectively a dictionary of String key/value pairs that control how a Weld program is compiled and run.

Values

Since Weld JITs code and implements a custom runtime, data passed in and out of it must be in a specific, C-compatible packed format. The Weld Github contains a plethora of information on how data should be formatted when passed into Weld, but in short, it is not safe to simply pass Rust objects into Weld.

WeldModule accepts and returns a wrapper struct called WeldValue, which wraps an opaque *const void that Weld reads depending on the argument and return types of the Weld program. Weld's main run function is thus unsafe: users need to guarantee that the data passed into Weld is properly formatted!

Passing Rust Values into Weld

Currently, users need to manually munge Rust values into a format that Weld understands, as specified here. Eventually, we may add a module in this crate that contains wrappers for some useful types. The current Rust types can be passed safely into Weld already:

• Primitive types such as i8, i16, and f32. These have a 1-1 correspondance with Weld.
• Rust structs with repr(C).

Notably, Vec<T> cannot be passed without adhering to the custom Weld format. Currently, that format is defined as:

#[repr(C)]
struct WeldVec<T> {
    ptr: *const T,
    len: i64,
}

There is thus a straightforward conversion from Vec<T> to a WeldVec<T>.

The data module defines layouts of Weld-compatible types, and also contains some methods for converting Rust values into Weld values.

Contexts

A context manages state such as allocation information. A context is passed into WeldModule::run and updated by the compiled Weld program.

The WeldContext struct wraps a context. Contexts are internally reference counted because values produced by Weld hold references to the context in which they are allocated. The memory backing a WeldContext is freed when all references to the context are dropped.

Re-exports

pub use crate::runtime::WeldRuntimeErrno;

Modules

ast	Defines the Weld abstract syntax tree.
data	Structures that can be passed into Weld.
runtime	Functions called from within the Weld runtime.

Macros

weld_err

A macro for creating a WeldError with a message and an unknown error code.

Structs

WeldConf	A struct used to configure compilation and the Weld runtime.
WeldContext	A context for a Weld program.
WeldError	An error when compiling or running a Weld program.
WeldModule	A compiled runnable Weld module.
WeldValue	A wrapper for data passed into and out of Weld.

Enums

WeldLogLevel

A logging level for the compiler.

Constants

BUILD	A build ID.
CONF_DUMP_CODE_DEFAULT	Default setting for whether to dump code.
CONF_DUMP_CODE_DIR_DEFAULT	Default directory for dumping code.
CONF_DUMP_CODE_DIR_KEY	Specifies the directory to dump code into.
CONF_DUMP_CODE_FILENAME_KEY	Specifies the filename prefix for dumped code.
CONF_DUMP_CODE_FORMATS_KEY	Specifies the formats to dump for dumped code.
CONF_DUMP_CODE_KEY	Enables dumping code during compilation.
CONF_ENABLE_BOUNDS_CHECKS_DEFAULT	Default setting for whether to enable bounds checking.
CONF_ENABLE_BOUNDS_CHECKS_KEY	Enables runtime bounds checking for loops before executing them.
CONF_EXPERIMENTAL_PASSES_DEFAULT	Default setting for whether to enable experimental (unstable) optimizations.
CONF_EXPERIMENTAL_PASSES_KEY	Enables experimental (unstable) optimizations.
CONF_LLVM_FUNC_OPTS_DEFAULT	Default LLVM function passes setting.
CONF_LLVM_FUNC_OPTS_KEY	Toggles per-function optimizations.
CONF_LLVM_MODULE_OPTS_DEFAULT	Default LLVM module passes setting.
CONF_LLVM_MODULE_OPTS_KEY	Toggles full module optimizations.
CONF_LLVM_OPTIMIZATION_LEVEL_DEFAULT	Default LLVM optimization level.
CONF_LLVM_OPTIMIZATION_LEVEL_KEY	Set the LLVM optimization level.
CONF_LLVM_RUN_FUNC_NAME_DEFAULT	Default symbol name for LLVM entry-point function.
CONF_LLVM_RUN_FUNC_NAME_KEY	Sets the symbol name of the entry-point function.
CONF_LLVM_TARGET_PASSES_DEFAULT	Default LLVM target analysis passes.
CONF_LLVM_TARGET_PASSES_KEY	Toggles LLVM target passes.
CONF_LLVM_UNROLLER_DEFAULT	Default LLVM loop unroller setting.
CONF_LLVM_UNROLLER_KEY	Toggles LLVM loop unrolling.
CONF_LLVM_VECTORIZER_DEFAULT	Default LLVM loop vectorizer setting.
CONF_LLVM_VECTORIZER_KEY	Toggles LLVM vectorization.
CONF_MEMORY_LIMIT_DEFAULT	Default memory limit.
CONF_MEMORY_LIMIT_KEY	Bytes a single WeldContext is allowed to allocate.
CONF_OPTIMIZATION_PASSES_DEFAULT	Default set of optimization passes.
CONF_OPTIMIZATION_PASSES_KEY	Specifies an ordered list of the optimizations to apply to a Weld program.
CONF_SIR_OPT_DEFAULT	Default setting for SIR optimization.
CONF_SIR_OPT_KEY	Enables internal Sequential IR (SIR) optimizations.
CONF_THREADS_DEFAULT	Default number of threads.
CONF_THREADS_KEY	Specifies the number of threads to use during execution.
CONF_TRACE_RUN_DEFAULT	Default setting for whether to trace SIR instructions.
CONF_TRACE_RUN_KEY	Specifies whether tracing should be enabled when compiling the program.
VERSION	Weld version.

Functions

load_linked_library	Load a dynamic library that a Weld program can access.
set_log_level	Enables logging to stderr in Weld with the given log level.

Type Definitions

Data	A wrapper for a C pointer.
DataMut	A wrapper for a mutable C pointer.
RunId	An identifier that uniquely identifies a call to WeldModule::run.
WeldResult	A Result that uses WeldError.