Skip to main content
Pigweed's logo Pigweed
code_xml
  1. Home
  2. Reference
  3. C/C++
  4. Comms
  5. pw_rpc
pw_rpc

Overview

Efficient, low-code-size RPC system for embedded devices.

Submodules

 Benchmarking & testing
 
 Channels
 
 Configuration
 User-provided header to optionally override options in this file.
 
 Synchronous API
 
 pw_protobuf RPC
 Call objects for pw_protobuf-backed RPC clients and servers.
 

Classes

class  pw::rpc::Client
 
class  pw::rpc::ClientServer
 
class  pw::rpc::DynamicCallPtr< CallType, UniquePtr >
 
class  pw::rpc::PacketMeta
 
class  pw::rpc::PayloadsView
 
class  pw::rpc::StatusView
 
class  pw::rpc::Rpc2ServiceFor< LegacyService >
 
struct  pw::rpc::Rpc2AdapterConfig
 Configuration for Rpc2Adapter and Rpc2ServerAdapter. More...
 
class  pw::rpc::Rpc2ServerAdapter
 
class  pw::rpc::Rpc2Adapter
 
class  pw::rpc::Rpc2ServiceAdapter
 
class  pw::rpc::Server
 
class  pw::rpc::Service
 
class  pw::rpc::Writer
 

Typedefs

template<auto kMethod>
using pw::rpc::MethodRequestType = typename internal::MethodInfo< kMethod >::Request
 
template<auto kMethod>
using pw::rpc::MethodResponseType = typename internal::MethodInfo< kMethod >::Response
 

Enumerations

enum class  MethodType : unsigned char { kUnary = 0b00 , kServerStreaming = 0b01 , kClientStreaming = 0b10 , kBidirectionalStreaming = 0b11 }
 

Functions

constexpr pw::rpc::DynamicCallPtr< CallType, UniquePtr >::DynamicCallPtr ()=default
 Creates an empty DynamicCallPtr.
 
constexpr pw::rpc::DynamicCallPtr< CallType, UniquePtr >::DynamicCallPtr (std::nullptr_t)
 
 pw::rpc::DynamicCallPtr< CallType, UniquePtr >::DynamicCallPtr (UniquePtr ptr)
 Takes ownership of a heap-allocated call object.
 
 pw::rpc::DynamicCallPtr< CallType, UniquePtr >::DynamicCallPtr (const DynamicCallPtr &)=delete
 
DynamicCallPtr & pw::rpc::DynamicCallPtr< CallType, UniquePtr >::operator= (const DynamicCallPtr &)=delete
 
 pw::rpc::DynamicCallPtr< CallType, UniquePtr >::DynamicCallPtr (DynamicCallPtr &&other) noexcept
 
DynamicCallPtr & pw::rpc::DynamicCallPtr< CallType, UniquePtr >::operator= (DynamicCallPtr &&other) noexcept
 
DynamicCallPtr & pw::rpc::DynamicCallPtr< CallType, UniquePtr >::operator= (std::nullptr_t) noexcept
 
void pw::rpc::DynamicCallPtr< CallType, UniquePtr >::reset () noexcept
 
CallType * pw::rpc::DynamicCallPtr< CallType, UniquePtr >::get () const noexcept
 
CallType & pw::rpc::DynamicCallPtr< CallType, UniquePtr >::operator* () const noexcept
 
CallType * pw::rpc::DynamicCallPtr< CallType, UniquePtr >::operator-> () const noexcept
 
 pw::rpc::DynamicCallPtr< CallType, UniquePtr >::operator bool () const noexcept
 
template<typename Ptr , typename = std::enable_if_t<!std::is_pointer_v<Ptr>>>
 pw::rpc::DynamicCallPtr (Ptr) -> DynamicCallPtr< typename std::pointer_traits< Ptr >::element_type, Ptr >
 
template<typename CallType >
DynamicCallPtr< CallType > pw::rpc::MakeDynamicCall (CallType call)
 
template<auto kMethod>
constexpr const auto & pw::rpc::MethodSerde ()
 
template<auto kMethod>
constexpr MethodId pw::rpc::GetMethodId ()
 
template<auto kMethod>
constexpr ServiceId pw::rpc::GetServiceIdForMethod ()
 
constexpr bool pw::rpc::HasServerStream (MethodType type)
 
constexpr bool pw::rpc::HasClientStream (MethodType type)
 
template<auto... kNonOkResponseMethods>
constexpr internal::DeliverNonOkResponsesTag< kNonOkResponseMethods... > pw::rpc::DeliverNonOkResponses ()
 

Friends

bool pw::rpc::DynamicCallPtr< CallType, UniquePtr >::operator== (const DynamicCallPtr &lhs, std::nullptr_t) noexcept
 
bool pw::rpc::DynamicCallPtr< CallType, UniquePtr >::operator== (std::nullptr_t, const DynamicCallPtr &rhs) noexcept
 
bool pw::rpc::DynamicCallPtr< CallType, UniquePtr >::operator!= (const DynamicCallPtr &lhs, std::nullptr_t) noexcept
 
bool pw::rpc::DynamicCallPtr< CallType, UniquePtr >::operator!= (std::nullptr_t, const DynamicCallPtr &rhs) noexcept
 

Function Documentation

◆ DeliverNonOkResponses()

template<auto... kNonOkResponseMethods>
constexpr internal::DeliverNonOkResponsesTag< kNonOkResponseMethods... > pw::rpc::DeliverNonOkResponses ( )
constexpr

Policy tag for Rpc2ServiceFor and Rpc2ServiceAdapter that delivers the response payload (with kOk) when a unary or client streaming pw_rpc handler finishes with a non-OK status.

Pass generated pw_rpc method functions (such as MyServiceImpl::ServiceInfo::MyMethod) to opt in specific methods, or omit template arguments (DeliverNonOkResponses()) to opt in all unary and client streaming methods of the service.

Warning
pw_rpc2 has no application status codes, so pw_rpc2 clients receive kOk alongside the serialized response for any non-OK handler status, including early error returns that leave the response default-initialized. Opted-in methods must encode error state in the response message itself on every non-OK return path. Only use the service-wide DeliverNonOkResponses() form when every unary and client streaming method in the service follows this contract.

◆ DynamicCallPtr()

template<typename Ptr , typename = std::enable_if_t<!std::is_pointer_v<Ptr>>>
pw::rpc::DynamicCallPtr ( Ptr  ) -> DynamicCallPtr< typename std::pointer_traits< Ptr >::element_type, Ptr >

Deduces the call type from an owning smart pointer, such as the pointer returned by the generated pw_protobuf DynamicClient methods.

◆ MakeDynamicCall()

template<typename CallType >
DynamicCallPtr< CallType > pw::rpc::MakeDynamicCall ( CallType  call)

Moves a call object into a heap-allocated DynamicCallPtr using PW_RPC_MAKE_UNIQUE_PTR.

Returns
A DynamicCallPtr that owns the call, or an empty DynamicCallPtr if PW_RPC_MAKE_UNIQUE_PTR fails to allocate the call. If allocation fails, the call is closed.

◆ operator=()

template<typename CallType , typename UniquePtr = decltype(PW_RPC_MAKE_UNIQUE_PTR( CallType, std::declval<CallType>()))>
DynamicCallPtr & pw::rpc::DynamicCallPtr< CallType, UniquePtr >::operator= ( DynamicCallPtr< CallType, UniquePtr > &&  other)
inlinenoexcept

Closes and releases the currently owned call, if any, and takes ownership of other's call.

◆ reset()

template<typename CallType , typename UniquePtr = decltype(PW_RPC_MAKE_UNIQUE_PTR( CallType, std::declval<CallType>()))>
void pw::rpc::DynamicCallPtr< CallType, UniquePtr >::reset ( )
inlinenoexcept

Closes and releases the owned call, if any. Server calls are completed with an OK status and client calls are abandoned, as when a call object is destroyed. A pending on_error from an earlier abort or cancellation is discarded and not invoked.

If none of the call's callbacks are running, the call object and its callbacks are destroyed before this returns. Otherwise, they are destroyed when the last running callback finishes.