# FFI Examples

End-to-end examples of `future_form_ffi` driving Rust async state machines from foreign hosts (Go, Java, Python).

| Example | Level | Demonstrates |
|---------|-------|--------------|
| [`counter_simple`](counter_simple/) | Introductory | Basic host-driven polling via `HostHandle` + `PollOnce` |
| [`counter_effects`](counter_effects/) | Introductory | Sans-IO effect protocol with `EffectSlot` + `EffectHandle` |
| [`key_value_store`](key_value_store/) | Intermediate | Per-future `Arc<EffectSlot>`, concurrent operations, multi-step futures |

## Progression

Start with `counter_simple` to understand the basic polling loop, then
`counter_effects` to see how futures request capabilities from the host,
then `key_value_store` for concurrent operations with independent effect
channels.

```
counter_simple       counter_effects       key_value_store
──────────────>  ───────────────────>  ─────────────────────>
  poll_once()      EffectSlot             Arc<EffectSlot>
  HostHandle       EffectHandle           per-future slots
  blind poll       effect dispatch        concurrent futures
```

## Running

Each example has a `run_test.sh` that builds the Rust cdylib and runs
all host implementations. Foreign toolchains (Go, Java, Python) are
available via `nix develop .#ffi`:

```sh
nix develop .#ffi

./future_form_ffi/examples/counter_simple/run_test.sh
./future_form_ffi/examples/counter_effects/run_test.sh
./future_form_ffi/examples/key_value_store/run_test.sh
```

The `counter_simple` tokio host needs only Rust:

```sh
cargo run --manifest-path future_form_ffi/examples/counter_simple/tokio_host/Cargo.toml
```