diff options
Diffstat (limited to 'include/grpc++/impl/codegen')
20 files changed, 70 insertions, 59 deletions
diff --git a/include/grpc++/impl/codegen/async_stream.h b/include/grpc++/impl/codegen/async_stream.h index f97d824baf..39f0ebd86f 100644 --- a/include/grpc++/impl/codegen/async_stream.h +++ b/include/grpc++/impl/codegen/async_stream.h @@ -155,7 +155,7 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface<R> { ClientAsyncReader(call, context, request, tag); } - // always allocated against a call arena, no memory free required + /// always allocated against a call arena, no memory free required static void operator delete(void* ptr, std::size_t size) { assert(size == sizeof(ClientAsyncReader)); } @@ -235,7 +235,7 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> { ClientAsyncWriter(call, context, response, tag); } - // always allocated against a call arena, no memory free required + /// always allocated against a call arena, no memory free required static void operator delete(void* ptr, std::size_t size) { assert(size == sizeof(ClientAsyncWriter)); } @@ -338,7 +338,7 @@ class ClientAsyncReaderWriter final ClientAsyncReaderWriter(call, context, tag); } - // always allocated against a call arena, no memory free required + /// always allocated against a call arena, no memory free required static void operator delete(void* ptr, std::size_t size) { assert(size == sizeof(ClientAsyncReaderWriter)); } diff --git a/include/grpc++/impl/codegen/async_unary_call.h b/include/grpc++/impl/codegen/async_unary_call.h index a147a6acbf..ea2da42198 100644 --- a/include/grpc++/impl/codegen/async_unary_call.h +++ b/include/grpc++/impl/codegen/async_unary_call.h @@ -71,7 +71,7 @@ class ClientAsyncResponseReader final ClientAsyncResponseReader(call, context, request); } - // always allocated against a call arena, no memory free required + /// always allocated against a call arena, no memory free required static void operator delete(void* ptr, std::size_t size) { assert(size == sizeof(ClientAsyncResponseReader)); } diff --git a/include/grpc++/impl/codegen/call.h b/include/grpc++/impl/codegen/call.h index 9fe2bbb75e..bbd0fc2dc8 100644 --- a/include/grpc++/impl/codegen/call.h +++ b/include/grpc++/impl/codegen/call.h @@ -634,10 +634,10 @@ class SneakyCallOpSet : public CallOpSet<Op1, Op2, Op3, Op4, Op5, Op6> { } }; -// Straightforward wrapping of the C call object +/// Straightforward wrapping of the C call object class Call final { public: - /* call is owned by the caller */ + /** call is owned by the caller */ Call(grpc_call* call, CallHook* call_hook, CompletionQueue* cq) : call_hook_(call_hook), cq_(cq), diff --git a/include/grpc++/impl/codegen/call_hook.h b/include/grpc++/impl/codegen/call_hook.h index 6a8258233d..812c4a91e7 100644 --- a/include/grpc++/impl/codegen/call_hook.h +++ b/include/grpc++/impl/codegen/call_hook.h @@ -39,7 +39,8 @@ namespace grpc { class CallOpSetInterface; class Call; -/// Channel and Server implement this to allow them to hook performing ops +/// An interface that Channel and Server implement to allow them to hook +/// performing ops class CallHook { public: virtual ~CallHook() {} diff --git a/include/grpc++/impl/codegen/client_context.h b/include/grpc++/impl/codegen/client_context.h index 3c50e6ba9d..c17ce20186 100644 --- a/include/grpc++/impl/codegen/client_context.h +++ b/include/grpc++/impl/codegen/client_context.h @@ -151,6 +151,7 @@ namespace testing { class InteropClientContextInspector; } // namespace testing +/// Gives access to client side RPC configuration. class ClientContext { public: ClientContext(); @@ -325,8 +326,8 @@ class ClientContext { }; static void SetGlobalCallbacks(GlobalCallbacks* callbacks); - // Should be used for framework-level extensions only. - // Applications never need to call this method. + /// Should be used for framework-level extensions only. + /// Applications never need to call this method. grpc_call* c_call() { return call_; } private: diff --git a/include/grpc++/impl/codegen/client_unary_call.h b/include/grpc++/impl/codegen/client_unary_call.h index 4bf35ae778..b923498db8 100644 --- a/include/grpc++/impl/codegen/client_unary_call.h +++ b/include/grpc++/impl/codegen/client_unary_call.h @@ -47,7 +47,7 @@ class ClientContext; class CompletionQueue; class RpcMethod; -// Wrapper that performs a blocking unary call +/// Wrapper that performs a blocking unary call template <class InputMessage, class OutputMessage> Status BlockingUnaryCall(ChannelInterface* channel, const RpcMethod& method, ClientContext* context, const InputMessage& request, diff --git a/include/grpc++/impl/codegen/completion_queue.h b/include/grpc++/impl/codegen/completion_queue.h index c8ab726b0f..57333d7158 100644 --- a/include/grpc++/impl/codegen/completion_queue.h +++ b/include/grpc++/impl/codegen/completion_queue.h @@ -159,7 +159,8 @@ class CompletionQueue : private GrpcLibraryCodegen { /// will start to return false and \a AsyncNext will return \a /// NextStatus::SHUTDOWN. Only once either one of these methods does that /// (that is, once the queue has been \em drained) can an instance of this - /// class be destroyed. + /// class be destroyed. Also note that applications must ensure that + /// no work is enqueued on this completion queue after this method is called. void Shutdown(); /// Returns a \em raw pointer to the underlying \a grpc_completion_queue diff --git a/include/grpc++/impl/codegen/completion_queue_tag.h b/include/grpc++/impl/codegen/completion_queue_tag.h index 19a08500cf..0affc818e8 100644 --- a/include/grpc++/impl/codegen/completion_queue_tag.h +++ b/include/grpc++/impl/codegen/completion_queue_tag.h @@ -40,10 +40,10 @@ namespace grpc { class CompletionQueueTag { public: virtual ~CompletionQueueTag() {} - // Called prior to returning from Next(), return value is the status of the - // operation (return status is the default thing to do). If this function - // returns false, the tag is dropped and not returned from the completion - // queue + /// Called prior to returning from Next(), return value is the status of the + /// operation (return status is the default thing to do). If this function + /// returns false, the tag is dropped and not returned from the completion + /// queue virtual bool FinalizeResult(void** tag, bool* status) = 0; }; diff --git a/include/grpc++/impl/codegen/config.h b/include/grpc++/impl/codegen/config.h index a43bf65f91..79352eee3c 100644 --- a/include/grpc++/impl/codegen/config.h +++ b/include/grpc++/impl/codegen/config.h @@ -39,9 +39,9 @@ #define GRPC_CUSTOM_STRING std::string #endif -// The following macros are deprecated and appear only for users -// with PB files generated using gRPC 1.0.x plugins. They should -// not be used in new code +/// The following macros are deprecated and appear only for users +/// with PB files generated using gRPC 1.0.x plugins. They should +/// not be used in new code #define GRPC_OVERRIDE override // deprecated #define GRPC_FINAL final // deprecated diff --git a/include/grpc++/impl/codegen/method_handler_impl.h b/include/grpc++/impl/codegen/method_handler_impl.h index 83b569ce74..8dfaf5883c 100644 --- a/include/grpc++/impl/codegen/method_handler_impl.h +++ b/include/grpc++/impl/codegen/method_handler_impl.h @@ -40,7 +40,7 @@ namespace grpc { -// A wrapper class of an application provided rpc method handler. +/// A wrapper class of an application provided rpc method handler. template <class ServiceType, class RequestType, class ResponseType> class RpcMethodHandler : public MethodHandler { public: @@ -77,7 +77,7 @@ class RpcMethodHandler : public MethodHandler { } private: - // Application provided rpc handler function. + /// Application provided rpc handler function. std::function<Status(ServiceType*, ServerContext*, const RequestType*, ResponseType*)> func_; @@ -85,7 +85,7 @@ class RpcMethodHandler : public MethodHandler { ServiceType* service_; }; -// A wrapper class of an application provided client streaming handler. +/// A wrapper class of an application provided client streaming handler. template <class ServiceType, class RequestType, class ResponseType> class ClientStreamingHandler : public MethodHandler { public: @@ -125,7 +125,7 @@ class ClientStreamingHandler : public MethodHandler { ServiceType* service_; }; -// A wrapper class of an application provided server streaming handler. +/// A wrapper class of an application provided server streaming handler. template <class ServiceType, class RequestType, class ResponseType> class ServerStreamingHandler : public MethodHandler { public: @@ -166,13 +166,13 @@ class ServerStreamingHandler : public MethodHandler { ServiceType* service_; }; -// A wrapper class of an application provided bidi-streaming handler. -// This also applies to server-streamed implementation of a unary method -// with the additional requirement that such methods must have done a -// write for status to be ok -// Since this is used by more than 1 class, the service is not passed in. -// Instead, it is expected to be an implicitly-captured argument of func -// (through bind or something along those lines) +/// A wrapper class of an application provided bidi-streaming handler. +/// This also applies to server-streamed implementation of a unary method +/// with the additional requirement that such methods must have done a +/// write for status to be ok +/// Since this is used by more than 1 class, the service is not passed in. +/// Instead, it is expected to be an implicitly-captured argument of func +/// (through bind or something along those lines) template <class Streamer, bool WriteNeeded> class TemplatedBidiStreamingHandler : public MethodHandler { public: @@ -249,7 +249,7 @@ class SplitServerStreamingHandler ServerSplitStreamer<RequestType, ResponseType>, false>(func) {} }; -// Handle unknown method by returning UNIMPLEMENTED error. +/// Handle unknown method by returning UNIMPLEMENTED error. class UnknownMethodHandler : public MethodHandler { public: template <class T> diff --git a/include/grpc++/impl/codegen/rpc_method.h b/include/grpc++/impl/codegen/rpc_method.h index 4897428074..ca7527507c 100644 --- a/include/grpc++/impl/codegen/rpc_method.h +++ b/include/grpc++/impl/codegen/rpc_method.h @@ -40,6 +40,7 @@ namespace grpc { +/// Descriptor of an RPC method class RpcMethod { public: enum RpcType { diff --git a/include/grpc++/impl/codegen/rpc_service_method.h b/include/grpc++/impl/codegen/rpc_service_method.h index eb8f9a1096..96bb739c99 100644 --- a/include/grpc++/impl/codegen/rpc_service_method.h +++ b/include/grpc++/impl/codegen/rpc_service_method.h @@ -52,7 +52,7 @@ namespace grpc { class ServerContext; class StreamContextInterface; -// Base class for running an RPC handler. +/// Base class for running an RPC handler. class MethodHandler { public: virtual ~MethodHandler() {} @@ -67,17 +67,17 @@ class MethodHandler { virtual void RunHandler(const HandlerParameter& param) = 0; }; -// Server side rpc method class +/// Server side rpc method class class RpcServiceMethod : public RpcMethod { public: - // Takes ownership of the handler + /// Takes ownership of the handler RpcServiceMethod(const char* name, RpcMethod::RpcType type, MethodHandler* handler) : RpcMethod(name, type), server_tag_(nullptr), handler_(handler) {} void set_server_tag(void* tag) { server_tag_ = tag; } void* server_tag() const { return server_tag_; } - // if MethodHandler is nullptr, then this is an async method + /// if MethodHandler is nullptr, then this is an async method MethodHandler* handler() const { return handler_.get(); } void ResetHandler() { handler_.reset(); } void SetHandler(MethodHandler* handler) { handler_.reset(handler); } diff --git a/include/grpc++/impl/codegen/security/auth_context.h b/include/grpc++/impl/codegen/security/auth_context.h index 75f2482346..e83877bcaf 100644 --- a/include/grpc++/impl/codegen/security/auth_context.h +++ b/include/grpc++/impl/codegen/security/auth_context.h @@ -99,7 +99,7 @@ class AuthContext { virtual AuthPropertyIterator begin() const = 0; virtual AuthPropertyIterator end() const = 0; - // Mutation functions: should only be used by an AuthMetadataProcessor. + /// Mutation functions: should only be used by an AuthMetadataProcessor. virtual void AddProperty(const grpc::string& key, const grpc::string_ref& value) = 0; virtual bool SetPeerIdentityPropertyName(const grpc::string& name) = 0; diff --git a/include/grpc++/impl/codegen/server_context.h b/include/grpc++/impl/codegen/server_context.h index ada304d571..07e3710b4b 100644 --- a/include/grpc++/impl/codegen/server_context.h +++ b/include/grpc++/impl/codegen/server_context.h @@ -91,7 +91,7 @@ class InteropServerContextInspector; class ServerContextTestSpouse; } // namespace testing -// Interface of server side rpc context. +/// Interface of server side rpc context. class ServerContext { public: ServerContext(); // for async calls @@ -106,9 +106,9 @@ class ServerContext { void AddInitialMetadata(const grpc::string& key, const grpc::string& value); void AddTrailingMetadata(const grpc::string& key, const grpc::string& value); - // IsCancelled is always safe to call when using sync API - // When using async API, it is only safe to call IsCancelled after - // the AsyncNotifyWhenDone tag has been delivered + /// IsCancelled is always safe to call when using sync API + /// When using async API, it is only safe to call IsCancelled after + /// the AsyncNotifyWhenDone tag has been delivered bool IsCancelled() const; // Cancel the Call from the server. This is a best-effort API and depending on diff --git a/include/grpc++/impl/codegen/service_type.h b/include/grpc++/impl/codegen/service_type.h index bd65ea009e..0df90678b1 100644 --- a/include/grpc++/impl/codegen/service_type.h +++ b/include/grpc++/impl/codegen/service_type.h @@ -61,6 +61,7 @@ class ServerAsyncStreamingInterface { virtual void BindCall(Call* call) = 0; }; +/// Desriptor of an RPC service and its various RPC methods class Service { public: Service() : server_(nullptr) {} diff --git a/include/grpc++/impl/codegen/status_code_enum.h b/include/grpc++/impl/codegen/status_code_enum.h index 9a90a18e2a..2eb97e83c1 100644 --- a/include/grpc++/impl/codegen/status_code_enum.h +++ b/include/grpc++/impl/codegen/status_code_enum.h @@ -136,6 +136,12 @@ enum StatusCode { /// The service is currently unavailable. This is a most likely a transient /// condition and may be corrected by retrying with a backoff. /// + /// \warning: Although data MIGHT not have been transmitted when this + /// status occurs, there is NOT A GUARANTEE that the server has not seen + /// anything. So in general it is unsafe to retry on this status code + /// if the call is non-idempotent. + /// + /// /// See litmus test above for deciding between FAILED_PRECONDITION, ABORTED, /// and UNAVAILABLE. UNAVAILABLE = 14, diff --git a/include/grpc++/impl/codegen/string_ref.h b/include/grpc++/impl/codegen/string_ref.h index 003793823c..4ed11b1b6c 100644 --- a/include/grpc++/impl/codegen/string_ref.h +++ b/include/grpc++/impl/codegen/string_ref.h @@ -55,14 +55,14 @@ namespace grpc { /// compatibility. class string_ref { public: - // types + /// types typedef const char* const_iterator; typedef std::reverse_iterator<const_iterator> const_reverse_iterator; - // constants + /// constants const static size_t npos; - // construct/copy. + /// construct/copy. string_ref() : data_(nullptr), length_(0) {} string_ref(const string_ref& other) : data_(other.data_), length_(other.length_) {} @@ -76,7 +76,7 @@ class string_ref { string_ref(const char* s, size_t l) : data_(s), length_(l) {} string_ref(const grpc::string& s) : data_(s.data()), length_(s.length()) {} - // iterators + /// iterators const_iterator begin() const { return data_; } const_iterator end() const { return data_ + length_; } const_iterator cbegin() const { return data_; } @@ -94,16 +94,16 @@ class string_ref { return const_reverse_iterator(begin()); } - // capacity + /// capacity size_t size() const { return length_; } size_t length() const { return length_; } size_t max_size() const { return length_; } bool empty() const { return length_ == 0; } - // element access + /// element access const char* data() const { return data_; } - // string operations + /// string operations int compare(string_ref x) const { size_t min_size = length_ < x.length_ ? length_ : x.length_; int r = memcmp(data_, x.data_, min_size); @@ -144,7 +144,7 @@ class string_ref { size_t length_; }; -// Comparison operators +/// Comparison operators inline bool operator==(string_ref x, string_ref y) { return x.compare(y) == 0; } inline bool operator!=(string_ref x, string_ref y) { return x.compare(y) != 0; } inline bool operator<(string_ref x, string_ref y) { return x.compare(y) < 0; } diff --git a/include/grpc++/impl/codegen/stub_options.h b/include/grpc++/impl/codegen/stub_options.h index 8e966a8dbf..41aef19ab0 100644 --- a/include/grpc++/impl/codegen/stub_options.h +++ b/include/grpc++/impl/codegen/stub_options.h @@ -36,6 +36,7 @@ namespace grpc { +/// Useful interface for generated stubs class StubOptions {}; } // namespace grpc diff --git a/include/grpc++/impl/codegen/sync_stream.h b/include/grpc++/impl/codegen/sync_stream.h index a010924cef..34b814e9e3 100644 --- a/include/grpc++/impl/codegen/sync_stream.h +++ b/include/grpc++/impl/codegen/sync_stream.h @@ -516,7 +516,7 @@ class ServerReaderWriterInterface : public ServerStreamingInterface, public WriterInterface<W>, public ReaderInterface<R> {}; -// Actual implementation of bi-directional streaming +/// Actual implementation of bi-directional streaming namespace internal { template <class W, class R> class ServerReaderWriterBody final { @@ -576,7 +576,7 @@ class ServerReaderWriterBody final { }; } // namespace internal -// class to represent the user API for a bidirectional streaming call +/// class to represent the user API for a bidirectional streaming call template <class W, class R> class ServerReaderWriter final : public ServerReaderWriterInterface<W, R> { public: diff --git a/include/grpc++/impl/codegen/time.h b/include/grpc++/impl/codegen/time.h index e090ece756..81ca7bb3de 100644 --- a/include/grpc++/impl/codegen/time.h +++ b/include/grpc++/impl/codegen/time.h @@ -39,17 +39,16 @@ namespace grpc { -/* If you are trying to use CompletionQueue::AsyncNext with a time class that - isn't either gpr_timespec or std::chrono::system_clock::time_point, you - will most likely be looking at this comment as your compiler will have - fired an error below. In order to fix this issue, you have two potential - solutions: - - 1. Use gpr_timespec or std::chrono::system_clock::time_point instead - 2. Specialize the TimePoint class with whichever time class that you - want to use here. See below for two examples of how to do this. +/** If you are trying to use CompletionQueue::AsyncNext with a time class that + isn't either gpr_timespec or std::chrono::system_clock::time_point, you + will most likely be looking at this comment as your compiler will have + fired an error below. In order to fix this issue, you have two potential + solutions: + + 1. Use gpr_timespec or std::chrono::system_clock::time_point instead + 2. Specialize the TimePoint class with whichever time class that you + want to use here. See below for two examples of how to do this. */ - template <typename T> class TimePoint { public: |