Repository navigation
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 | — |
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
writeinto a copy or DMA andstoreinto 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 = mybuspushseg'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 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.
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.
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).
gridlane
Repositories