From 356fff684a63f9503c4ff4d7b22ef7bd20f3aa12 Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Fri, 17 Aug 2018 14:55:05 -0700 Subject: [PATCH 1/3] Improve documentation on lifetime of message and status --- include/grpcpp/impl/codegen/async_stream.h | 43 +++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/include/grpcpp/impl/codegen/async_stream.h b/include/grpcpp/impl/codegen/async_stream.h index b2134590c3c..cd433e48696 100644 --- a/include/grpcpp/impl/codegen/async_stream.h +++ b/include/grpcpp/impl/codegen/async_stream.h @@ -64,7 +64,7 @@ class ClientAsyncStreamingInterface { /// 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: + /// The tag will be returned when either: /// - all incoming messages have been read and the server has returned /// a status. /// - the server has returned a non-OK status. @@ -112,6 +112,8 @@ 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. + /// GRPC doesn't take ownership or a reference to \a msg, so it is safe to + /// to deallocate once Write returns. /// This is thread-safe with respect to \a AsyncReaderInterface::Read /// /// \param[in] msg The message to be written. @@ -124,6 +126,8 @@ 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. + /// GRPC doesn't take ownership or a reference to \a msg, so it is safe to + /// to deallocate once Write returns. /// WriteOptions \a options is used to set the write options of this message. /// This is thread-safe with respect to \a AsyncReaderInterface::Read /// @@ -143,6 +147,8 @@ class AsyncWriterInterface { /// and write is initiated. 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. + /// GRPC doesn't take ownership or a reference to \a msg, so it is safe to + /// to deallocate once Write returns. /// /// \param[in] msg The message to be written. /// \param[in] options The WriteOptions to be used to write this message. @@ -629,6 +635,8 @@ class ServerAsyncReaderInterface /// 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. + /// GRPC doesn't take ownership or a reference to \a msg or \a status, so it + /// is safe to to deallocate once Finish returns. /// /// \param[in] tag Tag identifying this request. /// \param[in] status To be sent to the client as the result of this call. @@ -650,6 +658,9 @@ class ServerAsyncReaderInterface /// metadata (if not sent already), and status, or if some failure occurred /// when trying to do so. /// + /// GRPC doesn't take ownership or a reference to \a status, so it is safe to + /// to deallocate once FinishWithError returns. + /// /// \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. @@ -697,6 +708,9 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface { /// initial and trailing metadata. /// /// Note: \a msg is not sent if \a status has a non-OK code. + /// + /// GRPC doesn't take ownership or a reference to \a msg and \a status, so it + /// is safe to to deallocate once Finish returns. void Finish(const W& msg, const Status& status, void* tag) override { finish_ops_.set_output_tag(tag); if (!ctx_->sent_initial_metadata_) { @@ -723,6 +737,9 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface { /// - also sends initial metadata if not alreay sent. /// - uses the \a ServerContext associated with this call to send possible /// initial and trailing metadata. + /// + /// GRPC doesn't take ownership or a reference to \a status, so it is safe to + /// to deallocate once FinishWithError returns. void FinishWithError(const Status& status, void* tag) override { GPR_CODEGEN_ASSERT(!status.ok()); finish_ops_.set_output_tag(tag); @@ -773,6 +790,9 @@ class ServerAsyncWriterInterface /// metadata (if not sent already), response message, and status, or if /// some failure occurred when trying to do so. /// + /// GRPC doesn't take ownership or a reference to \a status, so it is safe to + /// to deallocate once Finish returns. + /// /// \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; @@ -784,6 +804,9 @@ class ServerAsyncWriterInterface /// WriteAndFinish is equivalent of performing WriteLast and Finish /// in a single step. /// + /// GRPC doesn't take ownership or a reference to \a msg and \a status, so it + /// is safe to to deallocate once WriteAndFinish returns. + /// /// \param[in] msg The message to be written. /// \param[in] options The WriteOptions to be used to write this message. /// \param[in] status The Status that server returns to client. @@ -847,6 +870,9 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { /// for sending trailing (and initial) metadata to the client. /// /// Note: \a status must have an OK code. + /// + /// GRPC doesn't take ownership or a reference to \a msg and \a status, so it + /// is safe to to deallocate once WriteAndFinish returns. void WriteAndFinish(const W& msg, WriteOptions options, const Status& status, void* tag) override { write_ops_.set_output_tag(tag); @@ -865,6 +891,9 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { /// /// Note: there are no restrictions are the code of /// \a status,it may be non-OK + /// + /// GRPC doesn't take ownership or a reference to \a status, so it is safe to + /// to deallocate once Finish returns. void Finish(const Status& status, void* tag) override { finish_ops_.set_output_tag(tag); EnsureInitialMetadataSent(&finish_ops_); @@ -924,6 +953,9 @@ class ServerAsyncReaderWriterInterface /// metadata (if not sent already), response message, and status, or if some /// failure occurred when trying to do so. /// + /// GRPC doesn't take ownership or a reference to \a status, so it is safe to + /// to deallocate once Finish returns. + /// /// \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; @@ -935,6 +967,9 @@ class ServerAsyncReaderWriterInterface /// WriteAndFinish is equivalent of performing WriteLast and Finish in a /// single step. /// + /// GRPC doesn't take ownership or a reference to \a msg and \a status, so it + /// is safe to to deallocate once WriteAndFinish returns. + /// /// \param[in] msg The message to be written. /// \param[in] options The WriteOptions to be used to write this message. /// \param[in] status The Status that server returns to client. @@ -1006,6 +1041,9 @@ class ServerAsyncReaderWriter final /// for sending trailing (and initial) metadata to the client. /// /// Note: \a status must have an OK code. + // + /// GRPC doesn't take ownership or a reference to \a msg and \a status, so it + /// is safe to to deallocate once WriteAndFinish returns. void WriteAndFinish(const W& msg, WriteOptions options, const Status& status, void* tag) override { write_ops_.set_output_tag(tag); @@ -1024,6 +1062,9 @@ class ServerAsyncReaderWriter final /// /// Note: there are no restrictions are the code of \a status, /// it may be non-OK + // + /// GRPC doesn't take ownership or a reference to \a status, so it is safe to + /// to deallocate once Finish returns. void Finish(const Status& status, void* tag) override { finish_ops_.set_output_tag(tag); EnsureInitialMetadataSent(&finish_ops_); From f80af5a7c753f18f0f15ab6b377949fc4b06d69f Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Fri, 17 Aug 2018 14:58:01 -0700 Subject: [PATCH 2/3] Formatting --- include/grpcpp/impl/codegen/async_stream.h | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/include/grpcpp/impl/codegen/async_stream.h b/include/grpcpp/impl/codegen/async_stream.h index cd433e48696..5df849f610a 100644 --- a/include/grpcpp/impl/codegen/async_stream.h +++ b/include/grpcpp/impl/codegen/async_stream.h @@ -112,9 +112,10 @@ 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 AsyncReaderInterface::Read + /// /// GRPC doesn't take ownership or a reference to \a msg, so it is safe to /// to deallocate once Write returns. - /// 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. @@ -126,11 +127,12 @@ 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. - /// GRPC doesn't take ownership or a reference to \a msg, so it is safe to - /// to deallocate once Write returns. /// WriteOptions \a options is used to set the write options of this message. /// This is thread-safe with respect to \a AsyncReaderInterface::Read /// + /// GRPC doesn't take ownership or a reference to \a msg, so it is safe to + /// to deallocate once Write returns. + /// /// \param[in] msg The message to be written. /// \param[in] options The WriteOptions to be used to write this message. /// \param[in] tag The tag identifying the operation. @@ -147,6 +149,7 @@ class AsyncWriterInterface { /// and write is initiated. 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. + /// /// GRPC doesn't take ownership or a reference to \a msg, so it is safe to /// to deallocate once Write returns. /// @@ -635,6 +638,7 @@ class ServerAsyncReaderInterface /// 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. + /// /// GRPC doesn't take ownership or a reference to \a msg or \a status, so it /// is safe to to deallocate once Finish returns. /// From 5f2bb7a7d4d90f09423419a1bc8bc35847c7cb4e Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Wed, 12 Sep 2018 11:14:18 -0700 Subject: [PATCH 3/3] s/GRPC/gRPC --- include/grpcpp/impl/codegen/async_stream.h | 30 +++++++++++----------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/include/grpcpp/impl/codegen/async_stream.h b/include/grpcpp/impl/codegen/async_stream.h index 5df849f610a..9c3c40af542 100644 --- a/include/grpcpp/impl/codegen/async_stream.h +++ b/include/grpcpp/impl/codegen/async_stream.h @@ -114,7 +114,7 @@ class AsyncWriterInterface { /// queue BEFORE calling Write again. /// This is thread-safe with respect to \a AsyncReaderInterface::Read /// - /// GRPC doesn't take ownership or a reference to \a msg, so it is safe to + /// gRPC doesn't take ownership or a reference to \a msg, so it is safe to /// to deallocate once Write returns. /// /// \param[in] msg The message to be written. @@ -130,7 +130,7 @@ class AsyncWriterInterface { /// WriteOptions \a options is used to set the write options of this message. /// This is thread-safe with respect to \a AsyncReaderInterface::Read /// - /// GRPC doesn't take ownership or a reference to \a msg, so it is safe to + /// gRPC doesn't take ownership or a reference to \a msg, so it is safe to /// to deallocate once Write returns. /// /// \param[in] msg The message to be written. @@ -150,7 +150,7 @@ class AsyncWriterInterface { /// the flow control window size. If \a msg size is larger than the window /// size, it will be sent on wire without buffering. /// - /// GRPC doesn't take ownership or a reference to \a msg, so it is safe to + /// gRPC doesn't take ownership or a reference to \a msg, so it is safe to /// to deallocate once Write returns. /// /// \param[in] msg The message to be written. @@ -639,7 +639,7 @@ class ServerAsyncReaderInterface /// metadata (if not sent already), response message, and status, or if /// some failure occurred when trying to do so. /// - /// GRPC doesn't take ownership or a reference to \a msg or \a status, so it + /// gRPC doesn't take ownership or a reference to \a msg or \a status, so it /// is safe to to deallocate once Finish returns. /// /// \param[in] tag Tag identifying this request. @@ -662,7 +662,7 @@ class ServerAsyncReaderInterface /// metadata (if not sent already), and status, or if some failure occurred /// when trying to do so. /// - /// GRPC doesn't take ownership or a reference to \a status, so it is safe to + /// gRPC doesn't take ownership or a reference to \a status, so it is safe to /// to deallocate once FinishWithError returns. /// /// \param[in] tag Tag identifying this request. @@ -713,7 +713,7 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface { /// /// Note: \a msg is not sent if \a status has a non-OK code. /// - /// GRPC doesn't take ownership or a reference to \a msg and \a status, so it + /// gRPC doesn't take ownership or a reference to \a msg and \a status, so it /// is safe to to deallocate once Finish returns. void Finish(const W& msg, const Status& status, void* tag) override { finish_ops_.set_output_tag(tag); @@ -742,7 +742,7 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface { /// - uses the \a ServerContext associated with this call to send possible /// initial and trailing metadata. /// - /// GRPC doesn't take ownership or a reference to \a status, so it is safe to + /// gRPC doesn't take ownership or a reference to \a status, so it is safe to /// to deallocate once FinishWithError returns. void FinishWithError(const Status& status, void* tag) override { GPR_CODEGEN_ASSERT(!status.ok()); @@ -794,7 +794,7 @@ class ServerAsyncWriterInterface /// metadata (if not sent already), response message, and status, or if /// some failure occurred when trying to do so. /// - /// GRPC doesn't take ownership or a reference to \a status, so it is safe to + /// gRPC doesn't take ownership or a reference to \a status, so it is safe to /// to deallocate once Finish returns. /// /// \param[in] tag Tag identifying this request. @@ -808,7 +808,7 @@ class ServerAsyncWriterInterface /// WriteAndFinish is equivalent of performing WriteLast and Finish /// in a single step. /// - /// GRPC doesn't take ownership or a reference to \a msg and \a status, so it + /// gRPC doesn't take ownership or a reference to \a msg and \a status, so it /// is safe to to deallocate once WriteAndFinish returns. /// /// \param[in] msg The message to be written. @@ -875,7 +875,7 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { /// /// Note: \a status must have an OK code. /// - /// GRPC doesn't take ownership or a reference to \a msg and \a status, so it + /// gRPC doesn't take ownership or a reference to \a msg and \a status, so it /// is safe to to deallocate once WriteAndFinish returns. void WriteAndFinish(const W& msg, WriteOptions options, const Status& status, void* tag) override { @@ -896,7 +896,7 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface { /// Note: there are no restrictions are the code of /// \a status,it may be non-OK /// - /// GRPC doesn't take ownership or a reference to \a status, so it is safe to + /// gRPC doesn't take ownership or a reference to \a status, so it is safe to /// to deallocate once Finish returns. void Finish(const Status& status, void* tag) override { finish_ops_.set_output_tag(tag); @@ -957,7 +957,7 @@ class ServerAsyncReaderWriterInterface /// metadata (if not sent already), response message, and status, or if some /// failure occurred when trying to do so. /// - /// GRPC doesn't take ownership or a reference to \a status, so it is safe to + /// gRPC doesn't take ownership or a reference to \a status, so it is safe to /// to deallocate once Finish returns. /// /// \param[in] tag Tag identifying this request. @@ -971,7 +971,7 @@ class ServerAsyncReaderWriterInterface /// WriteAndFinish is equivalent of performing WriteLast and Finish in a /// single step. /// - /// GRPC doesn't take ownership or a reference to \a msg and \a status, so it + /// gRPC doesn't take ownership or a reference to \a msg and \a status, so it /// is safe to to deallocate once WriteAndFinish returns. /// /// \param[in] msg The message to be written. @@ -1046,7 +1046,7 @@ class ServerAsyncReaderWriter final /// /// Note: \a status must have an OK code. // - /// GRPC doesn't take ownership or a reference to \a msg and \a status, so it + /// gRPC doesn't take ownership or a reference to \a msg and \a status, so it /// is safe to to deallocate once WriteAndFinish returns. void WriteAndFinish(const W& msg, WriteOptions options, const Status& status, void* tag) override { @@ -1067,7 +1067,7 @@ class ServerAsyncReaderWriter final /// Note: there are no restrictions are the code of \a status, /// it may be non-OK // - /// GRPC doesn't take ownership or a reference to \a status, so it is safe to + /// gRPC doesn't take ownership or a reference to \a status, so it is safe to /// to deallocate once Finish returns. void Finish(const Status& status, void* tag) override { finish_ops_.set_output_tag(tag);