diff options
Diffstat (limited to 'include/grpc++/impl')
| -rw-r--r-- | include/grpc++/impl/codegen/async_stream.h | 13 | ||||
| -rw-r--r-- | include/grpc++/impl/codegen/client_context.h | 10 | ||||
| -rw-r--r-- | include/grpc++/impl/codegen/completion_queue.h | 15 | ||||
| -rw-r--r-- | include/grpc++/impl/codegen/server_context.h | 7 | ||||
| -rw-r--r-- | include/grpc++/impl/codegen/sync_stream.h | 11 |
5 files changed, 43 insertions, 13 deletions
diff --git a/include/grpc++/impl/codegen/async_stream.h b/include/grpc++/impl/codegen/async_stream.h index 0606441549..e96d224ddb 100644 --- a/include/grpc++/impl/codegen/async_stream.h +++ b/include/grpc++/impl/codegen/async_stream.h @@ -52,11 +52,14 @@ class ClientAsyncStreamingInterface { /// Request notification of the reading of the initial metadata. Completion /// will be notified by \a tag on the associated completion queue. + /// This call is optional, but if it is used, it cannot be used concurrently + /// with or after the \a Read method. /// /// \param[in] tag Tag identifying this request. virtual void ReadInitialMetadata(void* tag) = 0; - /// Request notification completion. + /// Indicate that the stream is to be finished and request notification + /// Should not be used concurrently with other operations /// /// \param[out] status To be updated with the operation status. /// \param[in] tag Tag identifying this request. @@ -71,6 +74,11 @@ class AsyncReaderInterface { /// Read a message of type \a R into \a msg. Completion will be notified by \a /// tag on the associated completion queue. + /// This is thread-safe with respect to \a Write or \a WritesDone methods. It + /// should not be called concurrently with other streaming APIs + /// on the same stream. It is not meaningful to call it concurrently + /// with another \a Read on the same stream since reads on the same stream + /// are delivered in order. /// /// \param[out] msg Where to eventually store the read message. /// \param[in] tag The tag identifying the operation. @@ -88,6 +96,7 @@ class AsyncWriterInterface { /// Only one write may be outstanding at any given time. This means that /// after calling Write, one must wait to receive \a tag from the completion /// queue BEFORE calling Write again. + /// This is thread-safe with respect to \a Read /// /// \param[in] msg The message to be written. /// \param[in] tag The tag identifying the operation. @@ -158,6 +167,7 @@ class ClientAsyncWriterInterface : public ClientAsyncStreamingInterface, public AsyncWriterInterface<W> { public: /// Signal the client is done with the writes. + /// Thread-safe with respect to \a Read /// /// \param[in] tag The tag identifying the operation. virtual void WritesDone(void* tag) = 0; @@ -229,6 +239,7 @@ class ClientAsyncReaderWriterInterface : public ClientAsyncStreamingInterface, public AsyncReaderInterface<R> { public: /// Signal the client is done with the writes. + /// Thread-safe with respect to \a Read /// /// \param[in] tag The tag identifying the operation. virtual void WritesDone(void* tag) = 0; diff --git a/include/grpc++/impl/codegen/client_context.h b/include/grpc++/impl/codegen/client_context.h index e23fd4eda3..a132c9a57a 100644 --- a/include/grpc++/impl/codegen/client_context.h +++ b/include/grpc++/impl/codegen/client_context.h @@ -193,7 +193,7 @@ class ClientContext { /// /// \return A multimap of initial metadata key-value pairs from the server. const std::multimap<grpc::string_ref, grpc::string_ref>& - GetServerInitialMetadata() { + GetServerInitialMetadata() const { GPR_CODEGEN_ASSERT(initial_metadata_received_); return recv_initial_metadata_; } @@ -205,7 +205,7 @@ class ClientContext { /// /// \return A multimap of metadata trailing key-value pairs from the server. const std::multimap<grpc::string_ref, grpc::string_ref>& - GetServerTrailingMetadata() { + GetServerTrailingMetadata() const { // TODO(yangg) check finished return trailing_metadata_; } @@ -230,13 +230,13 @@ class ClientContext { #ifndef GRPC_CXX0X_NO_CHRONO /// Return the deadline for the client call. - std::chrono::system_clock::time_point deadline() { + std::chrono::system_clock::time_point deadline() const { return Timespec2Timepoint(deadline_); } #endif // !GRPC_CXX0X_NO_CHRONO /// Return a \a gpr_timespec representation of the client call's deadline. - gpr_timespec raw_deadline() { return deadline_; } + gpr_timespec raw_deadline() const { return deadline_; } /// Set the per call authority header (see /// https://tools.ietf.org/html/rfc7540#section-8.1.2.3). @@ -337,7 +337,7 @@ class ClientContext { const InputMessage& request, OutputMessage* result); - grpc_call* call() { return call_; } + grpc_call* call() const { return call_; } void set_call(grpc_call* call, const std::shared_ptr<Channel>& channel); uint32_t initial_metadata_flags() const { diff --git a/include/grpc++/impl/codegen/completion_queue.h b/include/grpc++/impl/codegen/completion_queue.h index 1b84b44705..03009e0561 100644 --- a/include/grpc++/impl/codegen/completion_queue.h +++ b/include/grpc++/impl/codegen/completion_queue.h @@ -31,8 +31,19 @@ * */ -/// A completion queue implements a concurrent producer-consumer queue, with two -/// main methods, \a Next and \a AsyncNext. +/// A completion queue implements a concurrent producer-consumer queue, with +/// two main API-exposed methods: \a Next and \a AsyncNext. These +/// methods are the essential component of the gRPC C++ asynchronous API. +/// There is also a \a Shutdown method to indicate that a given completion queue +/// will no longer have regular events. This must be called before the +/// completion queue is destroyed. +/// All completion queue APIs are thread-safe and may be used concurrently with +/// any other completion queue API invocation; it is acceptable to have +/// multiple threads calling \a Next or \a AsyncNext on the same or different +/// completion queues, or to call these methods concurrently with a \a Shutdown +/// elsewhere. +/// \remark{All other API calls on completion queue should be completed before +/// a completion queue destructor is called.} #ifndef GRPCXX_IMPL_CODEGEN_COMPLETION_QUEUE_H #define GRPCXX_IMPL_CODEGEN_COMPLETION_QUEUE_H diff --git a/include/grpc++/impl/codegen/server_context.h b/include/grpc++/impl/codegen/server_context.h index a1e1ed176f..cea13a513f 100644 --- a/include/grpc++/impl/codegen/server_context.h +++ b/include/grpc++/impl/codegen/server_context.h @@ -94,12 +94,12 @@ class ServerContext { ~ServerContext(); #ifndef GRPC_CXX0X_NO_CHRONO - std::chrono::system_clock::time_point deadline() { + std::chrono::system_clock::time_point deadline() const { return Timespec2Timepoint(deadline_); } #endif // !GRPC_CXX0X_NO_CHRONO - gpr_timespec raw_deadline() { return deadline_; } + gpr_timespec raw_deadline() const { return deadline_; } void AddInitialMetadata(const grpc::string& key, const grpc::string& value); void AddTrailingMetadata(const grpc::string& key, const grpc::string& value); @@ -122,7 +122,8 @@ class ServerContext { // was called. void TryCancel() const; - const std::multimap<grpc::string_ref, grpc::string_ref>& client_metadata() { + const std::multimap<grpc::string_ref, grpc::string_ref>& client_metadata() + const { return client_metadata_; } diff --git a/include/grpc++/impl/codegen/sync_stream.h b/include/grpc++/impl/codegen/sync_stream.h index e94ffe5842..cbfa410699 100644 --- a/include/grpc++/impl/codegen/sync_stream.h +++ b/include/grpc++/impl/codegen/sync_stream.h @@ -71,6 +71,9 @@ class ReaderInterface { virtual ~ReaderInterface() {} /// Blocking read a message and parse to \a msg. Returns \a true on success. + /// This is thread-safe with respect to \a Write or \WritesDone methods on + /// the same stream. It should not be called concurrently with another \a + /// Read on the same stream as the order of delivery will not be defined. /// /// \param[out] msg The read message. /// @@ -87,6 +90,7 @@ class WriterInterface { virtual ~WriterInterface() {} /// Blocking write \a msg to the stream with options. + /// This is thread-safe with respect to \a Read /// /// \param msg The message to be written to the stream. /// \param options Options affecting the write operation. @@ -95,6 +99,7 @@ class WriterInterface { virtual bool Write(const W& msg, const WriteOptions& options) = 0; /// Blocking write \a msg to the stream with default options. + /// This is thread-safe with respect to \a Read /// /// \param msg The message to be written to the stream. /// @@ -174,7 +179,8 @@ class ClientWriterInterface : public ClientStreamingInterface, public WriterInterface<W> { public: /// Half close writing from the client. - /// Block until writes are completed. + /// Block until currently-pending writes are completed. + /// Thread safe with respect to \a Read operations only /// /// \return Whether the writes were successful. virtual bool WritesDone() = 0; @@ -257,7 +263,8 @@ class ClientReaderWriterInterface : public ClientStreamingInterface, /// the metadata will be available in ClientContext after the first read. virtual void WaitForInitialMetadata() = 0; - /// Block until writes are completed. + /// Block until currently-pending writes are completed. + /// Thread-safe with respect to \a Read /// /// \return Whether the writes were successful. virtual bool WritesDone() = 0; |