Skip to content

Extending

Oguzhan KAYNAK edited this page Nov 15, 2026 · 2 revisions

Extending

Every layer has one extension point. Extending one layer does not touch the others.

Layer To add Implement Then
pushseg a transport or device API a StreamBackend (byte stream: connect, send, receive) or a MappedBackend (mapped memory: alloc, export, import, barrier, interrupt) register it under a name and select it in the configuration
pairring a different layer below (RDMA, a middleware, a device window) RemoteRegion: write, optional writev, store64, notify, size construct the channel with it
wireforge a different transport for messages a transport with non-blocking send and receive instantiate the generated link with it
wireforge new or changed messages edit model/project.yaml scripts/regenerate.sh
gridlane a new data primitive or phase code on top of put / signal / wait —

A new transport for pushseg

The core of pushseg enforces the memory contract. A backend only moves bytes:

  • Stream level: the core runs the whole segment protocol (framing, writes, atomic stores, notifications) over your byte stream. TCP is implemented this way.
  • Mapped level: your API exposes the remote memory; the core turns write into a copy or DMA and store into barrier + store + barrier. POSIX shared memory is implemented this way.
class MyBusBackend final : public pushseg::backend::MappedBackend { /* ... */ };
pushseg::backend::register_mapped_backend("mybus", [] { return std::make_unique<MyBusBackend>(); });
[links]
0-1 = mybus

pushseg's contract tests (tearing, ordering, flush, disconnects) can be run against the new backend by adding its name to the test list. Details: pushseg: plugging in your own API.

Everything above pushseg — pairring, the control plane, the data plane, the demonstrator — then runs over the new transport without a change.

pairring without pushseg

pairring needs only remote-writable memory with an atomic, ordered 8-byte store and a doorbell. When the peer's memory is mapped into the process, MappedRemoteRegion is ready; only the doorbell is supplied. Details: pairring: plugging in the layer below.

Another serializer

pairring carries byte strings. The wireforge adapter in gridlane is a few lines (include/gridlane/glue/pairring_transport.hpp); an adapter for another serializer has the same shape: send a buffer, receive a buffer.

Note on unframed message transports

pairring delivers whole messages, so the wireforge interface uses framing: none: one receive is one message, and the generated Link is used as it is. This needs wireforge 0.5.1 or later, where an unframed link keeps a message of exactly the largest size on a message transport (wireforge#45).

Clone this wiki locally