crabgrind allows Rust programs running under Valgrind to interact with the tools and virtualized environment.

Valgrind's “client request interface” is primarily accessible through a set of C macros in Valgrind's header files. However, these macros cannot be utilized in languages that lack support for C-preprocessor, such as Rust. To address this, crabgrind wraps “client request interface” macros with C functions and expose this API to Rust programs.

This library is essentially a wrapper. It only adds type conversions and some structure, while all the real things happens inside Valgrind.

Table of Contents

• Table of Contents
• Valgrind 3 API Coverage
• Quickstart
• Examples
• Overhead
• Safety
• Development
• License

Valgrind 3 API coverage

• Supported tool-specific client request interface: valgrind, callgrind, memcheck, helgrind, massif, cachegrind
• Monitor commands interface

Quickstart

crabgrind does not link against Valgrind but instead reads its header files, which must be accessible during build.

If you have installed Vallgrind using OS-specific package manager, the paths to the headers are likely to be resolved automatically by cc.

In case of manual installation or any missing file error, you can set the path to the Valgrind headers location through the DEP_VALGRIND environment variable. For example:

DEP_VALGRIND=/usr/include cargo build

add dependency Cargo.toml

[dependencies]
crabgrind = "0.1"

use some of the Valgrind's API

use crabgrind as cg;

fn main() {
    if matches!(cg::run_mode(), cg::RunMode::Native) {
        println!("run me under Valgrind");
    } else {
        cg::println!("Hey, Valgrind!");
    }
}

and run under Valgrind,

using cargo-valgrind:

cargo valgrind run

manually:

cargo build

valgrind ./target/debug/appname

Examples

• Print current function stack-trace to the Valgrind log
• Exclude expensive initialization code from the measurements
• Run a closure on the real CPU while running under Valgrind
• Save current memory usage snapshot to a file
• Dump Callgrind counters on a function basis

Overhead

from Valgrind docs

The code added to your binary has negligible performance impact: on x86, amd64, ppc32, ppc64 and ARM, the overhead is 6 simple integer instructions and is probably undetectable except in tight loops.

... the code does nothing when not run on Valgrind, so you are not forced to run your program under Valgrind just because you use the macros in this file.

Although your loops should be very tight (like a well-executed dance move) to notice any impact, keep in mind that:

• Wrapping each macros in a function implies function call overhead regardless of the run mode. This can potentially impact the performance of your Rust program.
• Functions that return std::result::Result involve branching, which can also have an impact on performance.
• Functions that take strings as parameters internally convert them to std::ffi::CString, which can introduce additional overhead.

Safety

No

License

crabgrind is distributed under MIT license.

Valgrind itself is a GPL2, however valgrind/*.h headers are distributed under a BSD-style license, so we can use them without worrying about license conflicts.