From 3306bcd1a1595142d43ceddefc8311e86cedf6d2 Mon Sep 17 00:00:00 2001 From: David Garcia Quintas Date: Thu, 27 Aug 2015 23:08:55 -0700 Subject: [PATCH] Docs for streams + exposed auth properties --- include/grpc++/support/async_stream.h | 45 ++++++++++---- include/grpc++/support/auth_context.h | 14 +++++ include/grpc++/support/sync_stream.h | 90 +++++++++++++++++---------- 3 files changed, 104 insertions(+), 45 deletions(-) diff --git a/include/grpc++/support/async_stream.h b/include/grpc++/support/async_stream.h index 4c12fda12f6..5b49b90fa98 100644 --- a/include/grpc++/support/async_stream.h +++ b/include/grpc++/support/async_stream.h @@ -45,32 +45,48 @@ namespace grpc { -// Async interfaces -// Common interface for all client side streaming. +/// Common interface for all client side asynchronous streaming. class ClientAsyncStreamingInterface { public: virtual ~ClientAsyncStreamingInterface() {} + /// Request notification of the reading of the initial metadata. Completion + /// will be notified by \a tag on the associated completion queue. + /// + /// \param[in] tag Tag identifying this request. virtual void ReadInitialMetadata(void* tag) = 0; + /// Request notification completion. + /// + /// \param[out] status To be updated with the operation status. + /// \param[in] tag Tag identifying this request. virtual void Finish(Status* status, void* tag) = 0; }; -// An interface that yields a sequence of R messages. +/// An interface that yields a sequence of messages of type \a R. template class AsyncReaderInterface { public: virtual ~AsyncReaderInterface() {} + /// Read a message of type \a R into \a msg. Completion will be notified by \a + /// tag on the associated completion queue. + /// + /// \param[out] msg Where to eventually store the read message. + /// \param[in] tag The tag identifying the operation. virtual void Read(R* msg, void* tag) = 0; }; -// An interface that can be fed a sequence of W messages. +/// An interface that can be fed a sequence of messages of type \a W. template class AsyncWriterInterface { public: virtual ~AsyncWriterInterface() {} + /// Request the writing of \a msg with identifying tag \a tag. + /// + /// \param[in] msg The message to be written. + /// \param[in] tag The tag identifying the operation. virtual void Write(const W& msg, void* tag) = 0; }; @@ -81,7 +97,7 @@ class ClientAsyncReaderInterface : public ClientAsyncStreamingInterface, template class ClientAsyncReader GRPC_FINAL : public ClientAsyncReaderInterface { public: - // Create a stream and write the first request out. + /// Create a stream and write the first request out. template ClientAsyncReader(Channel* channel, CompletionQueue* cq, const RpcMethod& method, ClientContext* context, @@ -89,7 +105,7 @@ class ClientAsyncReader GRPC_FINAL : public ClientAsyncReaderInterface { : context_(context), call_(channel->CreateCall(method, context, cq)) { init_ops_.set_output_tag(tag); init_ops_.SendInitialMetadata(context->send_initial_metadata_); - // TODO(ctiller): don't assert + /// TODO(ctiller): don't assert GPR_ASSERT(init_ops_.SendMessage(request).ok()); init_ops_.ClientSendClose(); call_.PerformOps(&init_ops_); @@ -131,10 +147,14 @@ class ClientAsyncReader GRPC_FINAL : public ClientAsyncReaderInterface { CallOpSet finish_ops_; }; +/// Common interface for client side asynchronous writing. template class ClientAsyncWriterInterface : public ClientAsyncStreamingInterface, public AsyncWriterInterface { public: + /// Signal the client is done with the writes. + /// + /// \param[in] tag The tag identifying the operation. virtual void WritesDone(void* tag) = 0; }; @@ -163,7 +183,7 @@ class ClientAsyncWriter GRPC_FINAL : public ClientAsyncWriterInterface { void Write(const W& msg, void* tag) GRPC_OVERRIDE { write_ops_.set_output_tag(tag); - // TODO(ctiller): don't assert + /// TODO(ctiller): don't assert GPR_ASSERT(write_ops_.SendMessage(msg).ok()); call_.PerformOps(&write_ops_); } @@ -194,12 +214,15 @@ class ClientAsyncWriter GRPC_FINAL : public ClientAsyncWriterInterface { CallOpClientRecvStatus> finish_ops_; }; -// Client-side interface for bi-directional streaming. +/// Client-side interface for asynchronous bi-directional streaming. template class ClientAsyncReaderWriterInterface : public ClientAsyncStreamingInterface, public AsyncWriterInterface, public AsyncReaderInterface { public: + /// Signal the client is done with the writes. + /// + /// \param[in] tag The tag identifying the operation. virtual void WritesDone(void* tag) = 0; }; @@ -235,7 +258,7 @@ class ClientAsyncReaderWriter GRPC_FINAL void Write(const W& msg, void* tag) GRPC_OVERRIDE { write_ops_.set_output_tag(tag); - // TODO(ctiller): don't assert + /// TODO(ctiller): don't assert GPR_ASSERT(write_ops_.SendMessage(msg).ok()); call_.PerformOps(&write_ops_); } @@ -348,7 +371,7 @@ class ServerAsyncWriter GRPC_FINAL : public ServerAsyncStreamingInterface, write_ops_.SendInitialMetadata(ctx_->initial_metadata_); ctx_->sent_initial_metadata_ = true; } - // TODO(ctiller): don't assert + /// TODO(ctiller): don't assert GPR_ASSERT(write_ops_.SendMessage(msg).ok()); call_.PerformOps(&write_ops_); } @@ -373,7 +396,7 @@ class ServerAsyncWriter GRPC_FINAL : public ServerAsyncStreamingInterface, CallOpSet finish_ops_; }; -// Server-side interface for bi-directional streaming. +/// Server-side interface for asynchronous bi-directional streaming. template class ServerAsyncReaderWriter GRPC_FINAL : public ServerAsyncStreamingInterface, public AsyncWriterInterface, diff --git a/include/grpc++/support/auth_context.h b/include/grpc++/support/auth_context.h index a8898a54acb..2e9611affc6 100644 --- a/include/grpc++/support/auth_context.h +++ b/include/grpc++/support/auth_context.h @@ -37,6 +37,7 @@ #include #include +#include #include #include @@ -95,6 +96,19 @@ class AuthContext { /// Iteration over all the properties. virtual AuthPropertyIterator begin() const = 0; virtual AuthPropertyIterator end() const = 0; + + static string transport_security_type_property_name() { + return GRPC_TRANSPORT_SECURITY_TYPE_PROPERTY_NAME; + } + static string ssl_transport_security_type() { + return GRPC_SSL_TRANSPORT_SECURITY_TYPE; + } + static string x509_cn_property_name() { + return GRPC_X509_CN_PROPERTY_NAME; + } + static string x509_san_property_name() { + return GRPC_X509_SAN_PROPERTY_NAME; + } }; } // namespace grpc diff --git a/include/grpc++/support/sync_stream.h b/include/grpc++/support/sync_stream.h index b4bb637ff23..a038ecbd503 100644 --- a/include/grpc++/support/sync_stream.h +++ b/include/grpc++/support/sync_stream.h @@ -45,60 +45,78 @@ namespace grpc { -// Common interface for all client side streaming. +/// Common interface for all synchronous client side streaming. class ClientStreamingInterface { public: virtual ~ClientStreamingInterface() {} - // Wait until the stream finishes, and return the final status. When the - // client side declares it has no more message to send, either implicitly or - // by calling WritesDone, it needs to make sure there is no more message to - // be received from the server, either implicitly or by getting a false from - // a Read(). - // This function will return either: - // - when all incoming messages have been read and the server has returned - // status - // - OR when the server has returned a non-OK status + /// Wait until the stream finishes, and return the final status. When the + /// client side declares it has no more message to send, either implicitly or + /// by calling \a WritesDone(), it needs to make sure there is no more message + /// to be received from the server, either implicitly or by getting a false + /// from a \a Read(). + /// + /// This function will return either: + /// - when all incoming messages have been read and the server has returned + /// status. + /// - OR when the server has returned a non-OK status. virtual Status Finish() = 0; }; -// An interface that yields a sequence of R messages. +/// An interface that yields a sequence of messages of type \a R. template class ReaderInterface { public: virtual ~ReaderInterface() {} - // Blocking read a message and parse to msg. Returns true on success. - // The method returns false when there will be no more incoming messages, - // either because the other side has called WritesDone or the stream has - // failed (or been cancelled). + /// Blocking read a message and parse to \a msg. Returns \a true on success. + /// + /// \param[out] msg The read message. + /// + /// \return \a false when there will be no more incoming messages, either + /// because the other side has called \a WritesDone() or the stream has failed + /// (or been cancelled). virtual bool Read(R* msg) = 0; }; -// An interface that can be fed a sequence of W messages. +/// An interface that can be fed a sequence of messages of type \a W. template class WriterInterface { public: virtual ~WriterInterface() {} - // Blocking write msg to the stream. Returns true on success. - // Returns false when the stream has been closed. + /// Blocking write \a msg to the stream with options. + /// + /// \param msg The message to be written to the stream. + /// \param options Options affecting the write operation. + /// + /// \return \a true on success, \a false when the stream has been closed. virtual bool Write(const W& msg, const WriteOptions& options) = 0; + /// Blocking write \a msg to the stream with default options. + /// + /// \param msg The message to be written to the stream. + /// + /// \return \a true on success, \a false when the stream has been closed. inline bool Write(const W& msg) { return Write(msg, WriteOptions()); } }; +/// Client-side interface for streaming reads of message of type \a R. template class ClientReaderInterface : public ClientStreamingInterface, public ReaderInterface { public: + /// Blocking wait for initial metadata from server. The received metadata + /// can only be accessed after this call returns. Should only be called before + /// the first read. Calling this method is optional, and if it is not called + /// the metadata will be available in ClientContext after the first read. virtual void WaitForInitialMetadata() = 0; }; template class ClientReader GRPC_FINAL : public ClientReaderInterface { public: - // Blocking create a stream and write the first request out. + /// Blocking create a stream and write the first request out. template ClientReader(Channel* channel, const RpcMethod& method, ClientContext* context, const W& request) @@ -106,24 +124,20 @@ class ClientReader GRPC_FINAL : public ClientReaderInterface { CallOpSet ops; ops.SendInitialMetadata(context->send_initial_metadata_); - // TODO(ctiller): don't assert + /// TODO(ctiller): don't assert GPR_ASSERT(ops.SendMessage(request).ok()); ops.ClientSendClose(); call_.PerformOps(&ops); cq_.Pluck(&ops); } - // Blocking wait for initial metadata from server. The received metadata - // can only be accessed after this call returns. Should only be called before - // the first read. Calling this method is optional, and if it is not called - // the metadata will be available in ClientContext after the first read. void WaitForInitialMetadata() { GPR_ASSERT(!context_->initial_metadata_received_); CallOpSet ops; ops.RecvInitialMetadata(context_); call_.PerformOps(&ops); - cq_.Pluck(&ops); // status ignored + cq_.Pluck(&ops); /// status ignored } bool Read(R* msg) GRPC_OVERRIDE { @@ -151,17 +165,21 @@ class ClientReader GRPC_FINAL : public ClientReaderInterface { Call call_; }; +/// Client-side interface for streaming writes of message of type \a W. template class ClientWriterInterface : public ClientStreamingInterface, public WriterInterface { public: + /// Block until writes are completed. + /// + /// \return Whether the writes were successful. virtual bool WritesDone() = 0; }; template class ClientWriter : public ClientWriterInterface { public: - // Blocking create a stream. + /// Blocking create a stream. template ClientWriter(Channel* channel, const RpcMethod& method, ClientContext* context, R* response) @@ -191,7 +209,7 @@ class ClientWriter : public ClientWriterInterface { return cq_.Pluck(&ops); } - // Read the final response and wait for the final status. + /// Read the final response and wait for the final status. Status Finish() GRPC_OVERRIDE { Status status; finish_ops_.ClientRecvStatus(context_, &status); @@ -207,20 +225,28 @@ class ClientWriter : public ClientWriterInterface { Call call_; }; -// Client-side interface for bi-directional streaming. +/// Client-side interface for bi-directional streaming. template class ClientReaderWriterInterface : public ClientStreamingInterface, public WriterInterface, public ReaderInterface { public: + /// Blocking wait for initial metadata from server. The received metadata + /// can only be accessed after this call returns. Should only be called before + /// the first read. Calling this method is optional, and if it is not called + /// the metadata will be available in ClientContext after the first read. virtual void WaitForInitialMetadata() = 0; + + /// Block until writes are completed. + /// + /// \return Whether the writes were successful. virtual bool WritesDone() = 0; }; template class ClientReaderWriter GRPC_FINAL : public ClientReaderWriterInterface { public: - // Blocking create a stream. + /// Blocking create a stream. ClientReaderWriter(Channel* channel, const RpcMethod& method, ClientContext* context) : context_(context), call_(channel->CreateCall(method, context, &cq_)) { @@ -230,10 +256,6 @@ class ClientReaderWriter GRPC_FINAL : public ClientReaderWriterInterface { cq_.Pluck(&ops); } - // Blocking wait for initial metadata from server. The received metadata - // can only be accessed after this call returns. Should only be called before - // the first read. Calling this method is optional, and if it is not called - // the metadata will be available in ClientContext after the first read. void WaitForInitialMetadata() { GPR_ASSERT(!context_->initial_metadata_received_); @@ -344,7 +366,7 @@ class ServerWriter GRPC_FINAL : public WriterInterface { ServerContext* const ctx_; }; -// Server-side interface for bi-directional streaming. +/// Server-side interface for bi-directional streaming. template class ServerReaderWriter GRPC_FINAL : public WriterInterface, public ReaderInterface {