diff options
Diffstat (limited to 'include/grpc++/impl/codegen')
20 files changed, 734 insertions, 143 deletions
diff --git a/include/grpc++/impl/codegen/async_stream.h b/include/grpc++/impl/codegen/async_stream.h index f97d824baf..04fc5241cb 100644 --- a/include/grpc++/impl/codegen/async_stream.h +++ b/include/grpc++/impl/codegen/async_stream.h @@ -53,16 +53,38 @@ class ClientAsyncStreamingInterface { /// Request notification of the reading of the 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 Read method. + /// with or after the \a AsyncReaderInterface::Read method. /// /// \param[in] tag Tag identifying this request. virtual void ReadInitialMetadata(void* tag) = 0; - /// Indicate that the stream is to be finished and request notification - /// Should not be used concurrently with other operations + /// 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 when both: + /// * 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 <i>WritesDone</i> method + /// of the class in use, e.g. \a ClientAsyncWriterInterface::WritesDone or + /// \a ClientAsyncReaderWriterInterface::WritesDone). + /// * there are no more messages to be received from the server (this can + /// be known implicitly by the calling code, or explicitly from an + /// earlier call to \a AsyncReaderInterface::Read that yielded a failed + /// result, e.g. cq->Next(&read_tag, &ok) filled in 'ok' with 'false'). + /// + /// This function will return 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 hasn't yet been received. /// - /// \param[out] status To be updated with the operation status. /// \param[in] tag Tag identifying this request. + /// \param[out] status To be updated with the operation status. virtual void Finish(Status* status, void* tag) = 0; }; @@ -77,11 +99,14 @@ class AsyncReaderInterface { /// This is thread-safe with respect to \a Write or \a WritesDone methods. It /// should not be called concurrently with other streaming APIs /// on the same stream. It is not meaningful to call it concurrently - /// with another \a Read on the same stream since reads on the same stream - /// are delivered in order. + /// with another \a AsyncReaderInterface::Read on the same stream since reads + /// on the same stream are delivered in order. /// /// \param[out] msg Where to eventually store the read message. /// \param[in] tag The tag identifying the operation. + /// + /// Side effect: note that this method attempt to receive initial metadata for + /// a stream if it hasn't yet been received. virtual void Read(R* msg, void* tag) = 0; }; @@ -96,7 +121,7 @@ class AsyncWriterInterface { /// Only one write may be outstanding at any given time. This means that /// after calling Write, one must wait to receive \a tag from the completion /// queue BEFORE calling Write again. - /// This is thread-safe with respect to \a Read + /// This is thread-safe with respect to \a AsyncReaderInterface::Read /// /// \param[in] msg The message to be written. /// \param[in] tag The tag identifying the operation. @@ -109,7 +134,7 @@ class AsyncWriterInterface { /// after calling Write, one must wait to receive \a tag from the completion /// queue BEFORE calling Write again. /// WriteOptions \a options is used to set the write options of this message. - /// This is thread-safe with respect to \a Read + /// This is thread-safe with respect to \a AsyncReaderInterface::Read /// /// \param[in] msg The message to be written. /// \param[in] options The WriteOptions to be used to write this message. @@ -117,11 +142,11 @@ class AsyncWriterInterface { virtual void Write(const W& msg, WriteOptions options, void* tag) = 0; /// Request the writing of \a msg and coalesce it with the writing - /// of trailing metadata, using WriteOptions \a options with identifying tag - /// \a tag. + /// of trailing metadata, using WriteOptions \a options with + /// identifying tag \a tag. /// - /// For client, WriteLast is equivalent of performing Write and WritesDone in - /// a single step. + /// For client, WriteLast is equivalent of performing Write and + /// WritesDone in a single step. /// For server, WriteLast buffers the \a msg. The writing of \a msg is held /// until Finish is called, where \a msg and trailing metadata are coalesced /// and write is initiated. Note that WriteLast can only buffer \a msg up to @@ -140,10 +165,17 @@ template <class R> class ClientAsyncReaderInterface : public ClientAsyncStreamingInterface, public AsyncReaderInterface<R> {}; +/// Async client-side API for doing server-streaming RPCs, +/// where the incoming message stream coming from the server has +/// messages of type \a R. template <class R> class ClientAsyncReader final : public ClientAsyncReaderInterface<R> { public: /// Create a stream and write the first request out. + /// \a tag will be notified on \a cq when the call has been started 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 ClientAsyncReader* Create(ChannelInterface* channel, CompletionQueue* cq, const RpcMethod& method, @@ -160,6 +192,14 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface<R> { assert(size == sizeof(ClientAsyncReader)); } + /// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata + /// method for semantics. + /// + /// Side effect: + /// - upon receiving initial metadata from the server, + /// the \a ClientContext associated with this call is updated, and the + /// calling code can access the received metadata through the + /// \a ClientContext. void ReadInitialMetadata(void* tag) override { GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_); @@ -177,6 +217,11 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface<R> { call_.PerformOps(&read_ops_); } + /// See the \a ClientAsyncStreamingInterface.Finish method for semantics. + /// + /// Side effect: + /// - the \a ClientContext associated with this call is updated with + /// possible initial and trailing metadata received from the server. void Finish(Status* status, void* tag) override { finish_ops_.set_output_tag(tag); if (!context_->initial_metadata_received_) { @@ -214,16 +259,27 @@ template <class W> class ClientAsyncWriterInterface : public ClientAsyncStreamingInterface, public AsyncWriterInterface<W> { public: - /// Signal the client is done with the writes. - /// Thread-safe with respect to \a Read + /// Signal the client is done with the writes (half-close the client stream). + /// Thread-safe with respect to \a AsyncReaderInterface::Read /// /// \param[in] tag The tag identifying the operation. virtual void WritesDone(void* tag) = 0; }; +/// Async API on the client side for doing client-streaming RPCs, +/// where the outgoing message stream going to the server contains +/// messages of type \a W. template <class W> class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> { public: + /// Create a stream and write the first 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. + /// \a response will be filled in with the single expected response + /// message from the server upon a successful call to the \a Finish + /// method of this instance. template <class R> static ClientAsyncWriter* Create(ChannelInterface* channel, CompletionQueue* cq, const RpcMethod& method, @@ -240,6 +296,13 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> { assert(size == sizeof(ClientAsyncWriter)); } + /// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata method for + /// semantics. + /// + /// Side effect: + /// - upon receiving initial metadata from the server, the \a ClientContext + /// associated with this call is updated, and the calling code can access + /// the received metadata through the \a ClientContext. void ReadInitialMetadata(void* tag) override { GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_); @@ -272,6 +335,13 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> { call_.PerformOps(&write_ops_); } + /// See the \a ClientAsyncStreamingInterface.Finish method for semantics. + /// + /// Side effect: + /// - the \a ClientContext associated with this call is updated with + /// possible initial and trailing metadata received from the server. + /// - attempts to fill in the \a response parameter passed to this class's + /// constructor with the server's response message. void Finish(Status* status, void* tag) override { finish_ops_.set_output_tag(tag); if (!context_->initial_metadata_received_) { @@ -310,23 +380,34 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> { finish_ops_; }; -/// Client-side interface for asynchronous bi-directional streaming. +/// Async client-side interface for bi-directional streaming, +/// where the client-to-server message stream has messages of type \a W, +/// and the server-to-client message stream has messages of type \a R. template <class W, class R> class ClientAsyncReaderWriterInterface : public ClientAsyncStreamingInterface, public AsyncWriterInterface<W>, public AsyncReaderInterface<R> { public: - /// Signal the client is done with the writes. - /// Thread-safe with respect to \a Read + /// Signal the client is done with the writes (half-close the client stream). + /// Thread-safe with respect to \a AsyncReaderInterface::Read /// /// \param[in] tag The tag identifying the operation. virtual void WritesDone(void* tag) = 0; }; +/// Async client-side interface for bi-directional streaming, +/// where the outgoing message stream going to the server +/// has messages of type \a W, and the incoming message stream coming +/// from the server has messages of type \a R. template <class W, class R> class ClientAsyncReaderWriter final : public ClientAsyncReaderWriterInterface<W, R> { public: + /// Create a stream and write the first request out. + /// \a tag will be notified on \a cq when the call has been started (i.e. + /// intitial metadata sent). + /// Note that \a context will be used to fill in custom initial metadata + /// used to send to the server when starting the call. static ClientAsyncReaderWriter* Create(ChannelInterface* channel, CompletionQueue* cq, const RpcMethod& method, @@ -343,6 +424,13 @@ class ClientAsyncReaderWriter final assert(size == sizeof(ClientAsyncReaderWriter)); } + /// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata method + /// for semantics of this method. + /// + /// Side effect: + /// - upon receiving initial metadata from the server, the \a ClientContext + /// is updated with it, and then the receiving initial metadata can + /// be accessed through this \a ClientContext. void ReadInitialMetadata(void* tag) override { GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_); @@ -384,6 +472,10 @@ class ClientAsyncReaderWriter final call_.PerformOps(&write_ops_); } + /// See the \a ClientAsyncStreamingInterface.Finish method 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(Status* status, void* tag) override { finish_ops_.set_output_tag(tag); if (!context_->initial_metadata_received_) { @@ -422,17 +514,62 @@ template <class W, class R> class ServerAsyncReaderInterface : public ServerAsyncStreamingInterface, public AsyncReaderInterface<R> { public: + /// Indicate that the stream is to be finished with a certain status code + /// and also send out \a msg response to the client. + /// Request notification for when the server has sent the response and the + /// appropriate signals to the client to end the call. + /// Should not be used concurrently with other operations. + /// + /// It is appropriate to call this method when: + /// * all messages from the client have been received (either known + /// implictly, or explicitly because a previous + /// \a AsyncReaderInterface::Read operation with a non-ok result, + /// e.g., cq->Next(&read_tag, &ok) filled in 'ok' with 'false'). + /// + /// This operation will end when the server has finished sending out initial + /// metadata (if not sent already), response message, and status, or if + /// some failure occurred when trying to do so. + /// + /// \param[in] tag Tag identifying this request. + /// \param[in] status To be sent to the client as the result of this call. + /// \param[in] msg To be sent to the client as the response for this call. virtual void Finish(const W& msg, const Status& status, void* tag) = 0; + /// Indicate that the stream is to be finished with a certain + /// non-OK status code. + /// Request notification for when the server has sent the appropriate + /// signals to the client to end the call. + /// Should not be used concurrently with other operations. + /// + /// This call is meant to end the call with some error, and can be called at + /// any point that the server would like to "fail" the call (though note + /// this shouldn't be called concurrently with any other "sending" call, like + /// \a AsyncWriterInterface::Write). + /// + /// 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. + /// + /// \param[in] tag Tag identifying this request. + /// \param[in] status To be sent to the client as the result of this call. + /// - Note: \a status must have a non-OK code. virtual void FinishWithError(const Status& status, void* tag) = 0; }; +/// Async server-side API for doing client-streaming RPCs, +/// where the incoming message stream from the client has messages of type \a R, +/// and the single response message sent from the server is type \a W. template <class W, class R> class ServerAsyncReader final : public ServerAsyncReaderInterface<W, R> { public: explicit ServerAsyncReader(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} + /// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics. + /// + /// Implicit input parameter: + /// - The initial metadata that will be sent to the client from this op will + /// be taken from the \a ServerContext associated with the call. void SendInitialMetadata(void* tag) override { GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_); @@ -452,6 +589,14 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface<W, R> { call_.PerformOps(&read_ops_); } + /// See the \a ServerAsyncReaderInterface.Read method for semantics + /// + /// Side effect: + /// - also sends initial metadata if not alreay sent. + /// - uses the \a ServerContext associated with this call to send possible + /// initial and trailing metadata. + /// + /// Note: \a msg is not sent if \a status has a non-OK code. void Finish(const W& msg, const Status& status, void* tag) override { finish_ops_.set_output_tag(tag); if (!ctx_->sent_initial_metadata_) { @@ -472,6 +617,12 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface<W, R> { call_.PerformOps(&finish_ops_); } + /// See the \a ServerAsyncReaderInterface.Read method for semantics + /// + /// Side effect: + /// - also sends initial metadata if not alreay sent. + /// - uses the \a ServerContext associated with this call to send possible + /// initial and trailing metadata. void FinishWithError(const Status& status, void* tag) override { GPR_CODEGEN_ASSERT(!status.ok()); finish_ops_.set_output_tag(tag); @@ -503,14 +654,32 @@ template <class W> class ServerAsyncWriterInterface : public ServerAsyncStreamingInterface, public AsyncWriterInterface<W> { public: + /// Indicate that the stream is to be finished with a certain status code. + /// Request notification for when the server has sent the appropriate + /// signals to the client to end the call. + /// 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 \a + /// AsyncReaderInterface::Read operation with a non-ok + /// result (e.g., cq->Next(&read_tag, &ok) filled in 'ok' with '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), response message, and status, or if + /// some failure occurred when trying to do so. + /// + /// \param[in] tag Tag identifying this request. + /// \param[in] status To be sent to the client as the result of this call. virtual void Finish(const Status& status, void* tag) = 0; /// Request the writing of \a msg and coalesce it with trailing metadata which - /// contains \a status, using WriteOptions options with identifying tag \a - /// tag. + /// contains \a status, using WriteOptions options with + /// identifying tag \a tag. /// - /// WriteAndFinish is equivalent of performing WriteLast and Finish in a - /// single step. + /// WriteAndFinish is equivalent of performing WriteLast and Finish + /// in a single step. /// /// \param[in] msg The message to be written. /// \param[in] options The WriteOptions to be used to write this message. @@ -520,12 +689,21 @@ class ServerAsyncWriterInterface : public ServerAsyncStreamingInterface, const Status& status, void* tag) = 0; }; +/// Async server-side API for doing server streaming RPCs, +/// where the outgoing message stream from the server has messages of type \a W. template <class W> class ServerAsyncWriter final : public ServerAsyncWriterInterface<W> { public: explicit ServerAsyncWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} + /// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics. + /// + /// Implicit input parameter: + /// - 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_); @@ -559,6 +737,13 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface<W> { call_.PerformOps(&write_ops_); } + /// See the \a ServerAsyncWriterInterface.WriteAndFinish method for semantics. + /// + /// Implicit input parameter: + /// - the \a ServerContext associated with this call is used + /// for sending trailing (and initial) metadata to the client. + /// + /// Note: \a status must have an OK code. void WriteAndFinish(const W& msg, WriteOptions options, const Status& status, void* tag) override { write_ops_.set_output_tag(tag); @@ -569,6 +754,14 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface<W> { call_.PerformOps(&write_ops_); } + /// See the \a ServerAsyncWriterInterface.Finish method for semantics. + /// + /// Implicit input parameter: + /// - the \a ServerContext associated with this call is used for sending + /// trailing (and initial if not already sent) metadata to the client. + /// + /// Note: there are no restrictions are the code of + /// \a status,it may be non-OK void Finish(const Status& status, void* tag) override { finish_ops_.set_output_tag(tag); EnsureInitialMetadataSent(&finish_ops_); @@ -606,11 +799,30 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface, public AsyncWriterInterface<W>, public AsyncReaderInterface<R> { public: + /// Indicate that the stream is to be finished with a certain status code. + /// Request notification for when the server has sent the appropriate + /// signals to the client to end the call. + /// 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 \a + /// AsyncReaderInterface::Read operation + /// with a non-ok result (e.g., cq->Next(&read_tag, &ok) filled in 'ok' + /// with '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), response message, and status, or if some + /// failure occurred when trying to do so. + /// + /// \param[in] tag Tag identifying this request. + /// \param[in] status To be sent to the client as the result of this call. virtual void Finish(const Status& status, void* tag) = 0; /// Request the writing of \a msg and coalesce it with trailing metadata which - /// contains \a status, using WriteOptions options with identifying tag \a - /// tag. + /// contains \a status, using WriteOptions options with + /// identifying tag \a tag. /// /// WriteAndFinish is equivalent of performing WriteLast and Finish in a /// single step. @@ -623,6 +835,10 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface, const Status& status, void* tag) = 0; }; +/// Async server-side API for doing bidirectional streaming RPCs, +/// where the incoming message stream coming from the client has messages of +/// type \a R, and the outgoing message stream coming from the server has +/// messages of type \a W. template <class W, class R> class ServerAsyncReaderWriter final : public ServerAsyncReaderWriterInterface<W, R> { @@ -630,6 +846,13 @@ class ServerAsyncReaderWriter final explicit ServerAsyncReaderWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} + /// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics. + /// + /// Implicit input parameter: + /// - 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_); @@ -667,6 +890,14 @@ class ServerAsyncReaderWriter final call_.PerformOps(&write_ops_); } + /// See the \a ServerAsyncReaderWriterInterface.WriteAndFinish + /// method for semantics. + /// + /// Implicit input parameter: + /// - the \a ServerContext associated with this call is used + /// for sending trailing (and initial) metadata to the client. + /// + /// Note: \a status must have an OK code. void WriteAndFinish(const W& msg, WriteOptions options, const Status& status, void* tag) override { write_ops_.set_output_tag(tag); @@ -677,6 +908,14 @@ class ServerAsyncReaderWriter final call_.PerformOps(&write_ops_); } + /// See the \a ServerAsyncReaderWriterInterface.Finish method for semantics. + /// + /// Implicit input parameter: + /// - the \a ServerContext associated with this call is used for sending + /// trailing (and initial if not already sent) metadata to the client. + /// + /// Note: there are no restrictions are the code of \a status, + /// it may be non-OK void Finish(const Status& status, void* tag) override { finish_ops_.set_output_tag(tag); EnsureInitialMetadataSent(&finish_ops_); 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); diff --git a/include/grpc++/impl/codegen/call.h b/include/grpc++/impl/codegen/call.h index 9fe2bbb75e..bbd0fc2dc8 100644 --- a/include/grpc++/impl/codegen/call.h +++ b/include/grpc++/impl/codegen/call.h @@ -634,10 +634,10 @@ class SneakyCallOpSet : public CallOpSet<Op1, Op2, Op3, Op4, Op5, Op6> { } }; -// Straightforward wrapping of the C call object +/// Straightforward wrapping of the C call object class Call final { public: - /* call is owned by the caller */ + /** call is owned by the caller */ Call(grpc_call* call, CallHook* call_hook, CompletionQueue* cq) : call_hook_(call_hook), cq_(cq), diff --git a/include/grpc++/impl/codegen/call_hook.h b/include/grpc++/impl/codegen/call_hook.h index 6a8258233d..85a5f86ab7 100644 --- a/include/grpc++/impl/codegen/call_hook.h +++ b/include/grpc++/impl/codegen/call_hook.h @@ -39,7 +39,8 @@ namespace grpc { class CallOpSetInterface; class Call; -/// Channel and Server implement this to allow them to hook performing ops +/// This is an interface that Channel and Server implement to allow them to hook +/// performing ops. class CallHook { public: virtual ~CallHook() {} diff --git a/include/grpc++/impl/codegen/client_context.h b/include/grpc++/impl/codegen/client_context.h index 3c50e6ba9d..b1b9be0fe2 100644 --- a/include/grpc++/impl/codegen/client_context.h +++ b/include/grpc++/impl/codegen/client_context.h @@ -151,6 +151,20 @@ namespace testing { class InteropClientContextInspector; } // namespace testing +/// A ClientContext allows the person implementing a service client to: +/// +/// - Add custom metadata key-value pairs that will propagated to the server +/// side. +/// - Control call settings such as compression and authentication. +/// - Initial and trailing metadata coming from the server. +/// - Get performance metrics (ie, census). +/// +/// Context settings are only relevant to the call they are invoked with, that +/// is to say, they aren't sticky. Some of these settings, such as the +/// compression options, can be made persistant at channel construction time +/// (see \a grpc::CreateCustomChannel). +/// +/// \warning ClientContext instances should \em not be reused across rpcs. class ClientContext { public: ClientContext(); @@ -178,9 +192,8 @@ class ClientContext { /// /// \param meta_key The metadata key. If \a meta_value is binary data, it must /// end in "-bin". - /// \param meta_value The metadata value. If its value is binary, it must be - /// base64-encoding (see https://tools.ietf.org/html/rfc4648#section-4) and \a - /// meta_key must end in "-bin". + /// \param meta_value The metadata value. If its value is binary, the key name + /// must end in "-bin". void AddMetadata(const grpc::string& meta_key, const grpc::string& meta_value); @@ -222,13 +235,24 @@ class ClientContext { deadline_ = deadline_tp.raw_time(); } - /// EXPERIMENTAL: Set this request to be idempotent + /// EXPERIMENTAL: Indicate that this request is idempotent. + /// By default, RPCs are assumed to <i>not</i> be idempotent. + /// + /// If true, the gRPC library assumes that it's safe to initiate + /// this RPC multiple times. void set_idempotent(bool idempotent) { idempotent_ = idempotent; } - /// EXPERIMENTAL: Set this request to be cacheable + /// EXPERIMENTAL: Set this request to be cacheable. + /// If set, grpc is free to use the HTTP GET verb for sending the request, + /// with the possibility of receiving a cached respone. void set_cacheable(bool cacheable) { cacheable_ = cacheable; } - /// EXPERIMENTAL: Trigger wait-for-ready or not on this request + /// EXPERIMENTAL: Trigger wait-for-ready or not on this request. + /// See https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md. + /// If set, if an RPC is made when a channel's connectivity state is + /// TRANSIENT_FAILURE or CONNECTING, the call will not "fail fast", + /// and the channel will wait until the channel is READY before making the + /// call. void set_wait_for_ready(bool wait_for_ready) { wait_for_ready_ = wait_for_ready; wait_for_ready_explicitly_set_ = true; @@ -325,8 +349,8 @@ class ClientContext { }; static void SetGlobalCallbacks(GlobalCallbacks* callbacks); - // Should be used for framework-level extensions only. - // Applications never need to call this method. + /// Should be used for framework-level extensions only. + /// Applications never need to call this method. grpc_call* c_call() { return call_; } private: diff --git a/include/grpc++/impl/codegen/client_unary_call.h b/include/grpc++/impl/codegen/client_unary_call.h index 4bf35ae778..b923498db8 100644 --- a/include/grpc++/impl/codegen/client_unary_call.h +++ b/include/grpc++/impl/codegen/client_unary_call.h @@ -47,7 +47,7 @@ class ClientContext; class CompletionQueue; class RpcMethod; -// Wrapper that performs a blocking unary call +/// Wrapper that performs a blocking unary call template <class InputMessage, class OutputMessage> Status BlockingUnaryCall(ChannelInterface* channel, const RpcMethod& method, ClientContext* context, const InputMessage& request, diff --git a/include/grpc++/impl/codegen/completion_queue.h b/include/grpc++/impl/codegen/completion_queue.h index c8ab726b0f..57333d7158 100644 --- a/include/grpc++/impl/codegen/completion_queue.h +++ b/include/grpc++/impl/codegen/completion_queue.h @@ -159,7 +159,8 @@ class CompletionQueue : private GrpcLibraryCodegen { /// will start to return false and \a AsyncNext will return \a /// NextStatus::SHUTDOWN. Only once either one of these methods does that /// (that is, once the queue has been \em drained) can an instance of this - /// class be destroyed. + /// class be destroyed. Also note that applications must ensure that + /// no work is enqueued on this completion queue after this method is called. void Shutdown(); /// Returns a \em raw pointer to the underlying \a grpc_completion_queue diff --git a/include/grpc++/impl/codegen/completion_queue_tag.h b/include/grpc++/impl/codegen/completion_queue_tag.h index 19a08500cf..0affc818e8 100644 --- a/include/grpc++/impl/codegen/completion_queue_tag.h +++ b/include/grpc++/impl/codegen/completion_queue_tag.h @@ -40,10 +40,10 @@ namespace grpc { class CompletionQueueTag { public: virtual ~CompletionQueueTag() {} - // Called prior to returning from Next(), return value is the status of the - // operation (return status is the default thing to do). If this function - // returns false, the tag is dropped and not returned from the completion - // queue + /// Called prior to returning from Next(), return value is the status of the + /// operation (return status is the default thing to do). If this function + /// returns false, the tag is dropped and not returned from the completion + /// queue virtual bool FinalizeResult(void** tag, bool* status) = 0; }; diff --git a/include/grpc++/impl/codegen/config.h b/include/grpc++/impl/codegen/config.h index a43bf65f91..79352eee3c 100644 --- a/include/grpc++/impl/codegen/config.h +++ b/include/grpc++/impl/codegen/config.h @@ -39,9 +39,9 @@ #define GRPC_CUSTOM_STRING std::string #endif -// The following macros are deprecated and appear only for users -// with PB files generated using gRPC 1.0.x plugins. They should -// not be used in new code +/// The following macros are deprecated and appear only for users +/// with PB files generated using gRPC 1.0.x plugins. They should +/// not be used in new code #define GRPC_OVERRIDE override // deprecated #define GRPC_FINAL final // deprecated diff --git a/include/grpc++/impl/codegen/method_handler_impl.h b/include/grpc++/impl/codegen/method_handler_impl.h index 83b569ce74..8dfaf5883c 100644 --- a/include/grpc++/impl/codegen/method_handler_impl.h +++ b/include/grpc++/impl/codegen/method_handler_impl.h @@ -40,7 +40,7 @@ namespace grpc { -// A wrapper class of an application provided rpc method handler. +/// A wrapper class of an application provided rpc method handler. template <class ServiceType, class RequestType, class ResponseType> class RpcMethodHandler : public MethodHandler { public: @@ -77,7 +77,7 @@ class RpcMethodHandler : public MethodHandler { } private: - // Application provided rpc handler function. + /// Application provided rpc handler function. std::function<Status(ServiceType*, ServerContext*, const RequestType*, ResponseType*)> func_; @@ -85,7 +85,7 @@ class RpcMethodHandler : public MethodHandler { ServiceType* service_; }; -// A wrapper class of an application provided client streaming handler. +/// A wrapper class of an application provided client streaming handler. template <class ServiceType, class RequestType, class ResponseType> class ClientStreamingHandler : public MethodHandler { public: @@ -125,7 +125,7 @@ class ClientStreamingHandler : public MethodHandler { ServiceType* service_; }; -// A wrapper class of an application provided server streaming handler. +/// A wrapper class of an application provided server streaming handler. template <class ServiceType, class RequestType, class ResponseType> class ServerStreamingHandler : public MethodHandler { public: @@ -166,13 +166,13 @@ class ServerStreamingHandler : public MethodHandler { ServiceType* service_; }; -// A wrapper class of an application provided bidi-streaming handler. -// This also applies to server-streamed implementation of a unary method -// with the additional requirement that such methods must have done a -// write for status to be ok -// Since this is used by more than 1 class, the service is not passed in. -// Instead, it is expected to be an implicitly-captured argument of func -// (through bind or something along those lines) +/// A wrapper class of an application provided bidi-streaming handler. +/// This also applies to server-streamed implementation of a unary method +/// with the additional requirement that such methods must have done a +/// write for status to be ok +/// Since this is used by more than 1 class, the service is not passed in. +/// Instead, it is expected to be an implicitly-captured argument of func +/// (through bind or something along those lines) template <class Streamer, bool WriteNeeded> class TemplatedBidiStreamingHandler : public MethodHandler { public: @@ -249,7 +249,7 @@ class SplitServerStreamingHandler ServerSplitStreamer<RequestType, ResponseType>, false>(func) {} }; -// Handle unknown method by returning UNIMPLEMENTED error. +/// Handle unknown method by returning UNIMPLEMENTED error. class UnknownMethodHandler : public MethodHandler { public: template <class T> diff --git a/include/grpc++/impl/codegen/rpc_method.h b/include/grpc++/impl/codegen/rpc_method.h index 4897428074..ca7527507c 100644 --- a/include/grpc++/impl/codegen/rpc_method.h +++ b/include/grpc++/impl/codegen/rpc_method.h @@ -40,6 +40,7 @@ namespace grpc { +/// Descriptor of an RPC method class RpcMethod { public: enum RpcType { diff --git a/include/grpc++/impl/codegen/rpc_service_method.h b/include/grpc++/impl/codegen/rpc_service_method.h index eb8f9a1096..96bb739c99 100644 --- a/include/grpc++/impl/codegen/rpc_service_method.h +++ b/include/grpc++/impl/codegen/rpc_service_method.h @@ -52,7 +52,7 @@ namespace grpc { class ServerContext; class StreamContextInterface; -// Base class for running an RPC handler. +/// Base class for running an RPC handler. class MethodHandler { public: virtual ~MethodHandler() {} @@ -67,17 +67,17 @@ class MethodHandler { virtual void RunHandler(const HandlerParameter& param) = 0; }; -// Server side rpc method class +/// Server side rpc method class class RpcServiceMethod : public RpcMethod { public: - // Takes ownership of the handler + /// Takes ownership of the handler RpcServiceMethod(const char* name, RpcMethod::RpcType type, MethodHandler* handler) : RpcMethod(name, type), server_tag_(nullptr), handler_(handler) {} void set_server_tag(void* tag) { server_tag_ = tag; } void* server_tag() const { return server_tag_; } - // if MethodHandler is nullptr, then this is an async method + /// if MethodHandler is nullptr, then this is an async method MethodHandler* handler() const { return handler_.get(); } void ResetHandler() { handler_.reset(); } void SetHandler(MethodHandler* handler) { handler_.reset(handler); } diff --git a/include/grpc++/impl/codegen/security/auth_context.h b/include/grpc++/impl/codegen/security/auth_context.h index 75f2482346..e83877bcaf 100644 --- a/include/grpc++/impl/codegen/security/auth_context.h +++ b/include/grpc++/impl/codegen/security/auth_context.h @@ -99,7 +99,7 @@ class AuthContext { virtual AuthPropertyIterator begin() const = 0; virtual AuthPropertyIterator end() const = 0; - // Mutation functions: should only be used by an AuthMetadataProcessor. + /// Mutation functions: should only be used by an AuthMetadataProcessor. virtual void AddProperty(const grpc::string& key, const grpc::string_ref& value) = 0; virtual bool SetPeerIdentityPropertyName(const grpc::string& name) = 0; diff --git a/include/grpc++/impl/codegen/server_context.h b/include/grpc++/impl/codegen/server_context.h index ada304d571..48967c2e68 100644 --- a/include/grpc++/impl/codegen/server_context.h +++ b/include/grpc++/impl/codegen/server_context.h @@ -91,63 +91,128 @@ class InteropServerContextInspector; class ServerContextTestSpouse; } // namespace testing -// Interface of server side rpc context. +/// A ServerContext allows the person implementing a service handler to: +/// +/// - Add custom initial and trailing metadata key-value pairs that will +/// propagated to the client side. +/// - Control call settings such as compression and authentication. +/// - Access metadata coming from the client. +/// - Get performance metrics (ie, census). +/// +/// Context settings are only relevant to the call handler they are supplied to, +/// that is to say, they aren't sticky across multiple calls. Some of these +/// settings, such as the compression options, can be made persistant at server +/// construction time by specifying the approriate \a ChannelArguments +/// to a \a grpc::ServerBuilder, via \a ServerBuilder::AddChannelArgument. +/// +/// \warning ServerContext instances should \em not be reused across rpcs. class ServerContext { public: ServerContext(); // for async calls ~ServerContext(); + /// Return the deadline for the server call. std::chrono::system_clock::time_point deadline() const { return Timespec2Timepoint(deadline_); } + /// Return a \a gpr_timespec representation of the server call's deadline. gpr_timespec raw_deadline() const { return deadline_; } + /// Add the (\a meta_key, \a meta_value) pair to the initial metadata + /// associated with a server call. These are made available at the client side + /// by the \a grpc::ClientContext::GetServerInitialMetadata() method. + /// + /// \warning This method should only be called before sending initial metadata + /// to the client (which can happen explicitly, or implicitly when sending a + /// a response message or status to the client). + /// + /// \param meta_key The metadata key. If \a meta_value is binary data, it must + /// end in "-bin". + /// \param meta_value The metadata value. If its value is binary, the key name + /// must end in "-bin". void AddInitialMetadata(const grpc::string& key, const grpc::string& value); + + /// Add the (\a meta_key, \a meta_value) pair to the initial metadata + /// associated with a server call. These are made available at the client + /// side by the \a grpc::ClientContext::GetServerTrailingMetadata() method. + /// + /// \warning This method should only be called before sending trailing + /// metadata to the client (which happens when the call is finished and a + /// status is sent to the client). + /// + /// \param meta_key The metadata key. If \a meta_value is binary data, + /// it must end in "-bin". + /// \param meta_value The metadata value. If its value is binary, the key name + /// must end in "-bin". void AddTrailingMetadata(const grpc::string& key, const grpc::string& value); - // IsCancelled is always safe to call when using sync API - // When using async API, it is only safe to call IsCancelled after - // the AsyncNotifyWhenDone tag has been delivered + /// IsCancelled is always safe to call when using sync API. + /// When using async API, it is only safe to call IsCancelled after + /// the AsyncNotifyWhenDone tag has been delivered. bool IsCancelled() const; - // Cancel the Call from the server. This is a best-effort API and depending on - // when it is called, the RPC may still appear successful to the client. - // For example, if TryCancel() is called on a separate thread, it might race - // with the server handler which might return success to the client before - // TryCancel() was even started by the thread. - // - // It is the caller's responsibility to prevent such races and ensure that if - // TryCancel() is called, the serverhandler must return Status::CANCELLED. The - // only exception is that if the serverhandler is already returning an error - // status code, it is ok to not return Status::CANCELLED even if TryCancel() - // was called. + /// Cancel the Call from the server. This is a best-effort API and + /// depending on when it is called, the RPC may still appear successful to + /// the client. + /// For example, if TryCancel() is called on a separate thread, it might race + /// with the server handler which might return success to the client before + /// TryCancel() was even started by the thread. + /// + /// It is the caller's responsibility to prevent such races and ensure that if + /// TryCancel() is called, the serverhandler must return Status::CANCELLED. + /// The only exception is that if the serverhandler is already returning an + /// error status code, it is ok to not return Status::CANCELLED even if + /// TryCancel() was called. void TryCancel() const; + /// Return a collection of initial metadata key-value pairs sent from the + /// client. Note that keys may happen more than + /// once (ie, a \a std::multimap is returned). + /// + /// It is safe to use this method after initial metadata has been received, + /// Calls always begin with the client sending initial metadata, so this is + /// safe to access as soon as the call has begun on the server side. + /// + /// \return A multimap of initial metadata key-value pairs from the server. const std::multimap<grpc::string_ref, grpc::string_ref>& client_metadata() const { return *client_metadata_.map(); } + /// Return the compression algorithm to be used by the server call. grpc_compression_level compression_level() const { return compression_level_; } + /// Set \a algorithm to be the compression algorithm used for the server call. + /// + /// \param algorithm The compression algorithm used for the server call. void set_compression_level(grpc_compression_level level) { compression_level_set_ = true; compression_level_ = level; } + /// Return a bool indicating whether the compression level for this call + /// has been set (either implicitly or through a previous call to + /// \a set_compression_level. bool compression_level_set() const { return compression_level_set_; } + /// Return the compression algorithm to be used by the server call. grpc_compression_algorithm compression_algorithm() const { return compression_algorithm_; } + /// Set \a algorithm to be the compression algorithm used for the server call. + /// + /// \param algorithm The compression algorithm used for the server call. void set_compression_algorithm(grpc_compression_algorithm algorithm); - // Set the load reporting costs in \a cost_data for the call. + /// Set the load reporting costs in \a cost_data for the call. void SetLoadReportingCosts(const std::vector<grpc::string>& cost_data); + /// Return the authentication context for this server call. + /// + /// \see grpc::AuthContext. std::shared_ptr<const AuthContext> auth_context() const { if (auth_context_.get() == nullptr) { auth_context_ = CreateAuthContext(call_); @@ -155,24 +220,25 @@ class ServerContext { return auth_context_; } - // Return the peer uri in a string. - // WARNING: this value is never authenticated or subject to any security - // related code. It must not be used for any authentication related - // functionality. Instead, use auth_context. + /// Return the peer uri in a string. + /// WARNING: this value is never authenticated or subject to any security + /// related code. It must not be used for any authentication related + /// functionality. Instead, use auth_context. grpc::string peer() const; + /// Get the census context associated with this server call. const struct census_context* census_context() const; - // Async only. Has to be called before the rpc starts. - // Returns the tag in completion queue when the rpc finishes. - // IsCancelled() can then be called to check whether the rpc was cancelled. + /// Async only. Has to be called before the rpc starts. + /// Returns the tag in completion queue when the rpc finishes. + /// IsCancelled() can then be called to check whether the rpc was cancelled. void AsyncNotifyWhenDone(void* tag) { has_notify_when_done_tag_ = true; async_notify_when_done_tag_ = tag; } - // Should be used for framework-level extensions only. - // Applications never need to call this method. + /// Should be used for framework-level extensions only. + /// Applications never need to call this method. grpc_call* c_call() { return call_; } private: @@ -205,14 +271,14 @@ class ServerContext { friend class UnknownMethodHandler; friend class ::grpc::ClientContext; - // Prevent copying. + /// Prevent copying. ServerContext(const ServerContext&); ServerContext& operator=(const ServerContext&); class CompletionOp; void BeginCompletionOp(Call* call); - // Return the tag queued by BeginCompletionOp() + /// Return the tag queued by BeginCompletionOp() CompletionQueueTag* GetCompletionOpTag(); ServerContext(gpr_timespec deadline, grpc_metadata_array* arr); diff --git a/include/grpc++/impl/codegen/service_type.h b/include/grpc++/impl/codegen/service_type.h index bd65ea009e..b88019164d 100644 --- a/include/grpc++/impl/codegen/service_type.h +++ b/include/grpc++/impl/codegen/service_type.h @@ -54,6 +54,12 @@ class ServerAsyncStreamingInterface { public: virtual ~ServerAsyncStreamingInterface() {} + /// Request notification of the sending of initial metadata to the client. + /// 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 SendInitialMetadata(void* tag) = 0; private: @@ -61,6 +67,7 @@ class ServerAsyncStreamingInterface { virtual void BindCall(Call* call) = 0; }; +/// Desriptor of an RPC service and its various RPC methods class Service { public: Service() : server_(nullptr) {} @@ -155,7 +162,7 @@ class Service { // From the server's point of view, streamed unary is a special // case of BIDI_STREAMING that has 1 read and 1 write, in that order, // and split server-side streaming is BIDI_STREAMING with 1 read and - // any number of writes, in that order + // any number of writes, in that order. methods_[index]->SetMethodType(::grpc::RpcMethod::BIDI_STREAMING); } diff --git a/include/grpc++/impl/codegen/status_code_enum.h b/include/grpc++/impl/codegen/status_code_enum.h index 9a90a18e2a..c3d27fa3b0 100644 --- a/include/grpc++/impl/codegen/status_code_enum.h +++ b/include/grpc++/impl/codegen/status_code_enum.h @@ -136,6 +136,11 @@ enum StatusCode { /// The service is currently unavailable. This is a most likely a transient /// condition and may be corrected by retrying with a backoff. /// + /// \warning Although data MIGHT not have been transmitted when this + /// status occurs, there is NOT A GUARANTEE that the server has not seen + /// anything. So in general it is unsafe to retry on this status code + /// if the call is non-idempotent. + /// /// See litmus test above for deciding between FAILED_PRECONDITION, ABORTED, /// and UNAVAILABLE. UNAVAILABLE = 14, diff --git a/include/grpc++/impl/codegen/string_ref.h b/include/grpc++/impl/codegen/string_ref.h index 003793823c..4ed11b1b6c 100644 --- a/include/grpc++/impl/codegen/string_ref.h +++ b/include/grpc++/impl/codegen/string_ref.h @@ -55,14 +55,14 @@ namespace grpc { /// compatibility. class string_ref { public: - // types + /// types typedef const char* const_iterator; typedef std::reverse_iterator<const_iterator> const_reverse_iterator; - // constants + /// constants const static size_t npos; - // construct/copy. + /// construct/copy. string_ref() : data_(nullptr), length_(0) {} string_ref(const string_ref& other) : data_(other.data_), length_(other.length_) {} @@ -76,7 +76,7 @@ class string_ref { string_ref(const char* s, size_t l) : data_(s), length_(l) {} string_ref(const grpc::string& s) : data_(s.data()), length_(s.length()) {} - // iterators + /// iterators const_iterator begin() const { return data_; } const_iterator end() const { return data_ + length_; } const_iterator cbegin() const { return data_; } @@ -94,16 +94,16 @@ class string_ref { return const_reverse_iterator(begin()); } - // capacity + /// capacity size_t size() const { return length_; } size_t length() const { return length_; } size_t max_size() const { return length_; } bool empty() const { return length_ == 0; } - // element access + /// element access const char* data() const { return data_; } - // string operations + /// string operations int compare(string_ref x) const { size_t min_size = length_ < x.length_ ? length_ : x.length_; int r = memcmp(data_, x.data_, min_size); @@ -144,7 +144,7 @@ class string_ref { size_t length_; }; -// Comparison operators +/// Comparison operators inline bool operator==(string_ref x, string_ref y) { return x.compare(y) == 0; } inline bool operator!=(string_ref x, string_ref y) { return x.compare(y) != 0; } inline bool operator<(string_ref x, string_ref y) { return x.compare(y) < 0; } diff --git a/include/grpc++/impl/codegen/stub_options.h b/include/grpc++/impl/codegen/stub_options.h index 8e966a8dbf..41aef19ab0 100644 --- a/include/grpc++/impl/codegen/stub_options.h +++ b/include/grpc++/impl/codegen/stub_options.h @@ -36,6 +36,7 @@ namespace grpc { +/// Useful interface for generated stubs class StubOptions {}; } // namespace grpc diff --git a/include/grpc++/impl/codegen/sync_stream.h b/include/grpc++/impl/codegen/sync_stream.h index a010924cef..db9048d7e5 100644 --- a/include/grpc++/impl/codegen/sync_stream.h +++ b/include/grpc++/impl/codegen/sync_stream.h @@ -50,16 +50,30 @@ class ClientStreamingInterface { public: virtual ~ClientStreamingInterface() {} - /// Wait until the stream finishes, and return the final status. When the - /// client side declares it has no more message to send, either implicitly or - /// by calling \a WritesDone(), it needs to make sure there is no more message - /// to be received from the server, either implicitly or by getting a false - /// from a \a Read(). + /// Block waiting until the stream finishes and a final status of the call is + /// available. + /// + /// It is appropriate to call this method when both: + /// * the calling code (client-side) has no more message to send + /// (this can be declared implicitly by calling this method, or + /// explicitly through an earlier call to <i>WritesDone</i> method of the + /// class in use, e.g. \a ClientWriterInterface::WritesDone or + /// \a ClientReaderWriterInterface::WritesDone). + /// * there are no more messages to be received from the server (which can + /// be known implicitly, or explicitly from an earlier call to \a + /// ReaderInterface::Read that returned "false"). /// /// This function will return either: - /// - when all incoming messages have been read and the server has returned + /// - when all incoming messages have been read and the server has + /// returned status. + /// - when the server has returned a non-OK status. + /// - OR when the call failed for some reason and the library generated a /// status. - /// - OR when the server has returned a non-OK status. + /// + /// Return values: + /// - \a Status contains the status code, message and details for the call + /// - the \a ClientContext associated with this call is updated with + /// possible trailing metadata sent from the server. virtual Status Finish() = 0; }; @@ -68,7 +82,12 @@ class ServerStreamingInterface { public: virtual ~ServerStreamingInterface() {} - /// Blocking send initial metadata to client. + /// Block to send initial metadata to client. + /// This call is optional, but if it is used, it cannot be used concurrently + /// with or after the \a Finish method. + /// + /// The initial metadata that will be sent to the client will be + /// taken from the \a ServerContext associated with the call. virtual void SendInitialMetadata() = 0; }; @@ -78,10 +97,11 @@ class ReaderInterface { public: virtual ~ReaderInterface() {} - /// Upper bound on the next message size available for reading on this stream + /// Get an upper bound on the next message size available for reading on this + /// stream. virtual bool NextMessageSize(uint32_t* sz) = 0; - /// Blocking read a message and parse to \a msg. Returns \a true on success. + /// Block to read a message and parse to \a msg. Returns \a true on success. /// This is thread-safe with respect to \a Write or \WritesDone methods on /// the same stream. It should not be called concurrently with another \a /// Read on the same stream as the order of delivery will not be defined. @@ -100,8 +120,8 @@ class WriterInterface { public: virtual ~WriterInterface() {} - /// Blocking write \a msg to the stream with WriteOptions \a options. - /// This is thread-safe with respect to \a Read + /// Block to write \a msg to the stream with WriteOptions \a options. + /// This is thread-safe with respect to \a ReaderInterface::Read /// /// \param msg The message to be written to the stream. /// \param options The WriteOptions affecting the write operation. @@ -109,8 +129,8 @@ class WriterInterface { /// \return \a true on success, \a false when the stream has been closed. virtual bool Write(const W& msg, WriteOptions options) = 0; - /// Blocking write \a msg to the stream with default write options. - /// This is thread-safe with respect to \a Read + /// Block to write \a msg to the stream with default write options. + /// This is thread-safe with respect to \a ReaderInterface::Read /// /// \param msg The message to be written to the stream. /// @@ -122,12 +142,12 @@ class WriterInterface { /// /// For client, WriteLast is equivalent of performing Write and WritesDone in /// a single step. \a msg and trailing metadata are coalesced and sent on wire - /// by calling this function. - /// For server, WriteLast buffers the \a msg. The writing of \a msg is held - /// until the service handler returns, where \a msg and trailing metadata are - /// coalesced and sent on wire. Note that WriteLast can only buffer \a msg up - /// to the flow control window size. If \a msg size is larger than the window - /// size, it will be sent on wire without buffering. + /// by calling this function. For server, WriteLast buffers the \a msg. + /// The writing of \a msg is held until the service handler returns, + /// where \a msg and trailing metadata are coalesced and sent on wire. + /// Note that WriteLast can only buffer \a msg up to the flow control window + /// size. If \a msg size is larger than the window size, it will be sent on + /// wire without buffering. /// /// \param[in] msg The message to be written to the stream. /// \param[in] options The WriteOptions to be used to write this message. @@ -141,17 +161,22 @@ template <class R> class ClientReaderInterface : public ClientStreamingInterface, public ReaderInterface<R> { public: - /// Blocking wait for initial metadata from server. The received metadata + /// Block to wait for initial metadata from server. The received metadata /// can only be accessed after this call returns. Should only be called before /// the first read. Calling this method is optional, and if it is not called /// the metadata will be available in ClientContext after the first read. virtual void WaitForInitialMetadata() = 0; }; +/// Synchronous (blocking) client-side API for doing server-streaming RPCs, +/// where the stream of messages coming from the server has messages +/// of type \a R. template <class R> class ClientReader final : public ClientReaderInterface<R> { public: - /// Blocking create a stream and write the first request out. + /// Block to create a stream and write the initial metadata and \a request + /// 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> ClientReader(ChannelInterface* channel, const RpcMethod& method, ClientContext* context, const W& request) @@ -172,6 +197,13 @@ class ClientReader final : public ClientReaderInterface<R> { cq_.Pluck(&ops); } + /// See the \a ClientStreamingInterface.WaitForInitialMetadata method for + /// semantics. + /// + // Side effect: + /// Once complete, the initial metadata read from + /// the server will be accessable through the \a ClientContext used to + /// construct this object. void WaitForInitialMetadata() override { GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_); @@ -186,6 +218,11 @@ class ClientReader final : public ClientReaderInterface<R> { return true; } + /// See the \a ReaderInterface.Read method for semantics. + /// Side effect: + /// This also receives initial metadata from the server, if not + /// already received (if initial metadata is received, it can be then + /// accessed through the \a ClientContext associated with this call). bool Read(R* msg) override { CallOpSet<CallOpRecvInitialMetadata, CallOpRecvMessage<R>> ops; if (!context_->initial_metadata_received_) { @@ -196,6 +233,11 @@ class ClientReader final : public ClientReaderInterface<R> { return cq_.Pluck(&ops) && ops.got_message; } + /// See the \a ClientStreamingInterface.Finish method for semantics. + /// + /// Side effect: + /// The \a ClientContext associated with this call is updated with + /// possible metadata received from the server. Status Finish() override { CallOpSet<CallOpClientRecvStatus> ops; Status status; @@ -211,23 +253,31 @@ class ClientReader final : public ClientReaderInterface<R> { Call call_; }; -/// Client-side interface for streaming writes of message of type \a W. +/// Client-side interface for streaming writes of message type \a W. template <class W> class ClientWriterInterface : public ClientStreamingInterface, public WriterInterface<W> { public: - /// Half close writing from the client. - /// Block until currently-pending writes are completed. - /// Thread safe with respect to \a Read operations only + /// Half close writing from the client. (signal that the stream of messages + /// coming from the clinet is complete). + /// Blocks until currently-pending writes are completed. + /// Thread safe with respect to \a ReaderInterface::Read operations only /// /// \return Whether the writes were successful. virtual bool WritesDone() = 0; }; +/// Synchronous (blocking) client-side API for doing client-streaming RPCs, +/// where the outgoing message stream coming from the client has messages of +/// type \a W. template <class W> class ClientWriter : public ClientWriterInterface<W> { public: - /// Blocking create a stream. + /// Block to create a stream (i.e. send request headers and other initial + /// metadata to the server). Note that \a context will be used to fill + /// in custom initial metadata. \a response will be filled in with the + /// single expected response message from the server upon a successful + /// call to the \a Finish method of this instance. template <class R> ClientWriter(ChannelInterface* channel, const RpcMethod& method, ClientContext* context, R* response) @@ -248,6 +298,12 @@ class ClientWriter : public ClientWriterInterface<W> { } } + /// See the \a ClientStreamingInterface.WaitForInitialMetadata method for + /// semantics. + /// + // Side effect: + /// Once complete, the initial metadata read from the server will be + /// accessable through the \a ClientContext used to construct this object. void WaitForInitialMetadata() { GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_); @@ -257,6 +313,12 @@ class ClientWriter : public ClientWriterInterface<W> { cq_.Pluck(&ops); // status ignored } + /// See the WriterInterface.Write(const W& msg, WriteOptions options) method + /// for semantics. + /// + /// Side effect: + /// Also sends initial metadata if not already sent (using the + /// \a ClientContext associated with this call). using WriterInterface<W>::Write; bool Write(const W& msg, WriteOptions options) override { CallOpSet<CallOpSendInitialMetadata, CallOpSendMessage, @@ -287,7 +349,12 @@ class ClientWriter : public ClientWriterInterface<W> { return cq_.Pluck(&ops); } - /// Read the final response and wait for the final status. + /// See the ClientStreamingInterface.Finish method for semantics. + /// Side effects: + /// - Also receives initial metadata if not already received. + /// - Attempts to fill in the \a response parameter passed + /// to the constructor of this instance with the response + /// message from the server. Status Finish() override { Status status; if (!context_->initial_metadata_received_) { @@ -308,29 +375,39 @@ class ClientWriter : public ClientWriterInterface<W> { Call call_; }; -/// Client-side interface for bi-directional streaming. +/// Client-side interface for bi-directional streaming with +/// client-to-server stream messages of type \a W and +/// server-to-client stream messages of type \a R. template <class W, class R> class ClientReaderWriterInterface : public ClientStreamingInterface, public WriterInterface<W>, public ReaderInterface<R> { public: - /// Blocking wait for initial metadata from server. The received metadata + /// Block to wait for initial metadata from server. The received metadata /// can only be accessed after this call returns. Should only be called before /// the first read. Calling this method is optional, and if it is not called /// the metadata will be available in ClientContext after the first read. virtual void WaitForInitialMetadata() = 0; - /// Block until currently-pending writes are completed. - /// Thread-safe with respect to \a Read + /// Half close writing from the client. (signal that the stream of messages + /// coming from the clinet is complete). + /// Blocks until currently-pending writes are completed. + /// Thread-safe with respect to \a ReaderInterface::Read /// /// \return Whether the writes were successful. virtual bool WritesDone() = 0; }; +/// Synchronous (blocking) client-side API for bi-directional streaming RPCs, +/// where the outgoing message stream coming from the client has messages of +/// type \a W, and the incoming messages stream coming from the server has +/// messages of type \a R. template <class W, class R> class ClientReaderWriter final : public ClientReaderWriterInterface<W, R> { public: - /// Blocking create a stream. + /// Block to create a stream and write the initial metadata and \a request + /// out. Note that \a context will be used to fill in custom initial metadata + /// used to send to the server when starting the call. ClientReaderWriter(ChannelInterface* channel, const RpcMethod& method, ClientContext* context) : context_(context), @@ -347,6 +424,12 @@ class ClientReaderWriter final : public ClientReaderWriterInterface<W, R> { } } + /// Block waiting to read initial metadata from the server. + /// This call is optional, but if it is used, it cannot be used concurrently + /// with or after the \a Finish method. + /// + /// Once complete, the initial metadata read from the server will be + /// accessable through the \a ClientContext used to construct this object. void WaitForInitialMetadata() override { GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_); @@ -361,6 +444,10 @@ class ClientReaderWriter final : public ClientReaderWriterInterface<W, R> { return true; } + /// See the \a ReaderInterface.Read method for semantics. + /// Side effect: + /// Also receives initial metadata if not already received (updates the \a + /// ClientContext associated with this call in that case). bool Read(R* msg) override { CallOpSet<CallOpRecvInitialMetadata, CallOpRecvMessage<R>> ops; if (!context_->initial_metadata_received_) { @@ -371,6 +458,11 @@ class ClientReaderWriter final : public ClientReaderWriterInterface<W, R> { return cq_.Pluck(&ops) && ops.got_message; } + /// See the \a WriterInterface.Write method for semantics. + /// + /// Side effect: + /// Also sends initial metadata if not already sent (using the + /// \a ClientContext associated with this call to fill in values). using WriterInterface<W>::Write; bool Write(const W& msg, WriteOptions options) override { CallOpSet<CallOpSendInitialMetadata, CallOpSendMessage, @@ -401,6 +493,11 @@ class ClientReaderWriter final : public ClientReaderWriterInterface<W, R> { return cq_.Pluck(&ops); } + /// See the ClientStreamingInterface.Finish method for semantics. + /// + /// Side effect: + /// - the \a ClientContext associated with this call is updated with + /// possible trailing metadata sent from the server. Status Finish() override { CallOpSet<CallOpRecvInitialMetadata, CallOpClientRecvStatus> ops; if (!context_->initial_metadata_received_) { @@ -424,11 +521,17 @@ template <class R> class ServerReaderInterface : public ServerStreamingInterface, public ReaderInterface<R> {}; +/// Synchronous (blocking) server-side API for doing client-streaming RPCs, +/// where the incoming message stream coming from the client has messages of +/// type \a R. template <class R> class ServerReader final : public ServerReaderInterface<R> { public: ServerReader(Call* call, ServerContext* ctx) : call_(call), ctx_(ctx) {} + /// See the \a ServerStreamingInterface.SendInitialMetadata method + /// for semantics. Note that initial metadata will be affected by the + /// \a ServerContext associated with this call. void SendInitialMetadata() override { GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_); @@ -465,11 +568,18 @@ template <class W> class ServerWriterInterface : public ServerStreamingInterface, public WriterInterface<W> {}; +/// Synchronous (blocking) server-side API for doing for doing a +/// server-streaming RPCs, where the outgoing message stream coming from the +/// server has messages of type \a W. template <class W> class ServerWriter final : public ServerWriterInterface<W> { public: ServerWriter(Call* call, ServerContext* ctx) : call_(call), ctx_(ctx) {} + /// See the \a ServerStreamingInterface.SendInitialMetadata method + /// for semantics. + /// Note that initial metadata will be affected by the + /// \a ServerContext associated with this call. void SendInitialMetadata() override { GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_); @@ -484,6 +594,11 @@ class ServerWriter final : public ServerWriterInterface<W> { call_->cq()->Pluck(&ops); } + /// See the \a WriterInterface.Write method for semantics. + /// + /// Side effect: + /// Also sends initial metadata if not already sent (using the + /// \a ClientContext associated with this call to fill in values). using WriterInterface<W>::Write; bool Write(const W& msg, WriteOptions options) override { if (options.is_last_message()) { @@ -516,7 +631,7 @@ class ServerReaderWriterInterface : public ServerStreamingInterface, public WriterInterface<W>, public ReaderInterface<R> {}; -// Actual implementation of bi-directional streaming +/// Actual implementation of bi-directional streaming namespace internal { template <class W, class R> class ServerReaderWriterBody final { @@ -576,12 +691,18 @@ class ServerReaderWriterBody final { }; } // namespace internal -// class to represent the user API for a bidirectional streaming call +/// Synchronous (blocking) server-side API for a bidirectional +/// streaming call, where the incoming message stream coming from the client has +/// messages of type \a R, and the outgoing message streaming coming from +/// the server has messages of type \a W. template <class W, class R> class ServerReaderWriter final : public ServerReaderWriterInterface<W, R> { public: ServerReaderWriter(Call* call, ServerContext* ctx) : body_(call, ctx) {} + /// See the \a ServerStreamingInterface.SendInitialMetadata method + /// for semantics. Note that initial metadata will be affected by the + /// \a ServerContext associated with this call. void SendInitialMetadata() override { body_.SendInitialMetadata(); } bool NextMessageSize(uint32_t* sz) override { @@ -590,6 +711,11 @@ class ServerReaderWriter final : public ServerReaderWriterInterface<W, R> { bool Read(R* msg) override { return body_.Read(msg); } + /// See the \a WriterInterface.Write(const W& msg, WriteOptions options) + /// method for semantics. + /// Side effect: + /// Also sends initial metadata if not already sent (using the \a + /// ServerContext associated with this call). using WriterInterface<W>::Write; bool Write(const W& msg, WriteOptions options) override { return body_.Write(msg, options); @@ -604,8 +730,7 @@ class ServerReaderWriter final : public ServerReaderWriterInterface<W, R> { /// through a unary call on the client side, but the server responds to it /// as though it were a single-ping-pong streaming call. The server can use /// the \a NextMessageSize method to determine an upper-bound on the size of -/// the message. -/// A key difference relative to streaming: ServerUnaryStreamer +/// the message. A key difference relative to streaming: ServerUnaryStreamer /// must have exactly 1 Read and exactly 1 Write, in that order, to function /// correctly. Otherwise, the RPC is in error. template <class RequestType, class ResponseType> @@ -615,12 +740,27 @@ class ServerUnaryStreamer final ServerUnaryStreamer(Call* call, ServerContext* ctx) : body_(call, ctx), read_done_(false), write_done_(false) {} + /// Block to send initial metadata to client. + /// Implicit input parameter: + /// - the \a ServerContext associated with this call will be used for + /// sending initial metadata. void SendInitialMetadata() override { body_.SendInitialMetadata(); } + /// Get an upper bound on the request message size from the client. bool NextMessageSize(uint32_t* sz) override { return body_.NextMessageSize(sz); } + /// Read a message of type \a R into \a msg. Completion will be notified by \a + /// tag on the associated completion queue. + /// This is thread-safe with respect to \a Write or \a WritesDone methods. It + /// should not be called concurrently with other streaming APIs + /// on the same stream. It is not meaningful to call it concurrently + /// with another \a ReaderInterface::Read on the same stream since reads on + /// the same stream are delivered in order. + /// + /// \param[out] msg Where to eventually store the read message. + /// \param[in] tag The tag identifying the operation. bool Read(RequestType* request) override { if (read_done_) { return false; @@ -629,6 +769,13 @@ class ServerUnaryStreamer final return body_.Read(request); } + /// Block to write \a msg to the stream with WriteOptions \a options. + /// This is thread-safe with respect to \a ReaderInterface::Read + /// + /// \param msg The message to be written to the stream. + /// \param options The WriteOptions affecting the write operation. + /// + /// \return \a true on success, \a false when the stream has been closed. using WriterInterface<ResponseType>::Write; bool Write(const ResponseType& response, WriteOptions options) override { if (write_done_ || !read_done_) { @@ -656,12 +803,27 @@ class ServerSplitStreamer final ServerSplitStreamer(Call* call, ServerContext* ctx) : body_(call, ctx), read_done_(false) {} + /// Block to send initial metadata to client. + /// Implicit input parameter: + /// - the \a ServerContext associated with this call will be used for + /// sending initial metadata. void SendInitialMetadata() override { body_.SendInitialMetadata(); } + /// Get an upper bound on the request message size from the client. bool NextMessageSize(uint32_t* sz) override { return body_.NextMessageSize(sz); } + /// Read a message of type \a R into \a msg. Completion will be notified by \a + /// tag on the associated completion queue. + /// This is thread-safe with respect to \a Write or \a WritesDone methods. It + /// should not be called concurrently with other streaming APIs + /// on the same stream. It is not meaningful to call it concurrently + /// with another \a ReaderInterface::Read on the same stream since reads on + /// the same stream are delivered in order. + /// + /// \param[out] msg Where to eventually store the read message. + /// \param[in] tag The tag identifying the operation. bool Read(RequestType* request) override { if (read_done_) { return false; @@ -670,6 +832,13 @@ class ServerSplitStreamer final return body_.Read(request); } + /// Block to write \a msg to the stream with WriteOptions \a options. + /// This is thread-safe with respect to \a ReaderInterface::Read + /// + /// \param msg The message to be written to the stream. + /// \param options The WriteOptions affecting the write operation. + /// + /// \return \a true on success, \a false when the stream has been closed. using WriterInterface<ResponseType>::Write; bool Write(const ResponseType& response, WriteOptions options) override { return read_done_ && body_.Write(response, options); diff --git a/include/grpc++/impl/codegen/time.h b/include/grpc++/impl/codegen/time.h index e090ece756..81ca7bb3de 100644 --- a/include/grpc++/impl/codegen/time.h +++ b/include/grpc++/impl/codegen/time.h @@ -39,17 +39,16 @@ namespace grpc { -/* If you are trying to use CompletionQueue::AsyncNext with a time class that - isn't either gpr_timespec or std::chrono::system_clock::time_point, you - will most likely be looking at this comment as your compiler will have - fired an error below. In order to fix this issue, you have two potential - solutions: - - 1. Use gpr_timespec or std::chrono::system_clock::time_point instead - 2. Specialize the TimePoint class with whichever time class that you - want to use here. See below for two examples of how to do this. +/** If you are trying to use CompletionQueue::AsyncNext with a time class that + isn't either gpr_timespec or std::chrono::system_clock::time_point, you + will most likely be looking at this comment as your compiler will have + fired an error below. In order to fix this issue, you have two potential + solutions: + + 1. Use gpr_timespec or std::chrono::system_clock::time_point instead + 2. Specialize the TimePoint class with whichever time class that you + want to use here. See below for two examples of how to do this. */ - template <typename T> class TimePoint { public: |