From 41ff2e1ee6afc5373a60edc19b5c477e10a429b2 Mon Sep 17 00:00:00 2001 From: Alexander Polcyn Date: Wed, 10 May 2017 15:19:01 -0700 Subject: [PATCH] address comments, format changes --- include/grpc++/generic/generic_stub.h | 6 +- include/grpc++/impl/codegen/async_stream.h | 86 ++++++------------- .../grpc++/impl/codegen/async_unary_call.h | 58 ++++++------- include/grpc++/impl/codegen/client_context.h | 13 ++- include/grpc++/impl/codegen/server_context.h | 8 +- include/grpc++/impl/codegen/service_type.h | 6 ++ include/grpc++/impl/codegen/sync_stream.h | 35 ++++---- include/grpc++/impl/server_builder_plugin.h | 2 +- include/grpc/impl/codegen/gpr_slice.h | 3 +- include/grpc/impl/codegen/grpc_types.h | 19 ++-- include/grpc/slice.h | 3 +- 11 files changed, 99 insertions(+), 140 deletions(-) diff --git a/include/grpc++/generic/generic_stub.h b/include/grpc++/generic/generic_stub.h index fdd23772043..1478846fc84 100644 --- a/include/grpc++/generic/generic_stub.h +++ b/include/grpc++/generic/generic_stub.h @@ -50,11 +50,11 @@ class GenericStub final { explicit GenericStub(std::shared_ptr channel) : channel_(channel) {} - /// Begin a call to a named method \a method usign \a context. - /// A tag \a tag will be deliever to \a cq when the call has been started + /// Begin a call to a named method \a method using \a context. + /// A tag \a tag will be delivered to \a cq when the call has been started /// (i.e, initial metadata has been sent). /// The return value only indicates whether or not registration of the call - /// succeeded (i.e. the call won't proceed if the return value is 0). + /// succeeded (i.e. the call won't proceed if the return value is nullptr). std::unique_ptr Call( ClientContext* context, const grpc::string& method, CompletionQueue* cq, void* tag); diff --git a/include/grpc++/impl/codegen/async_stream.h b/include/grpc++/impl/codegen/async_stream.h index 5a685cbe554..72fbd9ea796 100644 --- a/include/grpc++/impl/codegen/async_stream.h +++ b/include/grpc++/impl/codegen/async_stream.h @@ -53,7 +53,7 @@ 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; @@ -64,12 +64,14 @@ class ClientAsyncStreamingInterface { /// /// 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 \a - /// WritesDone. - /// * there are no more messages to be received from the server (which can - /// be known implicitly by the calling code, or known explicitly from an - /// earlier call to \a Read that yielded a failed result - /// (e.g. cq->Next(&read_tag, &ok) filled in 'ok' with 'false'. + /// by calling this method, or explicitly through an earlier call to + /// the WritesDone 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 @@ -97,7 +99,7 @@ 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 + /// 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. @@ -119,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. @@ -132,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. @@ -205,7 +207,6 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface { call_.PerformOps(&meta_ops_); } - /// See the \a AsyncReaderInterface.Read method for semantics of this method. void Read(R* msg, void* tag) override { read_ops_.set_output_tag(tag); if (!context_->initial_metadata_received_) { @@ -258,13 +259,13 @@ class ClientAsyncWriterInterface : public ClientAsyncStreamingInterface, public AsyncWriterInterface { public: /// Signal the client is done with the writes (half-close the client stream). - /// Thread-safe with respect to \a Read + /// Thread-safe with respect to \a AsyncReaderInterface::Read /// /// \param[in] tag The tag identifying the operation. virtual void WritesDone(void* tag) = 0; }; -/// Async API to on the client side for doing client-streaming RPCs, +/// 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 ClientAsyncWriter final : public ClientAsyncWriterInterface { @@ -309,8 +310,6 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { call_.PerformOps(&meta_ops_); } - /// See the \a AsyncWriterInterface.Write(const W& msg, void* tag) - /// method for semantics of this method. void Write(const W& msg, void* tag) override { write_ops_.set_output_tag(tag); // TODO(ctiller): don't assert @@ -318,9 +317,6 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { call_.PerformOps(&write_ops_); } - /// See the - /// \a AsyncWriterInterface.Write(const W& msg, WriteOptions options, void* tag) - /// method for semantics of this method. void Write(const W& msg, WriteOptions options, void* tag) override { write_ops_.set_output_tag(tag); if (options.is_last_message()) { @@ -332,8 +328,6 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { call_.PerformOps(&write_ops_); } - /// See the \a ClientAsyncWriterInterface.WritesDone method for semantics of - /// this method. void WritesDone(void* tag) override { write_ops_.set_output_tag(tag); write_ops_.ClientSendClose(); @@ -387,14 +381,14 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface { /// Async client-side interface for bi-directional streaming, /// where the client-to-server message stream has messages of type \a W, -/// abnd the server-to-client message stream has messages of type \a R. +/// and the server-to-client message stream has messages of type \a R. template class ClientAsyncReaderWriterInterface : public ClientAsyncStreamingInterface, public AsyncWriterInterface, public AsyncReaderInterface { public: /// Signal the client is done with the writes (half-close the client stream). - /// Thread-safe with respect to \a Read + /// Thread-safe with respect to \a AsyncReaderInterface::Read /// /// \param[in] tag The tag identifying the operation. virtual void WritesDone(void* tag) = 0; @@ -443,8 +437,6 @@ class ClientAsyncReaderWriter final call_.PerformOps(&meta_ops_); } - /// See \a AsyncReaderInterface.Read method for semantics - /// of this method. void Read(R* msg, void* tag) override { read_ops_.set_output_tag(tag); if (!context_->initial_metadata_received_) { @@ -454,8 +446,6 @@ class ClientAsyncReaderWriter final call_.PerformOps(&read_ops_); } - /// See \a AsyncWriterInterface.Write(const W& msg, void* tag) method for - /// semantics of this method. void Write(const W& msg, void* tag) override { write_ops_.set_output_tag(tag); // TODO(ctiller): don't assert @@ -463,8 +453,6 @@ class ClientAsyncReaderWriter final call_.PerformOps(&write_ops_); } - /// See \a AsyncWriterInterface.Write(const W& msg, WriteOptions options, void* tag) - /// method for semantics of this method. void Write(const W& msg, WriteOptions options, void* tag) override { write_ops_.set_output_tag(tag); if (options.is_last_message()) { @@ -476,8 +464,6 @@ class ClientAsyncReaderWriter final call_.PerformOps(&write_ops_); } - /// See \a ClientAsyncReaderWriterInterface.WritesDone method for semantics - /// of this method. void WritesDone(void* tag) override { write_ops_.set_output_tag(tag); write_ops_.ClientSendClose(); @@ -534,12 +520,12 @@ class ServerAsyncReaderInterface : public ServerAsyncStreamingInterface, /// /// 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 Read operation + /// 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), repsonse message, and status, or if some failure + /// (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. @@ -555,11 +541,10 @@ class ServerAsyncReaderInterface : public ServerAsyncStreamingInterface, /// 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 Write. + /// \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. + /// (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. @@ -576,16 +561,11 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface { explicit ServerAsyncReader(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} - /// 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. + /// 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_); @@ -599,7 +579,6 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface { call_.PerformOps(&meta_ops_); } - /// See the \a AsyncReaderInterface.Read method for semantics. void Read(R* msg, void* tag) override { read_ops_.set_output_tag(tag); read_ops_.RecvMessage(msg); @@ -678,13 +657,13 @@ class ServerAsyncWriterInterface : public ServerAsyncStreamingInterface, /// /// 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 Read operation + /// 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), repsonse message, and status, or if some failure + /// (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. @@ -714,10 +693,7 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { explicit ServerAsyncWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} - /// Request notification of the sending the 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. + /// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics. /// /// Implicit input parameter: /// - The initial metadata that will be sent to the client from this op will be @@ -737,7 +713,6 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { call_.PerformOps(&meta_ops_); } - /// See the \a AsyncWriterInterface.Write(const W &msg, void *tag) method for semantics. void Write(const W& msg, void* tag) override { write_ops_.set_output_tag(tag); EnsureInitialMetadataSent(&write_ops_); @@ -746,7 +721,6 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { call_.PerformOps(&write_ops_); } - /// See the \a AsyncWriterInterface.Write(const W &msg, WriteOptions options, void *tag) method for semantics. void Write(const W& msg, WriteOptions options, void* tag) override { write_ops_.set_output_tag(tag); if (options.is_last_message()) { @@ -827,13 +801,13 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface, /// /// 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 Read operation + /// 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), repsonse message, and status, or if some failure + /// (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. @@ -865,10 +839,7 @@ class ServerAsyncReaderWriter final explicit ServerAsyncReaderWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} - /// Request notification of the sending the 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. + /// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics. /// /// Implicit input parameter: /// - The initial metadata that will be sent to the client from this op will be @@ -888,14 +859,12 @@ class ServerAsyncReaderWriter final call_.PerformOps(&meta_ops_); } - /// See the \a AsyncReaderInterface.Read method for semantics. void Read(R* msg, void* tag) override { read_ops_.set_output_tag(tag); read_ops_.RecvMessage(msg); call_.PerformOps(&read_ops_); } - /// See the \a AsyncWriterInterface.Write(const W& msg, void* tag) method for semantics. void Write(const W& msg, void* tag) override { write_ops_.set_output_tag(tag); EnsureInitialMetadataSent(&write_ops_); @@ -904,7 +873,6 @@ class ServerAsyncReaderWriter final call_.PerformOps(&write_ops_); } - /// See the \a AsyncWriterInterface.Write(const W& msg, WriteOptions options, void* tag) method for semantics. void Write(const W& msg, WriteOptions options, void* tag) override { write_ops_.set_output_tag(tag); if (options.is_last_message()) { diff --git a/include/grpc++/impl/codegen/async_unary_call.h b/include/grpc++/impl/codegen/async_unary_call.h index 15179e53d6e..6db0a677eaa 100644 --- a/include/grpc++/impl/codegen/async_unary_call.h +++ b/include/grpc++/impl/codegen/async_unary_call.h @@ -51,7 +51,29 @@ template 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; }; @@ -83,16 +105,9 @@ class ClientAsyncResponseReader final assert(size == sizeof(ClientAsyncResponseReader)); } - /// 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. + /// See \a ClientAsyncResponseReaderInterface::ReadInitialMetadata for + /// semantics. /// - /// Once a completion has been notified, the initial metadata read from - /// the server will be accessable through the \a ClientContext used to - /// construct this object. - /// - /// \param[in] tag Tag identifying this request. /// Side effect: /// - the \a ClientContext associated with this call is updated with /// possible initial and trailing metadata sent from the serve. @@ -104,20 +119,7 @@ class ClientAsyncResponseReader final call_.PerformOps(&meta_buf_); } - /// 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. + /// See \a ClientAysncResponseReaderInterface::Finish for semantics. /// /// Side effect: /// - the \a ClientContext associated with this call is updated with @@ -169,13 +171,11 @@ class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { explicit ServerAsyncResponseWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} - /// Request notification of the sending the 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. + /// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics. /// - /// The initial metadata that will be sent to the client from this op will be - /// taken from the \a ServerContext associated with the call. + /// 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 { diff --git a/include/grpc++/impl/codegen/client_context.h b/include/grpc++/impl/codegen/client_context.h index 31bd0d258a6..1653887289f 100644 --- a/include/grpc++/impl/codegen/client_context.h +++ b/include/grpc++/impl/codegen/client_context.h @@ -154,7 +154,7 @@ class InteropClientContextInspector; /// A ClientContext allows the person implementing a service client to: /// /// - Add custom metadata key-value pairs that will propagated to the server -/// side. +/// side. /// - Control call settings such as compression and authentication. /// - Initial and trailing metadata coming from the server. /// - Get performance metrics (ie, census). @@ -193,8 +193,7 @@ 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". + /// end in "-bin". void AddMetadata(const grpc::string& meta_key, const grpc::string& meta_value); @@ -243,13 +242,13 @@ class ClientContext { /// this RPC multiple times. void set_idempotent(bool idempotent) { idempotent_ = idempotent; } - /// EXPERIMENTAL: Set this request to be cacheable - /// If set, grpc is free the GET verb for sending the request, + /// 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 - /// See grpc/doc/wait-for-ready.md. + /// 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 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 diff --git a/include/grpc++/impl/codegen/server_context.h b/include/grpc++/impl/codegen/server_context.h index beaad1c6fa1..1bf9d102a2b 100644 --- a/include/grpc++/impl/codegen/server_context.h +++ b/include/grpc++/impl/codegen/server_context.h @@ -96,7 +96,7 @@ class ServerContextTestSpouse; /// - 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 Initial metadata coming from the client. +/// - 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 @@ -130,8 +130,7 @@ class ServerContext { /// \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". + /// 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 @@ -145,8 +144,7 @@ class ServerContext { /// \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". + /// end in "-bin". void AddTrailingMetadata(const grpc::string& key, const grpc::string& value); /// IsCancelled is always safe to call when using sync API. diff --git a/include/grpc++/impl/codegen/service_type.h b/include/grpc++/impl/codegen/service_type.h index 0df90678b18..9439bd324ef 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: diff --git a/include/grpc++/impl/codegen/sync_stream.h b/include/grpc++/impl/codegen/sync_stream.h index ecde15fac9f..82870817bb2 100644 --- a/include/grpc++/impl/codegen/sync_stream.h +++ b/include/grpc++/impl/codegen/sync_stream.h @@ -54,12 +54,14 @@ class ClientStreamingInterface { /// 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 \a - /// WritesDone. + /// * 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 WritesDone 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 Read that - /// returned "false" + /// 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 @@ -118,7 +120,7 @@ class WriterInterface { virtual ~WriterInterface() {} /// Block to write \a msg to the stream with WriteOptions \a options. - /// This is thread-safe with respect to \a Read + /// 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. @@ -127,7 +129,7 @@ class WriterInterface { virtual bool Write(const W& msg, WriteOptions options) = 0; /// Block to write \a msg to the stream with default write options. - /// This is thread-safe with respect to \a Read + /// This is thread-safe with respect to \a ReaderInterface::Read /// /// \param msg The message to be written to the stream. /// @@ -209,7 +211,6 @@ class ClientReader final : public ClientReaderInterface { cq_.Pluck(&ops); /// status ignored } - /// See the \a ReaderInterface.NextMessageSize for semantics. bool NextMessageSize(uint32_t* sz) override { *sz = call_.max_receive_message_size(); return true; @@ -258,7 +259,7 @@ class ClientWriterInterface : public ClientStreamingInterface, /// 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 Read operations only + /// Thread safe with respect to \a ReaderInterface::Read operations only /// /// \return Whether the writes were successful. virtual bool WritesDone() = 0; @@ -339,7 +340,6 @@ class ClientWriter : public ClientWriterInterface { return cq_.Pluck(&ops); } - /// See the \a ClientWriterInterface.WritesDone method for semantics. bool WritesDone() override { CallOpSet ops; ops.ClientSendClose(); @@ -389,7 +389,7 @@ class ClientReaderWriterInterface : public ClientStreamingInterface, /// 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 Read + /// Thread-safe with respect to \a ReaderInterface::Read /// /// \return Whether the writes were successful. virtual bool WritesDone() = 0; @@ -484,7 +484,6 @@ class ClientReaderWriter final : public ClientReaderWriterInterface { return cq_.Pluck(&ops); } - /// See the ClientWriterInterface.WritesDone method for semantics. bool WritesDone() override { CallOpSet ops; ops.ClientSendClose(); @@ -546,13 +545,11 @@ class ServerReader final : public ServerReaderInterface { call_->cq()->Pluck(&ops); } - /// See the \a ReaderInterface.NextMessageSize method. bool NextMessageSize(uint32_t* sz) override { *sz = call_->max_receive_message_size(); return true; } - /// See the \a ReaderInterface.Read method for semantics. bool Read(R* msg) override { CallOpSet> ops; ops.RecvMessage(msg); @@ -707,12 +704,10 @@ class ServerReaderWriter final : public ServerReaderWriterInterface { /// \a ServerContext associated with this call. void SendInitialMetadata() override { body_.SendInitialMetadata(); } - /// See the \a ReaderInterface.NextMessageSize method for semantics bool NextMessageSize(uint32_t* sz) override { return body_.NextMessageSize(sz); } - /// See the \a ReaderInterface.Read method for semantics bool Read(R* msg) override { return body_.Read(msg); } /// See the \a WriterInterface.Write(const W& msg, WriteOptions options) method for semantics. @@ -760,7 +755,7 @@ class ServerUnaryStreamer final /// 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 + /// 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. @@ -774,7 +769,7 @@ class ServerUnaryStreamer final } /// Block to write \a msg to the stream with WriteOptions \a options. - /// This is thread-safe with respect to \a Read + /// 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. @@ -823,7 +818,7 @@ class ServerSplitStreamer final /// 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 + /// 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. @@ -837,7 +832,7 @@ class ServerSplitStreamer final } /// Block to write \a msg to the stream with WriteOptions \a options. - /// This is thread-safe with respect to \a Read + /// 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. diff --git a/include/grpc++/impl/server_builder_plugin.h b/include/grpc++/impl/server_builder_plugin.h index 8ce16d66780..d7ea6729071 100644 --- a/include/grpc++/impl/server_builder_plugin.h +++ b/include/grpc++/impl/server_builder_plugin.h @@ -44,7 +44,7 @@ class ServerInitializer; class ChannelArguments; /// A builder class for the creation and startup of \a grpc::Server instances. -/// This is interface is meant for internal usage only. Implementations of this +/// This interface is meant for internal usage only. Implementations of this /// interface should add themselves to a \a ServerBuilder instance through the /// \a InternalAddPluginFactory method. class ServerBuilderPlugin { diff --git a/include/grpc/impl/codegen/gpr_slice.h b/include/grpc/impl/codegen/gpr_slice.h index 3797645442e..f2becd44f85 100644 --- a/include/grpc/impl/codegen/gpr_slice.h +++ b/include/grpc/impl/codegen/gpr_slice.h @@ -33,8 +33,7 @@ #ifndef GRPC_IMPL_CODEGEN_GPR_SLICE_H #define GRPC_IMPL_CODEGEN_GPR_SLICE_H -/** WARNING: Please do not use this header. This was added as a temporary - * measure +/** WARNING: Please do not use this header. This was added as a temporary measure * to not break some of the external projects that depend on gpr_slice_* * functions. We are actively working on moving all the gpr_slice_* references * to grpc_slice_* and this file will be removed diff --git a/include/grpc/impl/codegen/grpc_types.h b/include/grpc/impl/codegen/grpc_types.h index dccbd6dbd69..c9af38e5300 100644 --- a/include/grpc/impl/codegen/grpc_types.h +++ b/include/grpc/impl/codegen/grpc_types.h @@ -162,8 +162,7 @@ typedef struct { /** Maximum message length that the channel can receive. Int valued, bytes. -1 means unlimited. */ #define GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH "grpc.max_receive_message_length" -/** \deprecated For backward compatibility. Use - GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH +/** \deprecated For backward compatibility. Use GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH instead. */ #define GRPC_ARG_MAX_MESSAGE_LENGTH GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH /** Maximum message length that the channel can send. Int valued, bytes. @@ -272,10 +271,8 @@ typedef struct { #define GRPC_ARG_MAX_METADATA_SIZE "grpc.max_metadata_size" /** If non-zero, allow the use of SO_REUSEPORT if it's available (default 1) */ #define GRPC_ARG_ALLOW_REUSEPORT "grpc.so_reuseport" -/** If non-zero, a pointer to a buffer pool (a pointer of type - grpc_resource_quota*). - (use grpc_resource_quota_arg_vtable() to fetch an appropriate pointer arg - vtable) */ +/** If non-zero, a pointer to a buffer pool (a pointer of type grpc_resource_quota*). + (use grpc_resource_quota_arg_vtable() to fetch an appropriate pointer arg vtable) */ #define GRPC_ARG_RESOURCE_QUOTA "grpc.resource_quota" /** If non-zero, expand wildcard addresses to a list of local addresses. */ #define GRPC_ARG_EXPAND_WILDCARD_ADDRS "grpc.expand_wildcard_addrs" @@ -288,12 +285,11 @@ typedef struct { /** The grpc_socket_factory instance to create and bind sockets. A pointer. */ #define GRPC_ARG_SOCKET_FACTORY "grpc.socket_factory" /** If non-zero, Cronet transport will coalesce packets to fewer frames when - * possible. */ + possible. */ #define GRPC_ARG_USE_CRONET_PACKET_COALESCING \ "grpc.use_cronet_packet_coalescing" -/** Channel arg (integer) setting how large a slice to try and read from the -wire -each time recvmsg (or equivalent) is called **/ +/** Channel arg (integer) setting how large a slice to try and read from the wire + each time recvmsg (or equivalent) is called **/ #define GRPC_ARG_TCP_READ_CHUNK_SIZE "grpc.experimental.tcp_read_chunk_size" /** Note this is not a "channel arg" key. This is the default slice size to use * when trying to read from the wire if the GRPC_ARG_TCP_READ_CHUNK_SIZE @@ -383,8 +379,7 @@ typedef enum grpc_call_error { /** A single metadata element */ typedef struct grpc_metadata { - /** the key, value values are expected to line up with grpc_mdelem: if - changing + /** the key, value values are expected to line up with grpc_mdelem: if changing them, update metadata.h at the same time. */ grpc_slice key; grpc_slice value; diff --git a/include/grpc/slice.h b/include/grpc/slice.h index bd54bc81501..19f546afb6e 100644 --- a/include/grpc/slice.h +++ b/include/grpc/slice.h @@ -166,8 +166,7 @@ GPRAPI int grpc_slice_rchr(grpc_slice s, char c); GPRAPI int grpc_slice_chr(grpc_slice s, char c); /** return the index of the first occurance of \a needle in \a haystack, or -1 - * if - * it's not found */ + if it's not found */ GPRAPI int grpc_slice_slice(grpc_slice haystack, grpc_slice needle); GPRAPI uint32_t grpc_slice_hash(grpc_slice s);