Crate weld[][src]

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 buid 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 ref conf = WeldConf::new();
let mut module = WeldModule::compile(code, conf).unwrap();

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

// A context manages memory.
let ref mut context = 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:

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 runtime::WeldRuntimeErrno;

Modules

ast

Defines the Weld abstract syntax tree.

data

Structures that can be passed into Weld.

ffi

C-compatible foreign function interface to 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_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.