Crate ispc

A small library meant to be used as a build dependency with Cargo for easily integrating ISPC code into Rust projects.

Using ispc-rs

You'll want to add a build script to your crate (build.rs), tell Cargo about it and add this crate as a build dependency and optionally as a runtime dependency if you plan to use the ispc_module macro or ISPC tasks.

# Cargo.toml
[package]
# ...
build = "build.rs"

[dependencies]
ispc = "0.3.4"

[build-dependencies]
ispc = "0.3.4"

Now you can use ispc to compile your code into a static library:

extern crate ispc;

fn main() {
    // Compile our ISPC library, this call will exit with EXIT_FAILURE if
    // compilation fails.
    ispc::compile_library("simple", &["src/simple.ispc"]);
}

Running cargo build should now build your ISPC files into a library and link your Rust application with it. For extra convenience the ispc_module macro is provided to import bindings to the library generated with rust-bindgen into a module of the same name. Note that all the functions imported will be unsafe as they're the raw C bindings to your lib.

#[macro_use]
extern crate ispc;

// Functions exported from simple will be callable under simple::*
ispc_module!(simple);

Some more complete examples can be found in the examples/ folder.

Compile-time Requirements

Both the ISPC compiler and libclang (for rust-bindgen) must be available in your path.

Windows Users

You'll need Visual Studio and will have to use the MSVC ABI version of Rust since ISPC and Clang link with MSVC on Windows. For bindgen to find libclang you'll need to copy libclang.lib to clang.lib and place it in your path.

Multiple ISPC Files: Unfortunately with multiple ISPC files when building with debug symbols some of the debug symbols for each compiled object will conflict, resulting in link errors and your program failing to compile. The workaround for this on Windows is to not build the ISPC code with debugging info if you're using multiple ISPC files, see the multi file examples.

Modules

exec	Defines the trait that must be implemented by ISPC task execution systems and provides a default threaded one for use.
instrument	Defines the trait that must be implemented by ISPC instrumentation callbacks structs and provides a default one.
opt	This module has various option flags and configs we can pass to ISPC, located here for convience and clutter reduction.
task	Defines structs for operating on ISPC task groups and getting chunks of a task to be scheduled on to threads

Macros

ispc_module

Convenience macro for generating the module to hold the raw/unsafe ISPC bindings.

Structs

Config

Extra configuration to be passed to ISPC

Functions

compile_library	Compile the list of ISPC files into a static library and generate bindings using bindgen. The library name should not contain a lib prefix or a lib extension like '.a' or '.lib', the appropriate prefix and suffix will be added based on the compilation target.
print_instrumenting_summary	Print out a summary of performace data gathered from instrumenting ISPC. Must enable instrumenting to have this record and print data, see Config::instrument.
set_instrument	If you have implemented your own instrument for logging ISPC performance data you can use this function to provide it for use instead of the default one. This function must be called before calling into ISPC code, otherwise the instrumenter will already be set to the default.
set_task_system	If you have implemented your own task system you can provide it for use instead of the default threaded one. This must be done prior to calling ISPC code which spawns tasks otherwise the task system will have already been initialized to Parallel, which you can also see as an example for implementing a task system.