Zero-Cost Async FFI

In this lesson, you will learn how to bridge foreign functions to the Rust Future trait without introducing heap allocations or intermediate task spawning.

The Cost of FFI Boundaries

When calling into a foreign C or C++ library, we often face a mismatch: the foreign library performs a long-running, blocking task, but we want our Rust executor to remain responsive. A naive approach is to use tokio::spawn_blocking, which requires an allocation and thread hand-off. "Zero-Cost Async FFI" avoids this by mapping the foreign state machine directly into a Rust Future.

Implementing the Custom Polling Wrapper

To achieve zero-cost, we create a wrapper struct that holds the state of the foreign request and implements Future. The poll method acts as the "bridge," checking the status of the foreign library’s operation without requiring extra threads.

struct FfiFuture {
    request_id: u32, // ID returned by the C library
}

impl Future for FfiFuture {
    type Output = i32;

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        // Direct call to C function; no spawning involved
        let status = unsafe { foreign_check_status(self.request_id) };

        if status == STATUS_PENDING {
            // Register the current task's waker with the foreign library
            unsafe { register_waker(self.request_id, cx.waker().clone()) };
            Poll::Pending
        } else {
            Poll::Ready(status)
        }
    }
}

Why this is Zero-Cost

1. No Allocation: The FfiFuture is typically allocated on the stack of the task that calls it, avoiding the overhead of Box or task-local buffers.
2. Direct Polling: We aren't introducing intermediate channels or queues. We call the foreign API synchronously during the poll execution.
3. Waker Hand-off: By passing a Waker reference into the foreign layer, we allow the foreign C code to trigger the Rust executor precisely when the work is finished. This creates a tight, zero-latency feedback loop between the hardware/foreign domain and the Rust runtime.

This pattern is highly efficient, though it requires strict memory safety management on the C side to ensure the Waker is only called when the result is truly ready.

Key Takeaway: By mapping foreign state machines directly into Future::poll, you eliminate task spawning and allocation, allowing Rust to orchestrate high-performance FFI operations with minimal runtime overhead.