API++: convenience functions over the shared RAM.

Ribbit reference — rendered from the source tree, revision 2026-10-31. These sections are descriptive: the key words of §1.2 do not apply, and the code is the contract.

The base API (ribbit_space.hpp, frogram.hpp) writes a value, reads one, and holds a read on a family. API++ (cpp/include/ribbit_pp.hpp, cpp/src/ribbit_pp.cpp) is a small set of convenience functions built only from those. It adds nothing to the memory and nothing to any host. Every function does one of two things:

• writes into the caller's own space; or
• holds a read on someone else's.

No function is a call that anyone answers. Nothing crosses between machines except what the RAM itself carries.

The functions are generalized from what the Redis and MQTT conversions each built by hand.

1. Read this first: publish/subscribe here is not a broker

Publisher / subscribe are not implemented with traditional publish/subscribe techniques. There is:

• no broker;
• no subscription list;
• no fan-out server;
• no acknowledgement;
• no queue.

A publish is a write into the publisher's own cells. A subscription is a read held on a family. These functions are offered for convenience only, so a program that already thinks in topics has a place to start.

Users are encouraged to explore the proper architectures:

• each producer writes its truth where it lives, in its own space;
• each consumer holds reads on exactly the families it needs;
• the shape of the data, not a topic name, decides who reads what.

A design that has been through that exercise rarely needs topics at all.

2. The functions

Not in API++, because they are the base API:

• write / write_fields (put);
• read (get);
• watch (a held read).

3. Gone with its writer (platform) [GONE_WITH_ITS_WRITER_V1]

When a participant's session ends, everything it wrote disappears: the entire family it wrote is gone.

This is the platform's own behaviour (ram_memory.hpp, ram_host.cpp, rowcodec.hpp, frogram, ribbit::Space), not something API++ adds.

Who owns a row. A row belongs to the session that wrote it last. Only that session's own writes count:

• its cell writes;
• the platform's write operation.

A vendor operation's writes are the region's, and stay.

How readers learn of it. When the session ends, the host removes each of its rows before the vendor's session_down.

• Each removal takes its place in the family's write order, exactly as a write does: an id, the variable's and the service's windows, the readers' words, the row's triggers.
• Every read held on that family is handed the row with gone set, in order.
• On the wire, a gone row is its own record (row codec head GONE): its id and coordinates, with no bag.
• A read of what is there now never returns a gone row.

What API++ does with it:

• subscribe skips gone rows (they are not publishes).
• capable reports a capability that went away (Capable::gone).
• The answerer is handed each request of an asker that is gone, with SpaceRow::gone set.

That last point is how a region learns a front has died, with nothing but writes and held reads.

4. Linger, by family: the writer's choice [LINGER_BY_FAMILY_V1]

What happens to a family's rows when the writer's session ends is the writer's choice. It is an application decision, not the platform's. The writer makes it per family, before the family's first write:

How it travels. The choice rides on the frame that names the family on the wire: F_LINGER on a cell write's F_NAMES, once per writer thread per family. Nothing is added per write.

How the reaper works. At session end the host:

1. removes the rows that go at once;
2. hands each linger the remaining rows chose to its reaper: one thread, a lock-free incoming list, and a condition variable whose mutex guards only its own sleep.

When an entry's time comes, the reaper removes only the rows that session still owns. A row written since by someone else is theirs, and is not reaped.

Typical choices:

• A front's requests to a region go at once: the region learns the front is gone.
• A publish from a client that publishes and exits stays a few seconds, so a slow subscriber still gets it.
• A retained message stays.

5. Held reads: watch and follow [STANDING_WATCH_V1]

Every API++ read except latest and capable's first look is a ribbit::Space held read, each on a thread of its own, handed batches in the family's write order.

subscribe, capable and the Answerer use watch. The Asker uses follow.

[SERVICE_PAST_AN_ID_V1] A memory cursor on a whole service, started past an id, used to read a variable's rows only when that variable was next written. It now reads every variable's rows past the id on its first read. test-family-hooks: 3 of 3 rows with the fix, 0 of 3 without.

6. Redis and MQTT on API++

MQTT (box front/src/region_client.cpp, client library libram/libmosquitto_ram.cpp):

• Publishes go through Publisher / subscribe. Gone: the box's own per-topic counter and both hand-written gap checks.
• The topic directory uses announce. Wildcard filters use capable. Gone: the box's and libram's own directory watches.
• Retained messages were one tuple per topic, (mqtt.retained, <topic>, hwm), written by every publisher. Each writer now has its own cell (offer), and the reader takes the newest (latest).
• Linger:
• box: its retained messages stay when it goes; everything else goes with it;
• libram: publishes and directory entries stay 5 s (for a client that publishes and exits); retained messages stay.

Redis (src/front.cpp, src/redis_ram.cpp, src/region.cpp):

• The front is an Asker. Its requests are (redis.ask, <front>, …), and it reads its replies with one standing follow.
• The region is an Answerer on Space("here"). Gone: the host's hand-written reader loop.
• The front's one call is gone (op=redis "h <front>", and with it the region's bind and session_down). When a front's session ends, its request cells go with it. The region is handed each one as gone, and that connection leaves (request_gone).
• run_two_fronts.py check 9 ("B stops: its clients leave the region") is green, and red with request_gone disabled.

Measured (lizard, NLOC / total CCN), main against this branch:

The platform grows by the shared lock-free primitives (moved in from Redis), API++, gone-with-its-writer, linger and its reaper, and Space::follow. Redis and MQTT shrink.

7. The in-process primitives are not API++

cpp/include/lf/primitives.hpp ([LF_PRIMITIVES_V1], formerly lf/apipp.hpp) is thread plumbing inside one process, for a vendor's own region memory. Redis and MQTT both use it, and it is never on the wire. It holds:

• WaitWord;
• QuietSpan;
• TakeStack;
• cas / swap / take / update on one value behind an atomic pointer.

An earlier API++ put cas, swap, add, take, take_first and batch into the platform memory, decided at the tuple and answered per call. That was removed (4ab86a2). It was request/response against the memory, which the design does not do.

8. Tests

test-ribbit-pp:

Both tests run in cpp/qualify.sh (stages build, lockfree).