Rust FFI Exercises — Study Plan

Work through the exercises in order. Each builds on concepts from the previous ones.

Run a single exercise: cargo test ex01 Run all exercises: cargo test

Exercises

Exercise 01 — Call C from Rust (src/ex01_calling_c.rs) Declare C functions in an extern "C" block and write safe Rust wrappers. Concepts: extern "C", type mapping (int→i32, double→f64), unsafe blocks.
Exercise 02 — Call Rust from C (src/ex02_rust_from_c.rs) Write #[no_mangle] pub extern "C" functions that C code can call. Concepts: #[no_mangle], C calling convention, symbol export.
Exercise 03 — #[repr(C)] Structs (src/ex03_structs.rs) Define C-compatible structs and pass them by value and by pointer. Concepts: #[repr(C)], pass-by-value vs pass-by-pointer, *const T / *mut T.

Strings & Data

Exercise 04 — C-String Passing (src/ex04_strings.rs) Convert between Rust &str/String and C *const c_char/*mut c_char. Concepts: CStr (borrow), CString (own), into_raw() / from_raw(), caller-provided buffers. See also: docs/ex04_strings_ffi.md for a comprehensive guide on string conversions, common mistakes, and buffer patterns.
Exercise 05 — Opaque Handles (src/ex05_opaque.rs) Hide a Rust HashMap behind an opaque *mut Config pointer. Concepts: Box::into_raw / Box::from_raw, create→use→destroy lifecycle, non-repr(C) types.
Exercise 06 — Arrays & Slices (src/ex06_arrays.rs) Pass arrays as (pointer, length) pairs across the FFI boundary. Concepts: slice::from_raw_parts, Vec ↔ (ptr, len) via mem::forget, from_raw_parts.
Exercise 07 — Callbacks (src/ex07_callbacks.rs) Function-pointer callbacks in both directions (Rust→C and C→Rust), including the void* user_data context pattern. Concepts: extern "C" fn pointers, context/"closure" via *mut c_void, Rust fn as C callback.
Exercise 08 — Memory Management (src/ex08_memory.rs) Allocate buffers in Rust, hand them to C, free them correctly. Builder pattern with an opaque handle. Concepts: "whoever allocates must free", mem::forget, Vec::from_raw_parts, out-parameters.
Exercise 09 — Error Handling (src/ex09_errors.rs) Integer return codes + thread_local! last-error message (like errno / GetLastError()). Concepts: thread_local!, RefCell<Option<CString>>, error code conventions.

Advanced

Reference Documents

In-depth guides and tutorials in the docs/ directory:

Document	Related Exercise	Topic
ex04_strings_ffi.md	Exercise 04	Rust ↔ C string conversions, `CStr`/`CString` patterns, common mistakes (dangling pointers, leaks, missing NUL), buffer allocation
ex14_panic_unwinding.md	Exercise 14	Panic unwinding, `Drop` guarantees, unwind vs abort, FFI boundary hazard
ex15_miri_tutorial.md	Exercise 15	Programmer's guide to Miri — reading errors, all 8 UB categories with examples and fixes, Stacked Borrows, Tree Borrows
ex16_pin_drop_guarantee.md	Exercise 16	Pin and the drop guarantee — why `Pin<Box<T>>` + `!Unpin` + `Drop` work together, usage patterns (callbacks, intrusive lists, async I/O)
ex25_cpp_vtable_abi.md	Exercise 25	Itanium C++ ABI vtable layout — vptr, slot numbering, multiple inheritance, pointer adjustment, deleting destructors
ex26_cpp_exceptions.md	Exercise 26	C++ exception model — try/catch wrappers, thread-local error storage, `catch(...)`, non-`std::exception` throws
ex27_cpp_stl_wrapping.md	Exercise 27	Wrapping C++ classes and STL types — opaque pointers, `std::string` interop, borrowed returns, callback iteration
ex29_unsafecell_aliasing.md	Exercise 29	`UnsafeCell` and LLVM aliasing — `noalias readonly`, LLVM IR examples, when to use `UnsafeCell` in FFI, Stacked Borrows

Commands

cargo test           # run all exercises
cargo test ex01      # run exercise 01 only
cargo test ex05      # run exercise 05 only
cargo build          # compile (also builds C/C++ via build.rs)

Estimated Time to Complete

For an experienced Rust developer with no prior FFI experience. Times include reading the exercise, implementing the solution, and passing all tests.

#	Exercise	Est. Time	Difficulty
01	Call C from Rust	20 min	★☆☆☆☆
02	Call Rust from C	20 min	★☆☆☆☆
03	`#[repr(C)]` Structs	25 min	★☆☆☆☆
04	C-String Passing	30 min	★★☆☆☆
05	Opaque Handles (Rust-owned)	30 min	★★☆☆☆
06	Arrays & Slices	30 min	★★☆☆☆
07	Callbacks	40 min	★★☆☆☆
08	Memory Management	45 min	★★★☆☆
09	Error Handling	40 min	★★☆☆☆
10	`MaybeUninit`, `NonNull` & `ManuallyDrop`	55 min	★★★☆☆
11	C++ Vtable Pattern	60 min	★★★★☆
12	Async / Threaded Interop	60 min	★★★★☆
13	Tagged Unions	40 min	★★★☆☆
14	Panic Safety	30 min	★★☆☆☆
15	Fixing UB with Miri	60 min	★★★★☆
16	Pin & Drop Guarantee	60 min	★★★★☆
17	Wrapping C Opaque Handles	50 min	★★★☆☆
18	Closures via Trampolines	50 min	★★★☆☆
19	Boxed `dyn Trait` Across FFI	65 min	★★★★☆
20	Global State & Init/Shutdown	35 min	★★☆☆☆
21	Bitflags & C-Style Enums	35 min	★★☆☆☆
22	Lifetimes with `PhantomData`	45 min	★★★☆☆
23	`transmute` & Reinterpretation	45 min	★★★☆☆
24	C-Owned Opaque Handles	45 min	★★★☆☆
25	C++ Virtual Functions (Direct Vtable)	75 min	★★★★★
26	C++ Exceptions Across FFI	50 min	★★★☆☆
27	Wrapping C++ Classes & STL Types	60 min	★★★★☆
28	Zero-Sized Types in FFI	40 min	★★★☆☆
29	`UnsafeCell` & Aliasing in FFI	45 min	★★★★☆
	Total	~20.5 hours

Tip: Exercises 01–07 build linearly — do them in order. After that, exercises are mostly independent and can be tackled in any order based on interest. Exercise 25 requires understanding ex11 (vtable pattern) first. Exercises 26 and 27 stand alone but pair well with ex25 for a complete C++ interop trilogy.

Hints

Stuck? These hints cover the most common stumbling blocks across all exercises. Each hint gives just enough to unblock you without spoiling the solution.

General FFI

unsafe is a contract, not a warning. When you write unsafe { }, you are promising that the preconditions documented on the function hold. Read the # Safety doc comment before every unsafe call.
Ownership always matters. Before touching a raw pointer ask: "who owns this memory?" If Rust allocated it (Box::into_raw, CString::into_raw, Vec::as_mut_ptr + mem::forget), Rust must free it. If C allocated it, C must free it.
repr(C) ≠ repr(Rust). If a struct crosses the FFI boundary, it needs #[repr(C)]. Opaque handles that C never dereferences do NOT need repr(C) — only a pointer crosses.

Strings (ex04)

CStr::from_ptr(ptr) borrows — the pointer must outlive the reference.
CString::new(s).unwrap() allocates — use .as_ptr() while the CString is alive.
CString::into_raw() transfers ownership to C; reclaim with CString::from_raw().
Watch out for interior NUL bytes — CString::new returns Err if the input contains \0.

Opaque Handles (ex05, ex17)

The pattern is always: Box::new(value) → Box::into_raw() → C holds the pointer → Box::from_raw() to reclaim.
The type behind the pointer does NOT need #[repr(C)] as long as C only stores the pointer and never dereferences the fields.
To wrap a C library's handle, use NonNull<OpaqueType> + Drop.

Callbacks & Closures (ex07, ex18)

C function pointers are extern "C" fn(...) — they cannot capture environment.
To pass state, use the void *user_data pattern: cast your state to *mut c_void, pass it alongside the fn pointer, cast it back inside the callback.
For Rust closures, write a trampoline: a generic extern "C" fn<F: Fn…> that casts the void* back to &F / &mut F / Box<F> depending on the trait.
Fn → pass &closure as context (shared borrow, not consumed).
FnMut → pass &mut closure as context (exclusive borrow, not consumed).
FnOnce → pass Box::into_raw(Box::new(closure)) as context (consumed via Box::from_raw).

dyn Trait (ex19)

Box<dyn Trait> is a fat pointer (2 words). C can't store that.
Wrap it: struct Handle { inner: Box<dyn Trait> }. Now Box::into_raw(Box::new(handle)) is a single-word (thin) pointer.
Drop on the wrapper frees both the wrapper and the trait object.
Registry pattern: store Vec<Box<dyn Logger>> inside a struct behind an opaque handle. add() pushes, broadcast() iterates and calls .log() on each. C sees one thin pointer hiding an arbitrarily large collection.
Downcasting: add fn as_any(&self) -> &dyn Any to your trait. Each impl returns self. Then handle.inner.as_any().downcast_ref::<ConcreteType>() recovers the concrete type. Returns None if the type doesn't match.
Any requires 'static — your concrete types must not hold non-'static borrows.

Memory (ex08)

mem::forget(vec) prevents Drop — you now own the raw pointer.
Reconstruct with Vec::from_raw_parts(ptr, len, cap) to free.
Never mix allocators: don't free() Rust memory or Box::from_raw C memory.

ManuallyDrop (ex10 Part D)

ManuallyDrop::new(v) wraps a value and suppresses its destructor — the value stays valid but won't be freed when it goes out of scope.
Use this when transferring a Vec to C: wrap in ManuallyDrop, extract (ptr, len, capacity), hand the triple to C.
To reclaim: Vec::from_raw_parts(ptr, len, cap) — the resulting Vec drops normally.
ManuallyDrop vs mem::forget: both suppress drop, but ManuallyDrop lets you read fields (.as_ptr(), .len()) after suppressing drop. mem::forget consumes the value so you can't access it afterwards.

Error Handling (ex09)

Return 0 for success, negative for error. Store the full message in a thread_local!.
thread_local! + RefCell<Option<CString>> is the Rust equivalent of errno + strerror.

Panic Safety (ex14)

Unwinding across extern "C" is undefined behavior. Always wrap with std::panic::catch_unwind.
catch_unwind requires UnwindSafe. Use AssertUnwindSafe(|| { ... }) if the compiler complains.
Pattern: catch_unwind(|| { /* real work */ }).unwrap_or_else(|_| ERROR_CODE).

Global State (ex20)

static GLOBAL: OnceLock<Mutex<T>> = OnceLock::new(); — initialized exactly once, thread-safe.
OnceLock::get_or_init(|| ...) is idempotent and lock-free after first init.
Always check that the library was initialized before accessing state.

Bitflags (ex21)

Use #[repr(transparent)] on a newtype: struct Flags(u32). ABI identical to u32.
contains(other): (self.0 & other.0) == other.0.
Implement BitOr, BitAnd, BitOrAssign — they're one-liners.

Lifetimes & PhantomData (ex22)

PhantomData<&'a T> tells the compiler "I logically borrow a &'a T" without storing one.
Use it when a raw pointer should have a lifetime but can't (because raw pointers are 'static).
The compiler will then prevent use-after-free at compile time.
&self borrow in cursor() → multiple cursors OK, no mutation. &mut self borrow in transaction() → exclusive access.

Transmute (ex23)

Only use transmute when there is no safe alternative. The most common legitimate case: *mut c_void ↔ function pointer — as casts don't work here.
Option<extern "C" fn(...)> is guaranteed to have the same layout as a nullable pointer. You do NOT need transmute for optional callbacks — just declare them as Option<…> in your extern "C" block.
Integer → #[repr(C)] enum: prefer match + TryFrom. If you transmute an integer that doesn't match any variant, it's instant UB — even if you never read the value.
Bytes → struct: prefer ptr::read_unaligned + size check over transmute. transmute requires exact size and alignment; read_unaligned is more forgiving.
Bytes → struct with bool/enum fields: even ptr::read_unaligned can be UB if the bit pattern is invalid for those types. Validate first or deserialize field by field.
Safe alternatives cheat sheet:
- *mut T ↔ *mut c_void → use as
- f32 ↔ u32 bits → f32::from_bits / to_bits
- Integer ↔ integer → as or From/TryFrom
- Struct → bytes → slice::from_raw_parts(ptr as *const u8, size_of::<T>())

C-Owned Opaque Handles (ex24)

The C library calls calloc / malloc — Rust must NOT call Box::from_raw. Call C's own destroy function in your Drop.
The out-parameter pattern: let mut ptr: *mut CSession = std::ptr::null_mut(); then pass &mut ptr (which is *mut *mut CSession) to the C function.
Wrap the raw pointer in NonNull<CSession> immediately after creation. NonNull::new(ptr).ok_or(Error)? handles the null case.
For get_option-style functions that fill a caller-provided buffer, use a stack array: let mut buf = [0u8; 256];. After the C call, find the NUL terminator with CStr::from_ptr(buf.as_ptr() as *const c_char).
&self vs &mut self: functions that only read (is_connected, get_option) take &self; functions that mutate state (connect, send) take &mut self.

Vtable / C++ (ex11)

A vtable is just a #[repr(C)] struct of extern "C" fn pointers.
Use static vtables (not heap-allocated) — one per concrete type.
The destroy function pointer in the vtable must reconstruct the Box to free.

Direct C++ Vtable Access (ex25)

Itanium ABI only: This works on GCC/Clang (Linux, macOS, BSD). It does NOT work on MSVC.
The vptr is the first field of every polymorphic C++ object. Read it: let vptr = *(obj as *const *const VtableStruct).
Virtual destructors occupy two slots in the Itanium ABI: slot 0 = complete destructor (D1, no dealloc), slot 1 = deleting destructor (D0, with dealloc). Your methods start at slot 2.
To destroy: call the deleting destructor (slot 1) through the primary base's vtable. The primary base pointer equals the allocation address.
Multiple inheritance: A class inheriting from N bases has N vptrs in its object layout. Casting to a non-primary base adjusts the pointer. Always use the correct interface pointer for each vtable.
Verify slot numbering: Use clang++ -Xclang -fdump-vtable-layouts -c file.cpp 2>&1 | c++filt to dump the vtable. Or write a C++ helper that reads vptr[slot] and compare against your #[repr(C)] struct in tests.
In/out arguments work the same through direct vtable calls — just pass &mut value as *mut f64. The virtual method writes through the pointer.
offset_to_top at vptr[-2] tells you the byte offset from the sub-object back to the complete object — useful for MI diagnostics.
See docs/ex25_cpp_vtable_abi.md for the full ABI reference with ASCII diagrams.

C++ Exceptions Across FFI (ex26)

Rule #1: An exception that escapes an extern "C" function is undefined behavior. Every extern "C" wrapper MUST have try { ... } catch (...) { ... }.
Always end your catch chain with catch (...) — C++ can throw non-std::exception types (e.g. throw 42;).
Use a thread-local ExceptionInfo struct to store the exception's message, type name, and error code. The Rust side retrieves it after checking the return code. This mirrors the errno / GetLastError() pattern.
Order catch blocks from most-specific to least-specific: ProcessingError → std::invalid_argument → std::exception → ....
For callbacks (C++ → Rust → C++): the Rust callback should never panic. Return an error code instead. Use catch_unwind() as a safety net if needed.
On the Rust side, build a CppException error type and a check(rc) → Result<(), CppException> helper. Then every wrapper is just: check(unsafe { cpp_ex_foo(...) })?; Ok(result).
See docs/ex26_cpp_exceptions.md for the full exception model guide.

Wrapping C++ Classes & STL Types (ex27)

Opaque pointer pattern: The C++ class lives on the heap. Rust holds *mut CppStringStack (a zero-size opaque type) inside a RAII wrapper with Drop.
std::string input: Pass (&str).as_ptr() + len — no NUL terminator needed. The C++ side constructs std::string(ptr, len).
std::string output (owned): Use a two-phase protocol: first call with buf = null to get the needed length, then allocate and call again.
std::string output (borrowed): peek() returns a pointer directly into C++ memory. Wrap it in a PeekGuard<'a> that borrows &'a StringStack to prevent mutation while the pointer is live.
Clone = C++ copy constructor: cpp_stk_clone() calls new CppStringStack(*s). Implement Rust's Clone trait.
Callback iteration: for_each() passes each element to a callback. Use a trampoline that appends to a Vec<String> through a *mut c_void context pointer.
Factory functions: C++ static methods like from_csv() become extern "C" functions that return new opaque pointers.
See docs/ex27_cpp_stl_wrapping.md for the full wrapping patterns guide.

Pin & Drop (ex16)

Use Pin<Box<T>> when C stores a raw pointer back to your struct.
PhantomPinned makes the type !Unpin so it can't be moved out of the Pin.
Drop must deregister from C before the memory is freed.

Miri (ex15)

Run with cargo +nightly miri test ex15.
Miri catches: dangling pointers, aliasing violations (& and &mut to same address), unaligned reads, use-after-free.
ptr::read_unaligned for unaligned access; split_at_mut to get two &mut to non-overlapping parts.

Debugging Tips

Segfault? You probably used a pointer after free, or cast to the wrong type. Run under Miri or Valgrind.
Garbled strings? Check that your CString is still alive when C reads the pointer. A common bug: CString::new(s).unwrap().as_ptr() — the CString is a temporary and is freed immediately!
Link errors? Make sure build.rs compiles your C file and the function name matches exactly (no name mangling — use extern "C").
Use cargo test -- --nocapture to see println! output from tests.
Use #[repr(C)] and check sizes: assert_eq!(std::mem::size_of::<MyStruct>(), EXPECTED_SIZE); catches layout mismatches early.

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
csrc		csrc
docs		docs
include		include
src		src
tests		tests
.gitignore		.gitignore
Cargo.toml		Cargo.toml
README.md		README.md
build.rs		build.rs
native.code-workspace		native.code-workspace

Folders and files

Latest commit

History

Repository files navigation

Rust FFI Exercises — Study Plan

Exercises

Strings & Data

Advanced

Reference Documents

Commands

Estimated Time to Complete

Hints

General FFI

Strings (ex04)

Opaque Handles (ex05, ex17)

Callbacks & Closures (ex07, ex18)

dyn Trait (ex19)

Memory (ex08)

ManuallyDrop (ex10 Part D)

Error Handling (ex09)

Panic Safety (ex14)

Global State (ex20)

Bitflags (ex21)

Lifetimes & PhantomData (ex22)

Transmute (ex23)

C-Owned Opaque Handles (ex24)

Vtable / C++ (ex11)

Direct C++ Vtable Access (ex25)

C++ Exceptions Across FFI (ex26)

Wrapping C++ Classes & STL Types (ex27)

Pin & Drop (ex16)

Miri (ex15)

Debugging Tips

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages