diff options
Diffstat (limited to 'include/grpc++/impl/codegen/sync_stream.h')
| -rw-r--r-- | include/grpc++/impl/codegen/sync_stream.h | 120 |
1 files changed, 61 insertions, 59 deletions
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. |