future_form_ffi 0.1.0

FFI support for future_form: host-driven polling, opaque handles, and effect slots
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

# Effects Counter

An FFI example demonstrating `future_form`'s sans-IO effect protocol.
A counter service requests capabilities from the host (timestamps,
logging) rather than performing I/O directly. Foreign hosts (Go, Java,
Python) inspect pending effects, fulfill them, and re-poll.

## What this demonstrates

- The sans-IO effect protocol (`EffectSlot` + `EffectHandle`)
- Host-fulfilled effects: `GetTimestamp` and `Log`
- Per-struct `EffectSlot` (one future at a time)
- The same async state machine driven by Go, Java, and Python hosts

## Structure

```
counter_effects/
├── counter_effects/  Domain logic: EffectCounter with GetTimestamp + Log effects
├── effects_bridge/   C ABI + JNI bridge (effects counter)
├── go_host/          Go host with effect fulfillment
├── java_host/        Java host with effect fulfillment
├── python_host/      Python host with effect fulfillment
└── run_test.sh       Build + run across all hosts
```

## Running

From the workspace root, using `nix develop .#ffi` for foreign toolchains:

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

## Prerequisites

See [counter_simple](../counter_simple/) for the basic polling pattern
without effects. For concurrent per-future effect slots, see the
[key_value_store](../key_value_store/) example.

## Limitations

This example uses a **per-struct `EffectSlot`** -- only one future can
be in flight at a time per counter instance. For concurrent futures, see
the [key_value_store](../key_value_store/) example which uses per-future
`Arc<EffectSlot>`.