diff options
-rw-r--r-- | include/grpc++/impl/codegen/async_stream.h | 143 | ||||
-rw-r--r-- | include/grpc++/impl/codegen/async_unary_call.h | 9 | ||||
-rw-r--r-- | include/grpc++/impl/codegen/server_context.h | 67 | ||||
-rw-r--r-- | include/grpc++/impl/codegen/service_type.h | 10 | ||||
-rw-r--r-- | include/grpc++/impl/codegen/sync_stream.h | 120 | ||||
-rw-r--r-- | include/grpc/impl/codegen/gpr_slice.h | 10 | ||||
-rw-r--r-- | include/grpc/impl/codegen/grpc_types.h | 61 |
7 files changed, 217 insertions, 203 deletions
diff --git a/include/grpc++/impl/codegen/async_stream.h b/include/grpc++/impl/codegen/async_stream.h index 72fbd9ea79..3402fff38b 100644 --- a/include/grpc++/impl/codegen/async_stream.h +++ b/include/grpc++/impl/codegen/async_stream.h @@ -63,14 +63,15 @@ class ClientAsyncStreamingInterface { /// 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 + /// * 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 + /// 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: @@ -80,8 +81,8 @@ class ClientAsyncStreamingInterface { /// - 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. + /// Note that implementations of this method attempt to receive initial + /// metadata from the server if initial metadata hasn't yet been received. /// /// \param[in] tag Tag identifying this request. /// \param[out] status To be updated with the operation status. @@ -99,14 +100,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 AsyncReaderInterface::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. + /// 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; }; @@ -142,11 +143,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 @@ -166,7 +167,8 @@ 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. +/// 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: @@ -191,8 +193,8 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface<R> { assert(size == sizeof(ClientAsyncReader)); } - /// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata method for - /// semantics. + /// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata + /// method for semantics. /// /// Side effect: /// - upon receiving initial metadata from the server, @@ -266,7 +268,8 @@ class ClientAsyncWriterInterface : public ClientAsyncStreamingInterface, }; /// 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. +/// 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: @@ -298,10 +301,9 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> { /// 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. + /// - 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_); @@ -395,8 +397,9 @@ class ClientAsyncReaderWriterInterface : public ClientAsyncStreamingInterface, }; /// 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. +/// 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> { @@ -428,7 +431,7 @@ class ClientAsyncReaderWriter final /// 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 + /// be accessed through this \a ClientContext. void ReadInitialMetadata(void* tag) override { GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_); @@ -514,26 +517,27 @@ class ServerAsyncReaderInterface : public ServerAsyncStreamingInterface, 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. + /// 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'. + /// 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. + /// 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. + /// 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. @@ -543,8 +547,9 @@ class ServerAsyncReaderInterface : public ServerAsyncStreamingInterface, /// 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. + /// 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. @@ -564,8 +569,8 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface<W, R> { /// 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. + /// - 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_); @@ -657,25 +662,25 @@ 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 AsyncReaderInterface::Read operation - /// with a non-ok result (e.g., cq->Next(&read_tag, &ok) filled in 'ok' - /// with 'false'. + /// 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. + /// 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. @@ -696,8 +701,8 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface<W> { /// 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. + /// - 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 { @@ -753,10 +758,11 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface<W> { /// 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. + /// - 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 + /// 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_); @@ -801,12 +807,14 @@ 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 AsyncReaderInterface::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 + /// 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. /// @@ -815,8 +823,8 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface, 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. @@ -830,8 +838,9 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface, }; /// 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. +/// 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> { @@ -842,8 +851,8 @@ class ServerAsyncReaderWriter final /// 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. + /// - 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 { @@ -883,7 +892,8 @@ class ServerAsyncReaderWriter final call_.PerformOps(&write_ops_); } - /// See the \a ServerAsyncReaderWriterInterface.WriteAndFinish method for semantics. + /// See the \a ServerAsyncReaderWriterInterface.WriteAndFinish + /// method for semantics. /// /// Implicit input parameter: /// - the \a ServerContext associated with this call is used @@ -903,10 +913,11 @@ class ServerAsyncReaderWriter final /// 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. + /// - 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 + /// 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 6db0a677ea..0f2f466bfc 100644 --- a/include/grpc++/impl/codegen/async_unary_call.h +++ b/include/grpc++/impl/codegen/async_unary_call.h @@ -174,8 +174,8 @@ class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { /// 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. + /// 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 { @@ -193,12 +193,12 @@ class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { /// 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. + /// 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). @@ -234,6 +234,7 @@ class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { /// \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). diff --git a/include/grpc++/impl/codegen/server_context.h b/include/grpc++/impl/codegen/server_context.h index 1bf9d102a2..42575176d7 100644 --- a/include/grpc++/impl/codegen/server_context.h +++ b/include/grpc++/impl/codegen/server_context.h @@ -93,17 +93,17 @@ class ServerContextTestSpouse; /// 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. +/// - 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 parameter to the see \a grpc::Server -/// constructor. +/// 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 parameter +/// to the see \a grpc::Server constructor. /// /// \warning ServerContext instances should \em not be reused across rpcs. class ServerContext { @@ -119,32 +119,32 @@ class ServerContext { /// 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. + /// 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, it must be - /// must end in "-bin". + /// \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 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. + /// 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). + /// \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, it must be - /// end in "-bin". + /// \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 end in "-bin". void AddTrailingMetadata(const grpc::string& key, const grpc::string& value); /// IsCancelled is always safe to call when using sync API. @@ -152,22 +152,23 @@ class ServerContext { /// 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. + /// 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. + /// 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). + /// 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 @@ -194,7 +195,7 @@ class ServerContext { /// 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 + /// \a set_compression_level. bool compression_level_set() const { return compression_level_set_; } /// Return the compression algorithm to be used by the server call. diff --git a/include/grpc++/impl/codegen/service_type.h b/include/grpc++/impl/codegen/service_type.h index 9439bd324e..b88019164d 100644 --- a/include/grpc++/impl/codegen/service_type.h +++ b/include/grpc++/impl/codegen/service_type.h @@ -54,10 +54,10 @@ 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. + /// 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; @@ -162,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/sync_stream.h b/include/grpc++/impl/codegen/sync_stream.h index 82870817bb..e7d9b07c19 100644 --- a/include/grpc++/impl/codegen/sync_stream.h +++ b/include/grpc++/impl/codegen/sync_stream.h @@ -54,18 +54,18 @@ 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 <i>WritesDone</i> method of the class in use, e.g. - /// \a ClientWriterInterface::WritesDone or + /// * 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"). + /// 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 - /// status. + /// - 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. @@ -97,7 +97,8 @@ class ReaderInterface { public: virtual ~ReaderInterface() {} - /// Get an 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; /// Block to read a message and parse to \a msg. Returns \a true on success. @@ -141,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. @@ -167,14 +168,15 @@ class ClientReaderInterface : public ClientStreamingInterface, 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. +/// 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: - /// 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. + /// 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) @@ -218,8 +220,9 @@ class ClientReader final : public ClientReaderInterface<R> { /// 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 + /// 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; @@ -234,8 +237,8 @@ class ClientReader final : public ClientReaderInterface<R> { /// 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. + /// The \a ClientContext associated with this call is updated with + /// possible metadata received from the server. Status Finish() override { CallOpSet<CallOpClientRecvStatus> ops; Status status; @@ -266,15 +269,16 @@ class ClientWriterInterface : public ClientStreamingInterface, }; /// 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. +/// where the outgoing message stream coming from the client has messages of +/// type \a W. template <class W> class ClientWriter : public ClientWriterInterface<W> { public: - /// 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. + /// 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) @@ -299,9 +303,8 @@ class ClientWriter : public ClientWriterInterface<W> { /// semantics. /// // Side effect: - /// Once complete, the initial metadata read from - /// the server will be accessable through the \a ClientContext used to - /// construct this object. + /// 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_); @@ -315,8 +318,8 @@ class ClientWriter : public ClientWriterInterface<W> { /// for semantics. /// /// Side effect: - /// Also sends initial metadata if not already sent (using the \a ClientContext - /// associated with this call). + /// 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, @@ -350,8 +353,9 @@ class ClientWriter : public ClientWriterInterface<W> { /// 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. + /// - 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_) { @@ -395,15 +399,15 @@ class ClientReaderWriterInterface : public ClientStreamingInterface, 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. +/// 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: - /// 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 + /// 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) @@ -425,9 +429,8 @@ class ClientReaderWriter final : public ClientReaderWriterInterface<W, R> { /// 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. + /// 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_); @@ -528,8 +531,7 @@ class ServerReader final : public ServerReaderInterface<R> { 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 + /// 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_); @@ -691,16 +693,16 @@ class ServerReaderWriterBody final { } // namespace internal /// 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. +/// 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 + /// for semantics. Note that initial metadata will be affected by the /// \a ServerContext associated with this call. void SendInitialMetadata() override { body_.SendInitialMetadata(); } @@ -710,7 +712,8 @@ 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. + /// 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). @@ -728,8 +731,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> @@ -755,8 +757,8 @@ 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 ReaderInterface::Read on the same stream since reads on the same stream - /// are delivered in order. + /// 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. @@ -818,8 +820,8 @@ 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 ReaderInterface::Read on the same stream since reads on the same stream - /// are delivered in order. + /// 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. diff --git a/include/grpc/impl/codegen/gpr_slice.h b/include/grpc/impl/codegen/gpr_slice.h index f2becd44f8..ead0b7db95 100644 --- a/include/grpc/impl/codegen/gpr_slice.h +++ b/include/grpc/impl/codegen/gpr_slice.h @@ -33,11 +33,11 @@ #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 - * 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 - * */ +/** 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 + */ /* TODO (sreek) - Allowed by default but will be very soon turned off */ #define GRPC_ALLOW_GPR_SLICE_FUNCTIONS 1 diff --git a/include/grpc/impl/codegen/grpc_types.h b/include/grpc/impl/codegen/grpc_types.h index c9af38e530..99b0e43b3c 100644 --- a/include/grpc/impl/codegen/grpc_types.h +++ b/include/grpc/impl/codegen/grpc_types.h @@ -67,8 +67,8 @@ typedef struct grpc_byte_buffer { } data; } grpc_byte_buffer; -/** Completion Queues enable notification of the completion of asynchronous - actions. */ +/** Completion Queues enable notification of the completion of + * asynchronous actions. */ typedef struct grpc_completion_queue grpc_completion_queue; /** An alarm associated with a completion queue. */ @@ -134,9 +134,9 @@ typedef struct { Used to set optional channel-level configuration. These configuration options are modelled as key-value pairs as defined by grpc_arg; keys are strings to allow easy backwards-compatible extension - by arbitrary parties. - All evaluation is performed at channel creation time (i.e. the values in - this structure need only live through the creation invocation). + by arbitrary parties. All evaluation is performed at channel creation + time (i.e. the values in this structure need only live through the + creation invocation). See the description of the \ref grpc_arg_keys "available args" for more details. */ @@ -162,8 +162,8 @@ 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 - instead. */ +/** \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. -1 means unlimited. */ @@ -171,8 +171,8 @@ typedef struct { /** Maximum time that a channel may have no outstanding rpcs. Int valued, milliseconds. INT_MAX means unlimited. */ #define GRPC_ARG_MAX_CONNECTION_IDLE_MS "grpc.max_connection_idle_ms" -/** Maximum time that a channel may exist. Int valued, milliseconds. INT_MAX - means unlimited. */ +/** Maximum time that a channel may exist. Int valued, milliseconds. + * INT_MAX means unlimited. */ #define GRPC_ARG_MAX_CONNECTION_AGE_MS "grpc.max_connection_age_ms" /** Grace period after the chennel reaches its max age. Int valued, milliseconds. INT_MAX means unlimited. */ @@ -271,8 +271,10 @@ 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" @@ -284,12 +286,12 @@ typedef struct { #define GRPC_ARG_SOCKET_MUTATOR "grpc.socket_mutator" /** 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. */ +/** If non-zero, Cronet transport will coalesce packets to fewer frames + * when 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 @@ -331,8 +333,8 @@ typedef enum grpc_call_error { GRPC_CALL_ERROR_INVALID_METADATA, /** invalid message was passed to this call */ GRPC_CALL_ERROR_INVALID_MESSAGE, - /** completion queue for notification has not been registered with the - server */ + /** completion queue for notification has not been registered + * with the server */ GRPC_CALL_ERROR_NOT_SERVER_COMPLETION_QUEUE, /** this batch of operations leads to more operations than allowed */ GRPC_CALL_ERROR_BATCH_TOO_BIG, @@ -379,8 +381,8 @@ 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 - them, update metadata.h at the same time. */ + /** 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; @@ -447,15 +449,13 @@ typedef enum { GRPC_OP_SEND_MESSAGE, /** Send a close from the client: one and only one instance MUST be sent from the client, unless the call was cancelled - in which case this can be - skipped. - This op completes after all bytes for the call (including the close) - have passed outgoing flow control. */ + skipped. This op completes after all bytes for the call + (including the close) have passed outgoing flow control. */ GRPC_OP_SEND_CLOSE_FROM_CLIENT, /** Send status from the server: one and only one instance MUST be sent from the server unless the call was cancelled - in which case this can be - skipped. - This op completes after all bytes for the call (including the status) - have passed outgoing flow control. */ + skipped. This op completes after all bytes for the call + (including the status) have passed outgoing flow control. */ GRPC_OP_SEND_STATUS_FROM_SERVER, /** Receive initial metadata: one and only one MUST be made on the client, must not be made on the server. @@ -473,10 +473,10 @@ typedef enum { This op completes after all activity on the call has completed. */ GRPC_OP_RECV_STATUS_ON_CLIENT, /** Receive close on the server: one and only one must be made on the - server. - This op completes after the close has been received by the server. - This operation always succeeds, meaning ops paired with this operation - will also appear to succeed, even though they may not have. */ + server. This op completes after the close has been received by the + server. This operation always succeeds, meaning ops paired with + this operation will also appear to succeed, even though they may not + have. */ GRPC_OP_RECV_CLOSE_ON_SERVER } grpc_op_type; @@ -537,8 +537,7 @@ typedef struct grpc_op { elements stays with the call object (ie key, value members are owned by the call object, trailing_metadata->array is owned by the caller). After the operation completes, call grpc_metadata_array_destroy on - this - value, or reuse it in a future op. */ + this value, or reuse it in a future op. */ grpc_metadata_array *trailing_metadata; grpc_status_code *status; grpc_slice *status_details; |