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

Fundamentally, 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 3.8).

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 accept packed C structs as an argument.
let ref args = MyArgs { a: 1, b: 50 };
let ref input = WeldValue::new_from_data(args as *const _ as Data);

// 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(conf, 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>.

Re-exports

pub use ffi::*;

Modules

ast

Abstract syntax tree for Weld.

code_builder
common

Common functionality or data types shared by the runtime and the weld compiler.

ffi
runtime
util

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.

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.

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. This function is ignored if it has already been called once, or if some other code in the process has initialized logging using Rust's log crate.

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.