asio-grpc v1.4.0
Asynchronous gRPC with Asio/unified executors
agrpc::detail::FinishFn Struct Reference

Client and server-side function object to finish RPCs. More...

#include <agrpc/rpc.hpp>

Public Member Functions

template<class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (grpc::ServerAsyncWriter< Response > &writer, const grpc::Status &status, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Finish a server stream. More...
 
template<class Response , class Request , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (grpc::ServerAsyncReader< Response, Request > &reader, const Response &response, const grpc::Status &status, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Finish a client stream (server-side) More...
 
template<class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (grpc::ServerAsyncResponseWriter< Response > &writer, const Response &response, const grpc::Status &status, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Finish a unary RPC (server-side) More...
 
template<class Response , class Request , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (grpc::ServerAsyncReaderWriter< Response, Request > &reader_writer, const grpc::Status &status, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Finish a bidirectional stream (server-side) More...
 
template<class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (grpc::ClientAsyncReader< Response > &reader, grpc::Status &status, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Finish a server stream (client-side) More...
 
template<class Request , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (grpc::ClientAsyncWriter< Request > &writer, grpc::Status &status, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Finish a client stream (client-side) More...
 
template<class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (grpc::ClientAsyncResponseReader< Response > &reader, Response &response, grpc::Status &status, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Finish a unary RPC (client-side) More...
 
template<class Request , class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (grpc::ClientAsyncReaderWriter< Request, Response > &reader_writer, grpc::Status &status, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Finish a bidirectional stream (client-side) More...
 

Detailed Description

Client and server-side function object to finish RPCs.

The examples below are based on the following .proto file:

syntax = "proto3";
package example.v1;
service Example {
rpc ServerStreaming(Request) returns (stream Response) {}
rpc ClientStreaming(stream Request) returns (Response) {}
rpc BidirectionalStreaming(stream Request) returns (stream Response) {}
rpc Unary(Request) returns (Response) {}
}
message Request {
int32 integer = 1;
}
message Response {
int32 integer = 1;
}
Attention
The completion handler created from the completion token that is provided to the functions described below must have an associated executor that refers to a GrpcContext:
asio::io_context io_context;
asio::co_spawn(
io_context,
[&]() -> asio::awaitable<void>
{
grpc::ServerContext server_context;
grpc::ServerAsyncReader<example::v1::Response, example::v1::Request> reader{&server_context};
// error: asio::this_coro::executor does not refer to a GrpcContext
// co_await agrpc::request(&example::v1::Example::AsyncService::RequestClientStreaming, service,
// server_context, reader, asio::use_awaitable);
// correct:
co_await agrpc::request(&example::v1::Example::AsyncService::RequestClientStreaming, service,
server_context, reader, asio::bind_executor(grpc_context, asio::use_awaitable));
},
asio::detached);
constexpr detail::RequestFn request
Start a new RPC.
Definition: rpc.hpp:1394

Member Function Documentation

◆ operator()() [1/8]

template<class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::FinishFn::operator() ( grpc::ClientAsyncReader< Response > &  reader,
grpc::Status &  status,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Finish a server stream (client-side)

Indicate that the stream is to be finished and request notification for when the call has been ended.

Should not be used concurrently with other operations.

It is appropriate to call this method exactly once when:

  • All messages from the server have been received (either known implictly, or explicitly because a previous read operation returned false).

The operation will finish when either:

  • All incoming messages have been read and the server has returned a status.
  • The server has returned a non-OK status.
  • The call failed for some reason and the library generated a status.

Note that implementations of this method attempt to receive initial metadata from the server if initial metadata has not been received yet.

Side effect:

  • The ClientContext associated with the call is updated with possible initial and trailing metadata received from the server.

Example:

grpc::Status status;
bool finish_ok = co_await agrpc::finish(*reader, status, asio::use_awaitable);
constexpr detail::FinishFn finish
Finish a RPC.
Definition: rpc.hpp:1430
Parameters
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(bool). The bool should always be true.

◆ operator()() [2/8]

template<class Request , class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::FinishFn::operator() ( grpc::ClientAsyncReaderWriter< Request, Response > &  reader_writer,
grpc::Status &  status,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Finish a bidirectional stream (client-side)

Indicate that the stream is to be finished and request notification for when the call has been ended.

Should not be used concurrently with other operations.

It is appropriate to call this method exactly once when:

  • All messages from the server have been received (either known implictly, or explicitly because a previous read operation returned false).
  • The client side has no more message to send (this can be declared implicitly by calling this method, or explicitly through an earlier call to the writes_done method).

The operation will finish when either:

  • All incoming messages have been read and the server has returned a status.
  • The server has returned a non-OK status.
  • The call failed for some reason and the library generated a status.

Note that implementations of this method attempt to receive initial metadata from the server if initial metadata has not been received yet.

Side effect:

  • The ClientContext associated with the call is updated with possible initial and trailing metadata sent from the server.

Example:

grpc::Status status;
bool finish_ok = co_await agrpc::finish(*reader_writer, status, asio::use_awaitable);
Parameters
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(bool). The bool should always be true.

◆ operator()() [3/8]

template<class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::FinishFn::operator() ( grpc::ClientAsyncResponseReader< Response > &  reader,
Response &  response,
grpc::Status &  status,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Finish a unary RPC (client-side)

Receive the server's response message and final status for the call.

This operation will finish when either:

  • The server's response message and status have been received.
  • The server has returned a non-OK status (no message expected in this case).
  • The call failed for some reason and the library generated a non-OK status.

Side effect:

  • The ClientContext associated with the call is updated with possible initial and trailing metadata sent from the server.

Example:

example::v1::Response response;
grpc::Status status;
bool finish_ok = co_await agrpc::finish(*reader, response, status, asio::use_awaitable);
Parameters
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(bool). The bool should always be true.

◆ operator()() [4/8]

template<class Request , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::FinishFn::operator() ( grpc::ClientAsyncWriter< Request > &  writer,
grpc::Status &  status,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Finish a client stream (client-side)

Indicate that the stream is to be finished and request notification for when the call has been ended.

Should not be used concurrently with other operations.

It is appropriate to call this method exactly once when:

  • The client side has no more message to send (this can be declared implicitly by calling this method, or explicitly through an earlier call to the writes_done method).

The operation will finish when either:

  • All incoming messages have been read and the server has returned a status.
  • The server has returned a non-OK status.
  • The call failed for some reason and the library generated a status.

Note that implementations of this method attempt to receive initial metadata from the server if initial metadata has not been received yet.

Side effect:

  • The ClientContext associated with the call is updated with possible initial and trailing metadata received from the server.
  • Attempts to fill in the response parameter that was passed to request.

Example:

grpc::Status status;
bool finish_ok = co_await agrpc::finish(*writer, status, asio::use_awaitable);
Parameters
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(bool). The bool should always be true.

◆ operator()() [5/8]

template<class Response , class Request , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::FinishFn::operator() ( grpc::ServerAsyncReader< Response, Request > &  reader,
const Response &  response,
const grpc::Status &  status,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Finish a client stream (server-side)

Side effect:

  • Also sends initial metadata if not alreay sent.
  • Uses the ServerContext associated with the call to send possible initial and trailing metadata.
Note
Response is not sent if status has a non-OK code.

gRPC does not take ownership or a reference to response and status, so it is safe to deallocate once finish returns.

Example:

example::v1::Response response;
bool finish_ok = co_await agrpc::finish(reader, response, grpc::Status::OK, asio::use_awaitable);
Parameters
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(bool). true means that the data/metadata/status/etc is going to go to the wire. If it is false, it is not going to the wire because the call is already dead (i.e., canceled, deadline expired, other side dropped the channel, etc).

◆ operator()() [6/8]

template<class Response , class Request , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::FinishFn::operator() ( grpc::ServerAsyncReaderWriter< Response, Request > &  reader_writer,
const grpc::Status &  status,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Finish a bidirectional stream (server-side)

Indicate that the stream is to be finished with a certain status code. Should not be used concurrently with other operations.

It is appropriate to call this method when either:

  • All messages from the client have been received (either known implictly, or explicitly because a previous read operation returned false).
  • It is desired to end the call early with some non-OK status code.

This operation will end when the server has finished sending out initial metadata (if not sent already) and status, or if some failure occurred when trying to do so.

The ServerContext associated with the call is used for sending trailing (and initial if not already sent) metadata to the client. There are no restrictions to the code of status, it may be non-OK. gRPC does not take ownership or a reference to status, so it is safe to to deallocate once finish returns.

Example:

bool finish_ok = co_await agrpc::finish(reader_writer, grpc::Status::OK, asio::use_awaitable);
Parameters
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(bool). true means that the data/metadata/status/etc is going to go to the wire. If it is false, it is not going to the wire because the call is already dead (i.e., canceled, deadline expired, other side dropped the channel, etc).

◆ operator()() [7/8]

template<class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::FinishFn::operator() ( grpc::ServerAsyncResponseWriter< Response > &  writer,
const Response &  response,
const grpc::Status &  status,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Finish a unary RPC (server-side)

Indicate that the RPC is to be finished and request notification when the server has sent the appropriate signals to the client to end the call. Should not be used concurrently with other operations.

Side effect:

  • Also sends initial metadata if not already sent (using the ServerContext associated with the call).
Note
If status has a non-OK code, then response will not be sent, and the client will receive only the status with possible trailing metadata.

Example:

example::v1::Response response;
bool finish_ok = co_await agrpc::finish(writer, response, grpc::Status::OK, asio::use_awaitable);
Parameters
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(bool). true means that the data/metadata/status/etc is going to go to the wire. If it is false, it is not going to the wire because the call is already dead (i.e., canceled, deadline expired, other side dropped the channel, etc).

◆ operator()() [8/8]

template<class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::FinishFn::operator() ( grpc::ServerAsyncWriter< Response > &  writer,
const grpc::Status &  status,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Finish a server stream.

Indicate that the stream is to be finished with a certain status code. Should not be used concurrently with other operations.

It is appropriate to call this method when either:

  • All messages from the client have been received (either known implictly, or explicitly because a previous read operation returned false).
  • It is desired to end the call early with some non-OK status code.

This operation will end when the server has finished sending out initial metadata (if not sent already) and status, or if some failure occurred when trying to do so.

The ServerContext associated with the call is used for sending trailing (and initial if not already sent) metadata to the client. There are no restrictions to the code of status, it may be non-OK. gRPC does not take ownership or a reference to status, so it is safe to to deallocate once finish returns.

Example:

bool finish_ok = co_await agrpc::finish(writer, grpc::Status::OK, asio::use_awaitable);
Parameters
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(bool). true means that the data/metadata/status/etc is going to go to the wire. If it is false, it is not going to the wire because the call is already dead (i.e., canceled, deadline expired, other side dropped the channel, etc).