pw_rpc2#
Next gen, zero-copy async RPC with end-to-end backpressure
Unstable C++ Python
pw_rpc2 is the evolution of Pigweed’s Remote Procedure Call (RPC) framework
for embedded systems, redesigned from the ground up for asynchronous operations.
Built on cooperative async primitives and
transport abstractions, pw_rpc2 provides
end-to-end backpressure, cooperatively multiplexed RPC calls, a stateful
connection model, and zero-copy packet handling.
Note
pw_rpc2 is under active development. C++ support includes a server and
client, with support for making calls and defining services with either raw
or PWPB APIs, manual async state machines or coroutines. Python support
includes a synchronous and asyncio host client.
Other language runtimes are planned.
Highlights#
Stateful connections: A private
Socketbetween one client and one server replaces RPC1’s staticChannel, ensuring that RPCs know when a peer is listening or disconnects.End-to-end backpressure: Asynchronous buffer reservations from the transport layer pause tasks until space becomes available, naturally integrating backpressure into every RPC call.
Zero-copy payloads: Using pw_buf, all reads and writes operate directly on views of transport buffers, without intermediate staging or copying.
Cooperative concurrency: All RPC calls run in their own async2 Task, multiplexing operations on a shared dispatcher thread, and avoiding the global lock contention of RPC1.
C++ documentation#
C++ runtime mechanics. How to set up and use the C++ client and server, RPC call and error semantics, and protobuf codegen.
End-to-end C++ example suites. Examples covering common RPC patterns and use cases.
Testing services and clients.
Unit test pw_rpc2 services and clients in-process with
TestHarness.
Python documentation#
Synchronous and asyncio host client.
Connect to a pw_rpc2 server, build service clients at runtime from
protobuf descriptors, and call unary and streaming RPCs.
Classes, calls, and exceptions.
Generated reference for pw_rpc2 and pw_rpc2.aio.
Protocol and architecture#
Binary framing and control plane. Packet header layout, packet types, the opening handshake, and regular message exchange.
Evaluation and migration#
Architectural departures from RPC1. Why RPC2 was created: the history behind RPC, pain points with RPC1, and modernization and evolution.
Choosing the right RPC framework. Trade-offs between RPC1 and RPC2, with a guide on when to use which.
Incremental migration from RPC1.
Serve existing pw_rpc C++ services from a pw_rpc2 server without
modifying service implementations or .proto files.
Flash and RAM footprint. Bloaty size reports for the core server, client, combined endpoints, and generated raw/PWPB services and clients.