diff options
Diffstat (limited to 'include/grpc++/impl/codegen/async_unary_call.h')
| -rw-r--r-- | include/grpc++/impl/codegen/async_unary_call.h | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/include/grpc++/impl/codegen/async_unary_call.h b/include/grpc++/impl/codegen/async_unary_call.h index a147a6acbf..aadf77d8a8 100644 --- a/include/grpc++/impl/codegen/async_unary_call.h +++ b/include/grpc++/impl/codegen/async_unary_call.h @@ -47,18 +47,49 @@ namespace grpc { class CompletionQueue; extern CoreCodegenInterface* g_core_codegen_interface; +/// An interface relevant for async client side unary RPCS (which send +/// one request message to a server and receive one response message). template <class R> class ClientAsyncResponseReaderInterface { public: virtual ~ClientAsyncResponseReaderInterface() {} + + /// Request notification of the reading of initial metadata. Completion + /// will be notified by \a tag on the associated completion queue. + /// This call is optional, but if it is used, it cannot be used concurrently + /// with or after the \a Finish method. + /// + /// \param[in] tag Tag identifying this request. virtual void ReadInitialMetadata(void* tag) = 0; + + /// Request to receive the server's response \a msg and final \a status for + /// the call, and to notify \a tag on this call's completion queue when + /// finished. + /// + /// This function will return when either: + /// - when the server's response message and status have been received. + /// - when the server has returned a non-OK status (no message expected in + /// this case). + /// - when the call failed for some reason and the library generated a + /// non-OK status. + /// + /// \param[in] tag Tag identifying this request. + /// \param[out] status To be updated with the operation status. + /// \param[out] msg To be filled in with the server's response message. virtual void Finish(R* msg, Status* status, void* tag) = 0; }; +/// Async API for client-side unary RPCs, where the message response +/// received from the server is of type \a R. template <class R> class ClientAsyncResponseReader final : public ClientAsyncResponseReaderInterface<R> { public: + /// Start a call and write the request out. + /// \a tag will be notified on \a cq when the call has been started (i.e. + /// intitial metadata sent) and \a request has been written out. + /// Note that \a context will be used to fill in custom initial metadata + /// used to send to the server when starting the call. template <class W> static ClientAsyncResponseReader* Create(ChannelInterface* channel, CompletionQueue* cq, @@ -76,6 +107,12 @@ class ClientAsyncResponseReader final assert(size == sizeof(ClientAsyncResponseReader)); } + /// See \a ClientAsyncResponseReaderInterface::ReadInitialMetadata for + /// semantics. + /// + /// Side effect: + /// - the \a ClientContext associated with this call is updated with + /// possible initial and trailing metadata sent from the serve. void ReadInitialMetadata(void* tag) { GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_); @@ -84,6 +121,11 @@ class ClientAsyncResponseReader final call_.PerformOps(&meta_buf_); } + /// See \a ClientAysncResponseReaderInterface::Finish for semantics. + /// + /// Side effect: + /// - the \a ClientContext associated with this call is updated with + /// possible initial and trailing metadata sent from the server. void Finish(R* msg, Status* status, void* tag) { finish_buf_.set_output_tag(tag); if (!context_->initial_metadata_received_) { @@ -123,12 +165,21 @@ class ClientAsyncResponseReader final finish_buf_; }; +/// Async server-side API for handling unary calls, where the single +/// response message sent to the client is of type \a W. template <class W> class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { public: explicit ServerAsyncResponseWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} + /// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics. + /// + /// Side effect: + /// The initial metadata that will be sent to the client from this op will + /// be taken from the \a ServerContext associated with the call. + /// + /// \param[in] tag Tag identifying this request. void SendInitialMetadata(void* tag) override { GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_); @@ -142,6 +193,21 @@ class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { call_.PerformOps(&meta_buf_); } + /// Indicate that the stream 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. + /// + /// \param[in] tag Tag identifying this request. + /// \param[in] status To be sent to the client as the result of the call. + /// \param[in] msg Message to be sent to the client. + /// + /// Side effect: + /// - also sends initial metadata if not already sent (using the + /// \a ServerContext associated with this call). + /// + /// Note: if \a status has a non-OK code, then \a msg will not be sent, + /// and the client will receive only the status with possible trailing + /// metadata. void Finish(const W& msg, const Status& status, void* tag) { finish_buf_.set_output_tag(tag); if (!ctx_->sent_initial_metadata_) { @@ -162,6 +228,18 @@ class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { call_.PerformOps(&finish_buf_); } + /// Indicate that the stream is to be finished with a non-OK status, + /// and request notification for when the server has finished sending the + /// appropriate signals to the client to end the call. + /// Should not be used concurrently with other operations. + /// + /// \param[in] tag Tag identifying this request. + /// \param[in] status To be sent to the client as the result of the call. + /// - Note: \a status must have a non-OK code. + /// + /// Side effect: + /// - also sends initial metadata if not already sent (using the + /// \a ServerContext associated with this call). void FinishWithError(const Status& status, void* tag) { GPR_CODEGEN_ASSERT(!status.ok()); finish_buf_.set_output_tag(tag); |