synchronous_call.h File Reference

#include <utility>
#include "pw_chrono/system_clock.h"
#include "pw_rpc/client.h"
#include "pw_rpc/internal/method_info.h"
#include "pw_rpc/internal/synchronous_call_impl.h"
#include "pw_rpc/synchronous_call_result.h"

Go to the source code of this file.

Namespaces
namespace	pw
	Provides basic helpers for reading and writing UTF-8 encoded strings.

Functions
template<auto kRpcMethod, typename Response = typename internal::MethodInfo<kRpcMethod>::Response>
SynchronousCallResult< Response >	pw::rpc::SynchronousCall (Client &client, uint32_t channel_id, const typename internal::MethodInfo< kRpcMethod >::Request &request)
template<auto kRpcMethod, typename GeneratedClient >
SynchronousCallResult< typename internal::MethodInfo< kRpcMethod >::Response >	pw::rpc::SynchronousCall (const GeneratedClient &client, const typename internal::MethodInfo< kRpcMethod >::Request &request)
template<auto kRpcMethod>
Status	pw::rpc::SynchronousCall (Client &client, uint32_t channel_id, ConstByteSpan request, Function< void(ConstByteSpan, Status)> &&on_completed)
template<auto kRpcMethod>
Status	pw::rpc::SynchronousCall (const typename internal::MethodInfo< kRpcMethod >::GeneratedClient &client, ConstByteSpan request, Function< void(ConstByteSpan, Status)> &&on_completed)
template<auto kRpcMethod>
SynchronousCallResult< typename internal::MethodInfo< kRpcMethod >::Response >	pw::rpc::SynchronousCallFor (Client &client, uint32_t channel_id, const typename internal::MethodInfo< kRpcMethod >::Request &request, chrono::SystemClock::duration timeout)
template<auto kRpcMethod, typename GeneratedClient >
SynchronousCallResult< typename internal::MethodInfo< kRpcMethod >::Response >	pw::rpc::SynchronousCallFor (const GeneratedClient &client, const typename internal::MethodInfo< kRpcMethod >::Request &request, chrono::SystemClock::duration timeout)
template<auto kRpcMethod>
Status	pw::rpc::SynchronousCallFor (Client &client, uint32_t channel_id, ConstByteSpan request, chrono::SystemClock::duration timeout, Function< void(ConstByteSpan, Status)> &&on_completed)
template<auto kRpcMethod>
Status	pw::rpc::SynchronousCallFor (const typename internal::MethodInfo< kRpcMethod >::GeneratedClient &client, ConstByteSpan request, chrono::SystemClock::duration timeout, Function< void(ConstByteSpan, Status)> &&on_completed)
template<auto kRpcMethod>
SynchronousCallResult< typename internal::MethodInfo< kRpcMethod >::Response >	pw::rpc::SynchronousCallUntil (Client &client, uint32_t channel_id, const typename internal::MethodInfo< kRpcMethod >::Request &request, chrono::SystemClock::time_point deadline)
template<auto kRpcMethod>
SynchronousCallResult< typename internal::MethodInfo< kRpcMethod >::Response >	pw::rpc::SynchronousCallUntil (const typename internal::MethodInfo< kRpcMethod >::GeneratedClient &client, const typename internal::MethodInfo< kRpcMethod >::Request &request, chrono::SystemClock::time_point deadline)
template<auto kRpcMethod>
Status	pw::rpc::SynchronousCallUntil (Client &client, uint32_t channel_id, ConstByteSpan request, chrono::SystemClock::time_point deadline, Function< void(ConstByteSpan, Status)> &&on_completed)
template<auto kRpcMethod>
Status	pw::rpc::SynchronousCallUntil (const typename internal::MethodInfo< kRpcMethod >::GeneratedClient &client, ConstByteSpan request, chrono::SystemClock::time_point deadline, Function< void(ConstByteSpan, Status)> &&on_completed)

Detailed Description

pw_rpc provides wrappers that convert the asynchronous client API to a synchronous API. The SynchronousCall<RpcMethod> functions wrap the asynchronous client RPC call with a timed thread notification and returns once a result is known or a timeout has occurred. Only unary methods are supported.

The Nanopb and pwpb APIs return a SynchronousCallResult<Response> object, which can be queried to determine whether any error scenarios occurred and, if not, access the response. The raw API executes a function when the call completes or returns a pw::Status if it does not.

SynchronousCall<RpcMethod> blocks indefinitely, whereas SynchronousCallFor<RpcMethod> and SynchronousCallUntil<RpcMethod> block for a given timeout or until a deadline, respectively. All wrappers work with either the standalone static RPC functions or the generated service client member methods.

Note

Use of the SynchronousCall wrappers requires a

embed:rst:inline :cpp:class:`pw::sync::TimedThreadNotification` 

backend.

The following examples use the Nanopb API to make a call that blocks indefinitely. If you'd like to include a timeout for how long the call should block for, use the SynchronousCallFor() or SynchronousCallUntil() variants.

pw_rpc_EchoMessage request{.msg = "hello" };
pw::rpc::SynchronousCallResult<pw_rpc_EchoMessage> result =
  pw::rpc::SynchronousCall<EchoService::Echo>(rpc_client,
                                              channel_id,
                                              request);
if (result.ok()) {
  PW_LOG_INFO("%s", result.response().msg);
}

Additionally, the use of a generated Client object is supported:

pw_rpc::nanopb::EchoService::Client client(rpc_client, channel_id);
pw_rpc_EchoMessage request{.msg = "hello" };
pw::rpc::SynchronousCallResult<pw_rpc_EchoMessage> result =
  pw::rpc::SynchronousCall<EchoService::Echo>(client, request);
 
if (result.ok()) {
  PW_LOG_INFO("%s", result.response().msg);
}

SynchronousCall<RpcMethod> also supports using an optional custom response message class, SynchronousCall<RpcMethod, Response>. This enables the use of response messages with variable-length fields.

pw_rpc_MyMethodRequestMessage request{};
class CustomResponse : public pw_rpc_MyMethodResponseMessage {
 public:
  CustomResponse() {
    repeated_field.SetDecoder([this](
      MyMethodResponse::StreamDecoder& decoder) {
        return decoder.ReadRepeatedField(values);
      }
  }
  pw::Vector<uint32_t, 4> values();
 };
 pw::rpc::SynchronousCallResult<CustomResponse> result =
   pw::rpc::SynchronousCall<EchoService::Echo, CustomResponse>(rpc_client,
                                                               channel_id,
                                                               request);
 if (result.ok()) {
   PW_LOG_INFO("%d", result.response().values[0]);
 }
};

The raw API works similarly to the Nanopb API, but takes a

embed:rst:inline :cpp:type:`pw::Function` 

and returns a

embed:rst:inline :cpp:class:`pw::Status` 

. If the RPC completes, the

embed:rst:inline :cpp:type:`pw::Function` 

is called with the response and returned status, and the SynchronousCall invocation returns

embed:rst:inline :c:enumerator:`OK` 

. If the RPC fails, SynchronousCall returns an error.

pw::Status rpc_status = pw::rpc::SynchronousCall<EchoService::Echo>(
    rpc_client, channel_id, encoded_request,
    [](pw::ConstByteSpan reply, pw::Status status) {
      PW_LOG_INFO("Received %zu bytes with status %s",
                  reply.size(),
                  status.str());
    });

Warning

These wrappers should not be used from any context that cannot be blocked! This method will block the calling thread until the RPC completes, and translate the response into a pw::rpc::SynchronousCallResult that contains the error type and status or the proto response.

Function Documentation

SynchronousCall() [1/4]

template<auto kRpcMethod, typename Response = typename internal::MethodInfo<kRpcMethod>::Response>

SynchronousCallResult< Response > pw::rpc::SynchronousCall	(	Client &	client,
		uint32_t	channel_id,
		const typename internal::MethodInfo< kRpcMethod >::Request &	request
	)

Invokes a unary RPC synchronously using Nanopb or pwpb. Blocks indefinitely until a response is received.

Parameters

client	The pw::rpc::Client to use for the call
channel_id	The ID of the RPC channel to make the call on
request	The proto struct to send as the request

SynchronousCall() [2/4]

template<auto kRpcMethod>

Status pw::rpc::SynchronousCall	(	Client &	client,
		uint32_t	channel_id,
		ConstByteSpan	request,
		Function< void(ConstByteSpan, Status)> &&	on_completed
	)

Invokes a unary RPC synchronously using the raw API. Blocks until a response is received.

SynchronousCall() [3/4]

template<auto kRpcMethod, typename GeneratedClient >

SynchronousCallResult< typename internal::MethodInfo< kRpcMethod >::Response > pw::rpc::SynchronousCall	(	const GeneratedClient &	client,
		const typename internal::MethodInfo< kRpcMethod >::Request &	request
	)

Invokes a unary RPC synchronously using Nanopb or pwpb. Blocks indefinitely until a response is received.

Parameters

client	The generated service client to use for the call
request	The proto struct to send as the request

SynchronousCall() [4/4]

template<auto kRpcMethod>

Status pw::rpc::SynchronousCall	(	const typename internal::MethodInfo< kRpcMethod >::GeneratedClient &	client,
		ConstByteSpan	request,
		Function< void(ConstByteSpan, Status)> &&	on_completed
	)

Invokes a unary RPC synchronously using the raw API. Blocks until a response is received.

SynchronousCallFor() [1/4]

template<auto kRpcMethod>

SynchronousCallResult< typename internal::MethodInfo< kRpcMethod >::Response > pw::rpc::SynchronousCallFor	(	Client &	client,
		uint32_t	channel_id,
		const typename internal::MethodInfo< kRpcMethod >::Request &	request,
		chrono::SystemClock::duration	timeout
	)

Invokes a unary RPC synchronously using Nanopb or pwpb. Blocks until a response is received or the provided timeout passes.

Parameters

client	The pw::rpc::Client to use for the call
channel_id	The ID of the RPC channel to make the call on
request	The proto struct to send as the request
timeout	Duration to block for before returning with Timeout

SynchronousCallFor() [2/4]

template<auto kRpcMethod>

Status pw::rpc::SynchronousCallFor	(	Client &	client,
		uint32_t	channel_id,
		ConstByteSpan	request,
		chrono::SystemClock::duration	timeout,
		Function< void(ConstByteSpan, Status)> &&	on_completed
	)

Invokes a unary RPC synchronously using the raw API. Blocks until a response is received or the provided timeout passes.

SynchronousCallFor() [3/4]

template<auto kRpcMethod, typename GeneratedClient >

SynchronousCallResult< typename internal::MethodInfo< kRpcMethod >::Response > pw::rpc::SynchronousCallFor	(	const GeneratedClient &	client,
		const typename internal::MethodInfo< kRpcMethod >::Request &	request,
		chrono::SystemClock::duration	timeout
	)

Invokes a unary RPC synchronously using Nanopb or pwpb. Blocks until a response is received or the provided timeout passes.

Parameters

client	The generated service client to use for the call
request	The proto struct to send as the request
timeout	Duration to block for before returning with Timeout

SynchronousCallFor() [4/4]

template<auto kRpcMethod>

Status pw::rpc::SynchronousCallFor	(	const typename internal::MethodInfo< kRpcMethod >::GeneratedClient &	client,
		ConstByteSpan	request,
		chrono::SystemClock::duration	timeout,
		Function< void(ConstByteSpan, Status)> &&	on_completed
	)

Invokes a unary RPC synchronously using the raw API. Blocks until a response is received or the provided timeout passes.

SynchronousCallUntil() [1/4]

template<auto kRpcMethod>

SynchronousCallResult< typename internal::MethodInfo< kRpcMethod >::Response > pw::rpc::SynchronousCallUntil	(	Client &	client,
		uint32_t	channel_id,
		const typename internal::MethodInfo< kRpcMethod >::Request &	request,
		chrono::SystemClock::time_point	deadline
	)

Invokes a unary RPC synchronously using Nanopb or pwpb. Blocks until a response is received or the provided deadline arrives.

Parameters

client	The pw::rpc::Client to use for the call
channel_id	The ID of the RPC channel to make the call on
request	The proto struct to send as the request
deadline	Timepoint to block until before returning with Timeout

SynchronousCallUntil() [2/4]

template<auto kRpcMethod>

Status pw::rpc::SynchronousCallUntil	(	Client &	client,
		uint32_t	channel_id,
		ConstByteSpan	request,
		chrono::SystemClock::time_point	deadline,
		Function< void(ConstByteSpan, Status)> &&	on_completed
	)

Invokes a unary RPC synchronously using the raw API. Blocks until a response is received or the provided deadline arrives.

SynchronousCallUntil() [3/4]

template<auto kRpcMethod>

SynchronousCallResult< typename internal::MethodInfo< kRpcMethod >::Response > pw::rpc::SynchronousCallUntil	(	const typename internal::MethodInfo< kRpcMethod >::GeneratedClient &	client,
		const typename internal::MethodInfo< kRpcMethod >::Request &	request,
		chrono::SystemClock::time_point	deadline
	)

Invokes a unary RPC synchronously using Nanopb or pwpb. Blocks until a response is received or the provided deadline arrives.

Parameters

client	The generated service client to use for the call
request	The proto struct to send as the request
deadline	Timepoint to block until before returning with Timeout

SynchronousCallUntil() [4/4]

template<auto kRpcMethod>

Status pw::rpc::SynchronousCallUntil	(	const typename internal::MethodInfo< kRpcMethod >::GeneratedClient &	client,
		ConstByteSpan	request,
		chrono::SystemClock::time_point	deadline,
		Function< void(ConstByteSpan, Status)> &&	on_completed
	)

Invokes a unary RPC synchronously using the raw API. Blocks until a response is received or the provided deadline arrives.