Add minimal example: hello-single-latest

[lxsaah]

Difficulty: easy · Estimate: 2–3 hours

The README explains three buffer primitives (SPMC Ring, SingleLatest, Mailbox) but the quick-start only demonstrates SPMC Ring. Newcomers learn fastest from minimal examples per concept. Add a runnable examples/hello-single-latest that's the simplest possible "current value matters" demo.

Where to look

• README.md:62-92 — existing minimal SPMC quick-start
• examples/sync-api-demo/ — minimal example structure to mimic
• aimdb-core/src/buffer/cfg.rs — BufferCfg::SingleLatest definition

What to do

• Create examples/hello-single-latest/ with Cargo.toml, src/main.rs, README.md.
• ~30–50 lines of Rust: a single f32 "feature flag" record published every second, a tap that prints whenever the value changes.
• Add to root Cargo.toml workspace members.

Done when

• cargo run -p hello-single-latest works and prints values
• The example's README explains what SingleLatest semantics buy you in one paragraph
• Linked from main README's buffer table

We'd love help with this — comment if you'd like to take it.

[harunugurlu]

Hey, I would like to work on this issue. Could you assign it to me if it is still available?

[harunugurlu]

I have opened PR-182 . As I am a beginner in both Rust (reading the Rust Book actively), and in open source contribution, I would really appreciate any kind of feedback on implementation, style, or contribution process.

I have done my best trying to understand AimDB, the sync-api-example, the hello-single-latest-async example, and tried to follow the instructions in the issue description.

I have one point I am unsure though: As instructed in the issue description, I have created a tap and a sync producer that publishes a new value every second. This demonstrates using aSingleLatest buffer through the sync API, but it does not visibly demonstrate intermediate updates being overwritten and the consumer only seeing the latest value. If I am misinterpreting the purpose of this example or the behaviour of SingleLatest buffer, please correct me. If needed, I can try making this more visible in the example.

Thanks in advance!

[lxsaah]

Hi @harunugurlu , nice work!

The example builds, runs and matches its documented output. To answer your question in the issue, your instinct is exactly right. The current example uses a SingleLatest buffer, but because it sleeps a full second between every write, the tap reads each value before the next one arrives. That means the output would look identical if the buffer were an SPMC Ring or a Mailbox. The one property that makes SingleLatest special, collapsing intermediate updates, is never exercised. The good news is, making it visible is a small change. But before lets dive into the buffers:

Buffer	Keeps	Delivery to multiple readers	Good for
SpmcRing { capacity }	The last N values	Broadcast, non-destructive — every reader independently gets every value; on overflow the oldest are dropped	Telemetry, event logs, sensor streams (>10 Hz)
SingleLatest	Only the newest value	Broadcast, non-destructive — every reader sees the latest value; a read never removes it and intermediate updates are collapsed	Feature flags, config, UI state ("current value matters")
Mailbox	The newest unconsumed value (single shared slot)	Destructive hand-off — a read takes the value out of the slot, so with N readers each value goes to exactly one of them (they compete); a new write overwrites an unconsumed value	Work queue / job dispatch, commands where each item is handled once

The differece between SingleLatest and Mailbox is subtle. Both keep a single value, so the difference isn't how much they keep but what a read does. SingleLatest broadcasts the current state (every tap sees it, non-destructively), while Mailbox hands each value to exactly one consumer and it's then gone.

For this example, SingleLatest is the right choice. You want "what's the rollout right now," delivered to every observer, not a job that one worker consumes.

Keep your existing once-per-second producer, but add a second tap that reads more slowly than the producer writes, e.g. it sleeps a couple of seconds between reads, as if it were busy doing work. Give each tap a label in its output (say [fast] and [slow]) so you can tell them apart, then run it and compare the two streams.

What you'll see: the fast tap prints every value (0, 25, 50, 75, 100), while the slow tap prints only a subset, each time it looks it gets the current value and the ones written while it was busy have already been overwritten in the single slot.

While you do this, reach for the runtime context (ctx) instead of Tokio directly. It's the handle that keeps the example runtime-independent, which is AimDB's whole pitch ("one async API across Tokio, Embassy and WASM"). Use it:

• Sleep via ctx.time(). For the slow reader's delay, call ctx.time().sleep_millis(2000).await (or .sleep_secs(2)) rather than tokio::time::sleep. It routes through the runtime adapter, so the same code sleeps correctly on Embassy or WASM. (Don't use std::thread::sleep inside a tap — that would block the async runtime.)
• Log via ctx.log(). Instead of println! inside the tap, use ctx.log().info(&format!("[slow] rollout: {}%", pct)) — same portability benefit. (info takes a &str, hence the &format!(...).)

You can see this exact ctx.time() / ctx.log() pattern already in the sibling hello-single-latest-async example, so it's a good one to copy from.

Two small notes: in the sync main driver it's fine to keep std::thread::sleep and println!. That's a plain OS thread you own, not the async runtime.

[harunugurlu]

Thanks for the detailed explanation @lxsaah

I have updated the examples, created a "fast" and a "slow" tap observer and used ctx.time(), and ctx.log() inside them. Now, some of the values are being overwritten before the slow one can read them which demonstrates the SingleLatest buffer behaviour more clearly. Also I increased the grace period at the end before detaching to 1000 ms to give enough time to the slow tap to wake up so it is able to observe the latest published value.