Rust · Rust

Using C++ from Rust: how a safe wrapper turns a use-after-free into a compile error

On this page
  1. The same bug, written twice
  2. What unsafe really is
  3. The C boundary
  4. #[repr(C)] and padding
  5. The safe wrapper
  6. unsafe impl Send and Sync: the fourth superpower
  7. Panics and callbacks
  8. No operating system underneath: #![no_std]
  9. What I take away

The same bug, written twice#

This post revolves around a small, real library: a key-value store written in C++ on top of std::unordered_map, with a C API, used from Rust through a safe wrapper. All the code compiles, and I've run it on my machine. Let's start with a twenty-one-line C++ program:

dangling.cpp
// cl /std:c++20 /EHsc /W4 /Zi /fsanitize=address dangling.cpp kv.cpp
// The bug: keep the pointer from kv_get and use it after a kv_set.
#include "kv.h"
#include <cstdio>

int main() {
    kv* db = kv_new();
    // 27 characters: more than std::string keeps inside the object
    // itself (15 or 22, depending on the library), so it goes on the heap.
    kv_set(db, "email", "ana.garcia.tome@example.com");

    // Points inside the std::string that holds the value.
    const char* email = kv_get(db, "email");

    // A longer value doesn't fit in the current buffer: std::string gets
    // a new one and frees the old one, which `email` still points to.
    kv_set(db, "email", "ana.garcia.fernandez.tome@example-company.com");

    std::printf("%s\n", email);  // reads memory that was freed
    kv_free(db);
}

It compiles with cl /W4 without a single warning, and also with g++ -Wall -Wextra -pedantic. But run it with AddressSanitizer, which watches every memory access while the program runs, and this shows up.

This is the real output on my machine, an Intel Core i9-14900KF with Windows 11, with MSVC and AddressSanitizer (an extract: […] marks the lines removed):

output
==17532==ERROR: AddressSanitizer: heap-use-after-free on address 0x126bd17a0760 […]
READ of size 2 at 0x126bd17a0760 thread T0
    […]
    #12 0x7ff78e401094 in main dangling.cpp:19
    […]
0x126bd17a0760 is located 0 bytes inside of 32-byte region [0x126bd17a0760,0x126bd17a0780)
freed by thread T0 here:
    […]
    #8 0x7ff78e401926 in `anonymous namespace'::Store::set kv.cpp:22
    #9 0x7ff78e4012b6 in kv_set kv.cpp:53
    #10 0x7ff78e401083 in main dangling.cpp:17
    […]
previously allocated by thread T0 here:
    […]
    #10 0x7ff78e401926 in `anonymous namespace'::Store::set kv.cpp:22
    #11 0x7ff78e4012b6 in kv_set kv.cpp:53
    #12 0x7ff78e401055 in main dangling.cpp:10
    […]
SUMMARY: AddressSanitizer: heap-use-after-free […]

The trace reads from the bottom up. The memory was allocated at line 10, by the first kv_set. It was freed at line 17, by the second kv_set, inside std::string::operator= (kv.cpp:22). And it was read at line 19, in the printf: a use-after-free. The 32-byte region is the buffer where the first value lived in MSVC's library.

The culprit isn't the hash table. std::unordered_map doesn't invalidate pointers or references to its elements when it reorganises itself (the rehash); the standard says so in [unord.req.general]. The culprit is the std::string: its non-const member functions, such as assignment, may invalidate pointers to its contents ([string.require]). If the new value doesn't fit in the current buffer, the assignment allocates a new one and frees the old one, and email still points to the old one.

That's why the first value is 27 characters long. A short string fits inside the std::string object itself, without going to the heap: up to 15 characters in MSVC and in libstdc++, up to 22 in libc++. With a short value no memory would be freed, and AddressSanitizer would see nothing.

Now, the same bug written in Rust, with the wrapper we'll look at in this post:

dangling.rs
// cargo build --example dangling --features show-bug
// Doesn't compile, on purpose.
// The same bug as dangling.cpp, written in Rust with the wrapper.
use kvdemo::Kv;

fn main() {
    let mut db = Kv::new().unwrap();
    db.set("email", "ana.garcia.tome@example.com").unwrap();

    // email is a &str borrowed from db
    let email = db.get("email").unwrap();

    db.set("email", "ana.garcia.fernandez.tome@example-company.com")
        .unwrap();

    println!("{email}");
}

This is the real output on my machine, with cargo build:

output
error[E0502]: cannot borrow `db` as mutable because it is also borrowed as immutable
  --> examples\dangling.rs:13:5
   |
11 |     let email = db.get("email").unwrap();
   |                 -- immutable borrow occurs here
12 |
13 |     db.set("email", "ana.garcia.fernandez.tome@example-company.com")
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ mutable borrow occurs here
...
16 |     println!("{email}");
   |                ----- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `kvdemo` (example "dangling") due to 1 previous error

It doesn't compile. The borrow checker sees that email is a borrow of db that is still alive at line 16, and doesn't let set modify it in the meantime.

But it pays to be precise here, because this is the idea behind the whole post: Rust knows nothing about std::string. The compiler doesn't know C++'s invalidation rules. What it enforces is the contract I wrote in the wrapper: "the pointer from kv_get is valid until the next kv_set or kv_free", expressed as a &str whose lifetime depends on &self, plus a set that takes &mut self. If the wrapper were written wrong, for example if get returned a &'static str, it would compile and the bug would be back.

In A secret that ran code I said that Rust removes whole classes of memory bugs, but not bugs of meaning. This is the other side of it: a C++ memory bug that Rust does prevent, because the wrapper expresses it in types. The borrow checker is enforcing a C++ rule because someone wrote it into Rust's types.

What unsafe really is#

Writing that wrapper takes unsafe, and it's easy to misunderstand. unsafe doesn't turn off the borrow checker or any other compiler check. According to the Rust book, it unlocks exactly five superpowers:

  1. dereferencing a raw pointer;
  2. calling an unsafe function, including any declared through FFI;
  3. accessing or modifying a static mut variable;
  4. implementing an unsafe trait;
  5. accessing the fields of a union.

Everything else is checked the same way, inside and outside the block. It's what makes Rust so safe, as we covered in Why Rust remains the safest language in 2026: those guarantees stay on, and unsafe only opens those five doors.

In one sentence

unsafe doesn't switch the compiler off: it unlocks five operations and makes you responsible for getting them right. Everything else is still checked.

In my Rust systems guide I sum it up like this: unsafe isn't a way to silence the compiler, it's a promise you make. You're telling the compiler you've checked by hand what it can't check. If the promise is false, the result is the same undefined behaviour as in C++.

Three of the five show up in this post's code:

SuperpowerWhere it shows up
Dereferencing a raw pointer&mut *ctx.cast::<Ctx<F>>(), in for_each's trampoline
Calling an unsafe functionEvery call to ffi::kv_*
Implementing an unsafe traitunsafe impl Send and unsafe impl Sync
static mut and unionNot used

And one convention the whole code follows: every unsafe block has a // SAFETY: comment above it that justifies why the promise holds. It's the usual practice in Rust, and it makes every promise reviewable.

The C boundary#

Rust and C++ don't talk to each other directly. They talk through C, the common language of almost every language: C's calling convention and types both sides understand the same way.

YOUR CODE safe Rust: new, set, get, for_each WRAPPER lib.rs: all the unsafe, each with its SAFETY extern "C": only pointers, integers and repr(C) structs C API kv.h: opaque type, error codes C++ kv.cpp: exceptions, std::unordered_map
Fig. 1 — The boundary. Rust above the line, C++ below it. Neither a panic nor an exception crosses it: catch_unwind stops them above and try/catch below.

This is the whole API, the file kv.h:

kv.h
// kv.h: C API of a key-value store written in C++.
// Everything that crosses this boundary is C: pointers, integers and
// plain structs.
#pragma once
#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
#define KV_NOEXCEPT noexcept
extern "C" {
#else
#define KV_NOEXCEPT
#endif

// Opaque: API users only handle pointers, never the inside.
typedef struct kv kv;

// Error codes: C++ exceptions don't cross the boundary.
enum { KV_OK = 0, KV_EINVAL = 1, KV_ENOMEM = 2, KV_EINTERNAL = 3 };

// Struct shared by value: its memory layout has to match byte for
// byte on both sides.
typedef struct kv_stats {
    uint8_t  version;  // struct version
    uint64_t entries;  // number of entries
    uint32_t buckets;  // buckets of the hash table
} kv_stats;

// Returns 0 to keep iterating, any other value to stop.
typedef int (*kv_visit_fn)(const char* key, const char* value, void* ctx);

// NULL if out of memory. kv_free accepts NULL.
kv*         kv_new(void) KV_NOEXCEPT;
void        kv_free(kv* self) KV_NOEXCEPT;
int         kv_set(kv* self, const char* key,
                   const char* value) KV_NOEXCEPT;
// The returned pointer is valid until the next kv_set or kv_free.
const char* kv_get(const kv* self, const char* key) KV_NOEXCEPT;
void        kv_stats_get(const kv* self, kv_stats* out) KV_NOEXCEPT;
void        kv_for_each(const kv* self, kv_visit_fn visit,
                        void* ctx) KV_NOEXCEPT;

#ifdef __cplusplus
}
#endif

Four decisions worth a look:

  • Opaque type. typedef struct kv kv; declares the type without showing what's inside. API users only handle pointers to kv and never see the inside, so the inside can change without breaking anyone.
  • Error codes instead of exceptions. C has no exceptions, and Rust doesn't know what to do with them either. Every error becomes a number.
  • extern "C". It asks C++ to use C's calling convention and not to decorate the names, so from outside they show up as kv_new, kv_set…
  • The KV_NOEXCEPT macro. In C++17, noexcept is part of the function's type, so the header's declaration has to match the definition. In C, the macro expands to nothing.

Below the boundary, the library is ordinary C++. This fragment of kv.cpp is the class that holds the data, which throws std::invalid_argument if the key is empty, and the kv_set function, which translates each exception into an error code:

kv.cpp
// Plain C++: throws exceptions and uses the standard library.
class Store {
public:
    void set(const char* key, const char* value) {
        if (key == nullptr || *key == '\0')
            throw std::invalid_argument("empty key");
        map_[key] = value;
    }
    const std::string* get(const char* key) const {
        auto it = map_.find(key);
        return it == map_.end() ? nullptr : &it->second;
    }
    const auto& items() const { return map_; }

private:
    std::unordered_map<std::string, std::string> map_;
};
kv.cpp
// No exception leaves this function: each one becomes an error
// code.
int kv_set(kv* self, const char* key, const char* value) noexcept {
    try {
        self->set(key, value);
        return KV_OK;
    } catch (const std::invalid_argument&) {
        return KV_EINVAL;
    } catch (const std::bad_alloc&) {
        return KV_ENOMEM;
    } catch (...) {
        return KV_EINTERNAL;
    }
}

kv_set is marked noexcept, and that isn't magic. If an exception tried to leave a noexcept function, C++ would call std::terminate ([except.handle]): the program would abort anyway, although in a defined way, instead of unwinding the stack into Rust. That's why kv_set catches them all and turns them into codes. The same goes for kv_for_each, which calls a callback it doesn't control:

kv.cpp
// noexcept: if the callback threw, std::terminate instead of
// unwinding the stack into whoever called us.
void kv_for_each(const kv* self, kv_visit_fn visit, void* ctx) noexcept {
    for (const auto& [key, value] : self->items())
        if (visit(key.c_str(), value.c_str(), ctx) != 0)
            break;
}
The golden rule

Nothing that unwinds crosses the C boundary: neither C++ exceptions nor Rust panics. They're caught on their own side and turned into data.

And there's one line in the header that matters more than any other, even though it looks like just another comment: "The returned pointer is valid until the next kv_set or kv_free". It's kv_get's contract, and it's the rule the wrapper is going to turn into a lifetime.

This is how the library is used from Rust, with the safe wrapper:

main.rs
// cargo run
// Uses the C++ library from Rust through the safe wrapper.
use kvdemo::{Kv, KvError, ffi::KvStats};

// The same fields as KvStats, with Rust's default layout.
#[allow(dead_code)]
struct StatsRustLayout {
    version: u8,
    entries: u64,
    buckets: u32,
}

fn main() -> Result<(), KvError> {
    println!("size_of KvStats (repr C) = {}", size_of::<KvStats>());
    println!(
        "size_of same fields (repr Rust) = {}",
        size_of::<StatsRustLayout>()
    );

    let mut db = Kv::new()?;
    db.set("lang", "rust")?;
    db.set("ffi", "c++")?;
    println!("get(lang) = {:?}", db.get("lang"));
    println!("get(nope) = {:?}", db.get("nope"));

    // Errors from C++ (an exception) and from Rust (a NUL inside the
    // string)
    println!("set(\"\") = {:?}", db.set("", "x"));
    println!("set(\"a\\0b\") = {:?}", db.set("a\0b", "x"));

    let s = db.stats();
    println!(
        "stats: version={} entries={} buckets={}",
        s.version, s.entries, s.buckets
    );

    let mut keys = Vec::new();
    db.for_each(|k, _| {
        keys.push(k.to_owned());
        true
    });
    keys.sort();
    println!("keys = {keys:?}");
    Ok(())
}

This is the real output on my machine, with cargo run:

output
size_of KvStats (repr C) = 24
size_of same fields (repr Rust) = 16
get(lang) = Some("rust")
get(nope) = None
set("") = Err(InvalidKey)
set("a\0b") = Err(InteriorNul)
stats: version=1 entries=2 buckets=8
keys = ["ffi", "lang"]

Errors come from both sides of the boundary. set("") returns Err(InvalidKey): it's a C++ exception, std::invalid_argument, turned into an error code by kv_set. set("a\0b") returns Err(InteriorNul) without ever reaching C++: a C string ends at the first NUL, so it can't contain one inside, and CString::new rejects it before it crosses.

One detail in the output: buckets=8 is what MSVC's standard library does. A different standard library gives a different number of buckets.

#[repr(C)] and padding#

Besides pointers and integers, one struct crosses the boundary by value: kv_stats. For that, both sides have to agree on its memory layout, byte for byte. With three fields, uint8_t version, uint64_t entries and uint32_t buckets, C's alignment rules give:

FieldBytes
version1
Padding, to align entries to 87
entries8
buckets4
Trailing padding, so the size is a multiple of 84
Total24

Both sides check it at compile time. In C++, in kv.cpp:

kv.cpp
// kv_stats's layout is part of the API: if it changes, the build
// fails here. 1 + 7 (padding) + 8 + 4 + 4 (padding) = 24 bytes.
static_assert(sizeof(kv_stats) == 24);
static_assert(alignof(kv_stats) == 8);

And in Rust, in lib.rs, with the same struct marked #[repr(C)] and an assertion evaluated at compile time:

lib.rs
    /// The same memory layout as `kv_stats` in C.
    #[repr(C)]
    #[derive(Debug, Default, Clone, Copy)]
    pub struct KvStats {
        pub version: u8,
        pub entries: u64,
        pub buckets: u32,
    }
lib.rs
// If the memory layout doesn't match C's, it doesn't compile.
const _: () = assert!(size_of::<ffi::KvStats>() == 24);
const _: () = assert!(align_of::<ffi::KvStats>() == 8);

If either side changes, it doesn't compile. The first two lines of the cargo run output show why #[repr(C)] is needed: 24 bytes with it, and 16 with the same fields and Rust's default layout (the StatsRustLayout struct in main.rs).

Those 16 bytes deserve a caveat: they're not guaranteed. The Rust Reference says that, with the default layout, the order of the fields is unspecified. 16 is what this compiler, rustc 1.98.1, does: it arranges the fields differently to save padding. The only thing guaranteed is #[repr(C)].

In my C++ systems guide I teach the same thing from the other side. struct Bad { char a; int x; char b; } takes about 12 bytes, and struct Good { int x; char a; char b; }, with the same fields in a different order, about 8. In C++ you reorder by hand. Rust reorders on its own when you don't ask for repr(C), and that's exactly why a struct that crosses the boundary has to carry it. In my Rust guide I put it like this: without #[repr(C)], a struct shared with C has no layout guarantee at all.

The safe wrapper#

All of the crate's unsafe lives in a single file, lib.rs. Let's go through it piece by piece.

First, the declaration of the C functions:

lib.rs
    unsafe extern "C" {
        // Takes no pointers: calling it can't break anything.
        pub safe fn kv_new() -> *mut Kv;
        pub fn kv_free(this: *mut Kv);
        pub fn kv_set(
            this: *mut Kv,
            key: *const c_char,
            value: *const c_char,
        ) -> c_int;
        pub fn kv_get(
            this: *const Kv,
            key: *const c_char,
        ) -> *const c_char;
        pub fn kv_stats_get(this: *const Kv, out: *mut KvStats);
        pub fn kv_for_each(
            this: *const Kv,
            visit: KvVisitFn,
            ctx: *mut c_void,
        );
    }

Since the 2024 edition, extern blocks have to carry unsafe: declaring an external function is already a promise about its signature, one the compiler can't check. Inside the block, each function can be marked safe, stable since Rust 1.82. Here kv_new is a safe fn because it takes no pointers: calling it can't break anything. The rest are still unsafe to call.

Next, the opaque type on the Rust side:

lib.rs
    /// Opaque type: no accessible fields and no known size, and the
    /// marker leaves it without automatic Send, Sync or Unpin.
    #[repr(C)]
    pub struct Kv {
        _data: (),
        _marker: PhantomData<(*mut u8, PhantomPinned)>,
    }

It's the form the Nomicon recommends: a struct with no useful fields, with a PhantomData<(*mut u8, PhantomPinned)> marker that leaves it without automatic Send, Sync or Unpin. A raw pointer is neither Send nor Sync, and PhantomPinned removes Unpin, so Rust assumes nothing we don't know. My guide used _private: [u8; 0]; the Nomicon adds the marker.

Then, the public type: a non-null pointer to the C++ object, and a Drop that frees it.

lib.rs
/// The store, seen from Rust: sole owner of the C++ object.
pub struct Kv {
    ptr: NonNull<ffi::Kv>,
}
lib.rs
impl Drop for Kv {
    fn drop(&mut self) {
        // SAFETY: the pointer came from kv_new and is freed once.
        unsafe { ffi::kv_free(self.ptr.as_ptr()) };
    }
}

This is RAII, the same as in C++. In my Rust guide I describe it like this: Drop is Rust's destructor, called automatically, exactly once. In the C++ one I explain it with a File class that opens the file with fopen in the constructor and closes it with fclose in the destructor. Here, the C++ object is freed with kv_free when the Kv goes out of scope, no matter what.

And now, the heart of the post, set and get:

lib.rs
    pub fn set(&mut self, key: &str, value: &str) -> Result<(), KvError> {
        let key = CString::new(key).map_err(|_| KvError::InteriorNul)?;
        let value =
            CString::new(value).map_err(|_| KvError::InteriorNul)?;
        // SAFETY: the pointer is valid while self exists, and &mut self
        // guarantees nobody else uses it. Both strings end in NUL and
        // live until the end of the call.
        let code = unsafe {
            ffi::kv_set(self.ptr.as_ptr(), key.as_ptr(), value.as_ptr())
        };
        match code {
            ffi::KV_OK => Ok(()),
            ffi::KV_EINVAL => Err(KvError::InvalidKey),
            ffi::KV_ENOMEM => Err(KvError::OutOfMemory),
            _ => Err(KvError::Internal),
        }
    }

    /// The returned &str points into C++ memory, and its lifetime is
    /// tied to &self: while it exists, nobody can call set, which
    /// takes &mut self.
    ///
    /// ```compile_fail,E0502
    /// let mut db = kvdemo::Kv::new().unwrap();
    /// db.set("k", "ana.garcia.tome@example.com").unwrap();
    /// let v = db.get("k").unwrap();
    /// db.set("k", "ana.garcia.fernandez.tome@example-company.com")
    ///     .unwrap();
    /// println!("{v}");
    /// ```
    pub fn get(&self, key: &str) -> Option<&str> {
        let key = CString::new(key).ok()?;
        // SAFETY: valid pointer and NUL-terminated key.
        let value =
            unsafe { ffi::kv_get(self.ptr.as_ptr(), key.as_ptr()) };
        if value.is_null() {
            return None;
        }
        // SAFETY: kv_get returns a NUL-terminated string that lives
        // until the next kv_set or kv_free, and neither of them can
        // happen while the borrow of self that this &str comes from
        // is alive.
        unsafe { CStr::from_ptr(value) }.to_str().ok()
    }

Here's the header's contract, translated into types. set takes &mut self: an exclusive borrow. get takes &self and returns an Option<&str> whose lifetime is tied to that &self. While the &str exists, the borrow of db is still alive, and nobody can get the &mut self that set needs. The last SAFETY comment in get is the key to the bug at the start: the &str can point into C++ memory because kv_get's contract and Rust's borrowing rules say the same thing.

Above get there's a doctest marked compile_fail,E0502, with the same bug. cargo test compiles it on every run, and the test passes only if it does not compile, and with that error. If someone changed the wrapper and the bug compiled again, the test would fail.

Fun fact

A compile_fail doctest is a test that passes if the code does not compile. It turns "this shouldn't compile" into something checked every time, instead of a promise in a comment.

This is the real output on my machine, with cargo test:

output
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
test a_panic_in_the_callback_comes_back_to_rust ... ok
test errors_from_both_sides_of_the_boundary ... ok
test for_each_visits_every_entry_and_can_stop ... ok
test set_get_and_overwrite ... ok
test stats_cross_the_boundary_by_value ... ok
test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
test src\lib.rs - Kv::get (line 119) - compile fail ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.04s

The last line with ok is that doctest: compile fail ... ok.

The wrapper prevents one more bug. This program tries to modify the store while iterating over it:

reentrant.rs
// cargo build --example reentrant --features show-bug
// Doesn't compile, on purpose: modifying the store while iterating.
// In C++, a kv_set inside kv_for_each's callback could trigger a
// rehash and invalidate the iterator.
use kvdemo::Kv;

fn main() {
    let mut db = Kv::new().unwrap();
    db.set("a", "1").unwrap();
    db.for_each(|k, _| {
        db.set(&format!("{k}-copy"), "x").unwrap();
        true
    });
}

This is the real output on my machine, with cargo build:

output
error[E0502]: cannot borrow `db` as mutable because it is also borrowed as immutable
  --> examples\reentrant.rs:10:17
   |
10 |     db.for_each(|k, _| {
   |     -- -------- ^^^^^^ mutable borrow occurs here
   |     |  |
   |     |  immutable borrow later used by call
   |     immutable borrow occurs here
11 |         db.set(&format!("{k}-copy"), "x").unwrap();
   |         -- second borrow occurs due to use of `db` in closure

For more information about this error, try `rustc --explain E0502`.
error: could not compile `kvdemo` (example "reentrant") due to 1 previous error

for_each takes &self and the closure needs &mut db to call set: the two borrows clash. In C++ the equivalent, calling kv_set inside kv_for_each's callback, compiles without complaint. And if the insertion triggers a rehash, it invalidates the iterator the loop is using ([unord.req.general]).

unsafe impl Send and Sync: the fourth superpower#

The opaque type is neither Send nor Sync, so Kv wouldn't be either, and it couldn't be used from several threads. Allowing that takes two explicit promises:

lib.rs
// SAFETY: Kv is the sole owner of the C++ object, and the object
// doesn't depend on the thread that created it: it can move threads.
unsafe impl Send for Kv {}

// SAFETY: with &Kv you only reach kv_get, kv_stats_get and
// kv_for_each, which only call const member functions of
// std::unordered_map. The C++ standard library guarantees that those
// calls, made at once from several threads, cause no data races.
unsafe impl Sync for Kv {}

Send is easy: Kv is the sole owner of the C++ object, and the object doesn't depend on the thread that created it. Sync is more delicate, because it means several threads can use &Kv at the same time. The justification is in the C++ standard, in [res.on.data.races]: a standard library function only modifies the objects it accesses through non-const arguments, including this. That's why several calls to const functions of the same unordered_map, from several threads at once, cause no data races. And with a &Kv you only reach kv_get, kv_stats_get and kv_for_each, which only call const member functions.

Careful, though, because that promise depends on today's code. If someone adds a cache to kv_get tomorrow that gets modified on every read, the promise breaks and the compiler won't notice. That's exactly what unsafe means: the compiler takes your word for it.

With the promise made, four threads can read at once:

threads.rs
// cargo run --example threads
// Four threads read the same C++ store at once. It compiles because
// Kv is Sync: the promise of `unsafe impl Sync` in lib.rs.
use kvdemo::Kv;
use std::thread;

fn main() {
    let mut db = Kv::new().unwrap();
    for i in 0..1000 {
        db.set(&format!("key{i}"), &format!("value{i}")).unwrap();
    }

    let db = &db; // read-only from here on
    let found: usize = thread::scope(|s| {
        let workers: Vec<_> = (0..4)
            .map(|t| {
                s.spawn(move || {
                    (0..1000)
                        .filter(|i| i % 4 == t)
                        .filter(|i| db.get(&format!("key{i}")).is_some())
                        .count()
                })
            })
            .collect();
        workers.into_iter().map(|w| w.join().unwrap()).sum()
    });

    println!("found {found} of 1000 keys from 4 threads");
}

This is the real output on my machine, with cargo run:

output
found 1000 of 1000 keys from 4 threads

And to see that the promise is needed, I temporarily commented out unsafe impl Sync for Kv {}. This is the real output on my machine, with cargo build (the first 15 lines):

output
error[E0277]: `NonNull<kvdemo::ffi::Kv>` cannot be shared between threads safely
   --> examples\threads.rs:17:25
    |
 17 |                   s.spawn(move || {
    |  ___________________-----_^
    | |                   |
    | |                   required by a bound introduced by this call
 18 | |                     (0..1000)
 19 | |                         .filter(|i| i % 4 == t)
 20 | |                         .filter(|i| db.get(&format!("key{i}")).is_some())
 21 | |                         .count()
 22 | |                 })
    | |_________________^ `NonNull<kvdemo::ffi::Kv>` cannot be shared between threads safely
    |
    = help: within `kvdemo::Kv`, the trait `Sync` is not implemented for `NonNull<kvdemo::ffi::Kv>`
[…]

Rust won't let you share a raw pointer between threads until someone takes responsibility for it.

Panics and callbacks#

kv_for_each calls a Rust function from C++. What happens if that function calls panic!? This program tries it without the wrapper, calling the C API directly:

panic_abort.rs
// cargo run --example panic_abort
// An extern "C" callback that panics, without the wrapper: the
// panic tries to leave an extern "C" function and the process aborts.
use kvdemo::ffi;
use std::ffi::{c_char, c_int, c_void};

extern "C" fn visit(
    _key: *const c_char,
    _value: *const c_char,
    _ctx: *mut c_void,
) -> c_int {
    panic!("something went wrong in the callback");
}

fn main() {
    let db = ffi::kv_new();
    // SAFETY: db comes from kv_new; the c"..." literals end in NUL.
    unsafe {
        ffi::kv_set(db, c"lang".as_ptr(), c"rust".as_ptr());
        ffi::kv_for_each(db, visit, std::ptr::null_mut());
        ffi::kv_free(db);
    }
    println!("never printed");
}

(The c"lang" literals are C strings with their trailing NUL, written directly in Rust; they've been stable since Rust 1.77.)

This is the real output on my machine, with cargo run (an extract, without the backtrace):

output
thread 'main' (14964) panicked at examples\panic_abort.rs:12:5:
something went wrong in the callback
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

thread 'main' (14964) panicked at /rustc/48a229ceaefd4985c50990b14116b6d856af0985/library\core\src\panicking.rs:225:5:
panic in a function that cannot unwind
stack backtrace:
   […]
thread caused non-unwinding panic. aborting.

The panic tries to leave an extern "C" function, which can't unwind the stack, and the process aborts. The full backtrace shows kv_for_each (kv.cpp:83): the panic happened inside a call from C++. Aborting is what Rust has done since version 1.81; before that, a panic leaving an extern "C" function was undefined behaviour. The opposite case hasn't changed: a C++ exception that crosses an extern "C" boundary into Rust is still undefined behaviour, according to the Nomicon.

The solution is in Kv::for_each: a trampoline, a generic extern "C" function that acts as a bridge between C++ and the closure:

lib.rs
    /// Iterates over the entries until `visit` returns false. If
    /// `visit` panics, the panic doesn't cross the C++ code: it's
    /// caught in the trampoline and resumed here, back in Rust.
    pub fn for_each<F: FnMut(&str, &str) -> bool>(&self, visit: F) {
        struct Ctx<F> {
            visit: F,
            panic: Option<Box<dyn Any + Send>>,
        }

        extern "C" fn trampoline<F: FnMut(&str, &str) -> bool>(
            key: *const c_char,
            value: *const c_char,
            ctx: *mut c_void,
        ) -> c_int {
            // SAFETY: ctx is the &mut Ctx<F> we pass to kv_for_each
            // below, and it stays alive for the whole call.
            let ctx = unsafe { &mut *ctx.cast::<Ctx<F>>() };
            // SAFETY: kv_for_each passes NUL-terminated strings that
            // live for the duration of the callback call.
            let (key, value) =
                unsafe { (CStr::from_ptr(key), CStr::from_ptr(value)) };
            let (Ok(key), Ok(value)) = (key.to_str(), value.to_str())
            else {
                return 0; // not UTF-8: skipped
            };
            // AssertUnwindSafe: if there's a panic, it's resumed
            // without using ctx.visit again.
            match panic::catch_unwind(AssertUnwindSafe(|| {
                (ctx.visit)(key, value)
            })) {
                Ok(true) => 0,
                Ok(false) => 1,
                Err(payload) => {
                    ctx.panic = Some(payload);
                    1 // tell C++ to stop iterating
                }
            }
        }

        let mut ctx = Ctx { visit, panic: None };
        // SAFETY: valid pointer; ctx lives until kv_for_each returns.
        unsafe {
            ffi::kv_for_each(
                self.ptr.as_ptr(),
                trampoline::<F>,
                (&raw mut ctx).cast::<c_void>(),
            )
        };
        if let Some(payload) = ctx.panic {
            panic::resume_unwind(payload);
        }
    }

The trampoline calls the closure inside panic::catch_unwind. If there's a panic, it stores the payload, returns 1 so C++ stops iterating and, back in Rust, resumes it with panic::resume_unwind. The panic goes around the C++ code instead of through it. Two more details:

  • &raw mut ctx creates a raw pointer without going through a reference; it's syntax that has been stable since Rust 1.82.
  • The AssertUnwindSafe is justified because, if there's a panic, it's resumed without using ctx.visit again.

The same panic, through the wrapper:

panic_safe.rs
// cargo run --example panic_safe
// The same panic, through the wrapper: it comes back to Rust as a
// normal panic, which can be caught, and the store keeps working.
use kvdemo::Kv;
use std::panic;

fn main() {
    let mut db = Kv::new().unwrap();
    db.set("lang", "rust").unwrap();

    let result = panic::catch_unwind(|| {
        db.for_each(|_, _| panic!("something went wrong in the callback"));
    });

    println!("panic caught back in Rust: {}", result.is_err());
    println!("get(lang) = {:?}", db.get("lang"));
}

This is the real output on my machine, with cargo run:

output
thread 'main' (81384) panicked at examples\panic_safe.rs:12:28:
something went wrong in the callback
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
panic caught back in Rust: true
get(lang) = Some("rust")

The panic comes back to Rust, gets caught like any other, and the store keeps working.

There's another option for when you do want unwinding to cross the boundary: the "C-unwind" ABI, stable since Rust 1.71. It isn't used in this post, because the boundary is designed so that nothing crosses it.

No operating system underneath: #![no_std]#

Everything above uses std, Rust's standard library. And std assumes there's an operating system underneath: a heap, threads, files. As I explain in my guide, a driver or a kernel is what that system needs, so it can't lean on std.

With #![no_std] only core is left, the part of the library that depends on nothing:

  • there's no heap by default: you need the alloc crate and your own #[global_allocator];
  • there's no panic handling: you have to define a #[panic_handler].

Rust for Linux builds on that base. Rust support landed in the kernel with Linux 6.1, released on 11 December 2022. If you want to see what's "underneath", the rings series starts at From Ring 3 to Ring 0.

What I take away#

  • unsafe is a promise, not a switch. It unlocks five operations; everything else is still checked.
  • Design the C boundary so nothing that unwinds crosses it: neither exceptions nor panics.
  • Turn the contracts in the documentation into types and lifetimes. Nobody checks a comment; the compiler checks a lifetime.
  • Every unsafe with its SAFETY, and all of them in a single file. That way they can be reviewed.
  • Check the memory layout on both sides, with compile-time assertions.
  • compile_fail tests turn "this shouldn't compile" into something that gets verified.
Personal note

I wrote a Rust systems guide whose section 2 covers exactly this: unsafe, FFI, the safe-wrapper pattern and no_std. The example in my guide used extern "C" {, which the 2024 edition no longer accepts without unsafe, so writing this post was a chance to bring it up to date. All the code in this post compiles without warnings, with clippy and -D warnings, and I've run it on my machine with Rust 1.98 and MSVC.

References

  1. The Rust Programming Language, 20.1: Unsafe RustRust Project · doc.rust-lang.org
  2. The Rustonomicon: Foreign Function InterfaceRust Project · doc.rust-lang.org
  3. Rust Edition Guide: Unsafe extern blocksRust Project · doc.rust-lang.org
  4. The Rust Reference: Type layoutRust Project · doc.rust-lang.org
  5. Announcing Rust 1.81.0Rust Blog · blog.rust-lang.org
  6. Announcing Rust 1.82.0Rust Blog · blog.rust-lang.org
  7. std::panic::catch_unwindRust Project · doc.rust-lang.org
  8. std::ffi::CStringRust Project · doc.rust-lang.org
  9. C++ draft: [string.require]eel.is · eel.is
  10. C++ draft: [unord.req.general]eel.is · eel.is
  11. An informal comparison of the three major implementations of std::stringThe Old New Thing (Microsoft) · devblogs.microsoft.com
  12. C++ draft: [res.on.data.races]eel.is · eel.is
  13. C++ draft: [except.handle]eel.is · eel.is
  14. AddressSanitizer (MSVC)Microsoft · learn.microsoft.com
  15. Linux 6.1kernelnewbies · kernelnewbies.org
  16. cc cratedocs.rs · docs.rs

Share

Keep reading

Rust

Rate limiting an API by plan in Rust: GCRA, Redis and tower-rate-tier

How to limit requests by each user's plan with tower-rate-tier: why GCRA and not a fixed window, requests that cost more, limits shared between instances with Redis, and safe defaults. With an example service and real outputs.

· 11 min

Rust

Why Rust remains the safest language in 2026

Analysis of Rust's memory safety features and why it dominates in critical systems.

· 5 min

Need Rust development?

Secure, high-performance software development with Rust for your business. Consulting, training, and custom projects.

Let's talk→

Comments

Commenting requires a GitHub account. Comments live in GitHub Discussions (SoftDryzz/blog-comments) and are moderated: no promotional links.