diff options
Diffstat (limited to 'include')
69 files changed, 1211 insertions, 595 deletions
diff --git a/include/grpc++/ext/health_check_service_server_builder_option.h b/include/grpc++/ext/health_check_service_server_builder_option.h index 4861daacd4..a27841af01 100644 --- a/include/grpc++/ext/health_check_service_server_builder_option.h +++ b/include/grpc++/ext/health_check_service_server_builder_option.h @@ -44,8 +44,8 @@ namespace grpc { class HealthCheckServiceServerBuilderOption : public ServerBuilderOption { public: - // The ownership of hc will be taken and transferred to the grpc server. - // To explicitly disable default service, pass in a nullptr. + /// The ownership of hc will be taken and transferred to the grpc server. + /// To explicitly disable default service, pass in a nullptr. explicit HealthCheckServiceServerBuilderOption( std::unique_ptr<HealthCheckServiceInterface> hc); ~HealthCheckServiceServerBuilderOption() override {} diff --git a/include/grpc++/ext/proto_server_reflection_plugin.h b/include/grpc++/ext/proto_server_reflection_plugin.h index 66f39eb876..6497bba905 100644 --- a/include/grpc++/ext/proto_server_reflection_plugin.h +++ b/include/grpc++/ext/proto_server_reflection_plugin.h @@ -59,8 +59,8 @@ class ProtoServerReflectionPlugin : public ::grpc::ServerBuilderPlugin { std::shared_ptr<grpc::ProtoServerReflection> reflection_service_; }; -// Add proto reflection plugin to ServerBuilder. This function should be called -// at the static initialization time. +/// Add proto reflection plugin to ServerBuilder. This function should be called +/// at the static initialization time. void InitProtoReflectionServerBuilderPlugin(); } // namespace reflection diff --git a/include/grpc++/generic/generic_stub.h b/include/grpc++/generic/generic_stub.h index 02c00d0d45..1478846fc8 100644 --- a/include/grpc++/generic/generic_stub.h +++ b/include/grpc++/generic/generic_stub.h @@ -43,14 +43,18 @@ class CompletionQueue; typedef ClientAsyncReaderWriter<ByteBuffer, ByteBuffer> GenericClientAsyncReaderWriter; -// Generic stubs provide a type-unsafe interface to call gRPC methods -// by name. +/// Generic stubs provide a type-unsafe interface to call gRPC methods +/// by name. class GenericStub final { public: explicit GenericStub(std::shared_ptr<ChannelInterface> channel) : channel_(channel) {} - // begin a call to a named method + /// Begin a call to a named method \a method using \a context. + /// A tag \a tag will be delivered to \a cq when the call has been started + /// (i.e, initial metadata has been sent). + /// The return value only indicates whether or not registration of the call + /// succeeded (i.e. the call won't proceed if the return value is nullptr). std::unique_ptr<GenericClientAsyncReaderWriter> Call( ClientContext* context, const grpc::string& method, CompletionQueue* cq, void* tag); diff --git a/include/grpc++/grpc++.h b/include/grpc++/grpc++.h index daecfea406..978b172346 100644 --- a/include/grpc++/grpc++.h +++ b/include/grpc++/grpc++.h @@ -34,14 +34,18 @@ /// \mainpage gRPC C++ API /// /// The gRPC C++ API mainly consists of the following classes: +// /// - grpc::Channel, which represents the connection to an endpoint. See [the /// gRPC Concepts page](http://www.grpc.io/docs/guides/concepts.html) for more /// details. Channels are created by the factory function grpc::CreateChannel. +// /// - grpc::CompletionQueue, the producer-consumer queue used for all /// asynchronous communication with the gRPC runtime. +// /// - grpc::ClientContext and grpc::ServerContext, where optional configuration /// for an RPC can be set, such as setting custom metadata to be conveyed to the /// peer, compression settings, authentication, etc. +// /// - grpc::Server, representing a gRPC server, created by grpc::ServerBuilder. /// /// Streaming calls are handled with the streaming classes in diff --git a/include/grpc++/health_check_service_interface.h b/include/grpc++/health_check_service_interface.h index 0eed702683..c1b43199a6 100644 --- a/include/grpc++/health_check_service_interface.h +++ b/include/grpc++/health_check_service_interface.h @@ -41,26 +41,27 @@ namespace grpc { const char kHealthCheckServiceInterfaceArg[] = "grpc.health_check_service_interface"; -// The gRPC server uses this interface to expose the health checking service -// without depending on protobuf. +/// The gRPC server uses this interface to expose the health checking service +/// without depending on protobuf. class HealthCheckServiceInterface { public: virtual ~HealthCheckServiceInterface() {} - // Set or change the serving status of the given service_name. + /// Set or change the serving status of the given service_name. virtual void SetServingStatus(const grpc::string& service_name, bool serving) = 0; - // Apply to all registered service names. + /// Apply to all registered service names. virtual void SetServingStatus(bool serving) = 0; }; -// Enable/disable the default health checking service. This applies to all C++ -// servers created afterwards. For each server, user can override the default -// with a HealthCheckServiceServerBuilderOption. -// NOT thread safe. +/// Enable/disable the default health checking service. This applies to all C++ +/// servers created afterwards. For each server, user can override the default +/// with a HealthCheckServiceServerBuilderOption. +/// NOT thread safe. void EnableDefaultHealthCheckService(bool enable); -// NOT thread safe. +/// Returns whether the default health checking service is enabled. +/// NOT thread safe. bool DefaultHealthCheckServiceEnabled(); } // namespace grpc diff --git a/include/grpc++/impl/codegen/async_stream.h b/include/grpc++/impl/codegen/async_stream.h index f97d824baf..04fc5241cb 100644 --- a/include/grpc++/impl/codegen/async_stream.h +++ b/include/grpc++/impl/codegen/async_stream.h @@ -53,16 +53,38 @@ 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. + /// with or after the \a AsyncReaderInterface::Read method. /// /// \param[in] tag Tag identifying this request. virtual void ReadInitialMetadata(void* tag) = 0; - /// Indicate that the stream is to be finished and request notification - /// Should not be used concurrently with other operations + /// Indicate that the stream is to be finished and request notification for + /// when the call has been ended. + /// 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 + /// \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, e.g. cq->Next(&read_tag, &ok) filled in 'ok' with 'false'). + /// + /// This function will return when either: + /// - all incoming messages have been read and the server has returned + /// a status. + /// - the server has returned a non-OK status. + /// - 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. /// - /// \param[out] status To be updated with the operation status. /// \param[in] tag Tag identifying this request. + /// \param[out] status To be updated with the operation status. virtual void Finish(Status* status, void* tag) = 0; }; @@ -77,11 +99,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 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. virtual void Read(R* msg, void* tag) = 0; }; @@ -96,7 +121,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 + /// This is thread-safe with respect to \a AsyncReaderInterface::Read /// /// \param[in] msg The message to be written. /// \param[in] tag The tag identifying the operation. @@ -109,7 +134,7 @@ class AsyncWriterInterface { /// after calling Write, one must wait to receive \a tag from the completion /// queue BEFORE calling Write again. /// WriteOptions \a options is used to set the write options of this message. - /// This is thread-safe with respect to \a Read + /// This is thread-safe with respect to \a AsyncReaderInterface::Read /// /// \param[in] msg The message to be written. /// \param[in] options The WriteOptions to be used to write this message. @@ -117,11 +142,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 @@ -140,10 +165,17 @@ template <class R> 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. template <class R> class ClientAsyncReader final : public ClientAsyncReaderInterface<R> { public: /// Create a stream and write the first request out. + /// \a tag will be notified on \a cq when the call has been started and + /// \a request has been written 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> static ClientAsyncReader* Create(ChannelInterface* channel, CompletionQueue* cq, const RpcMethod& method, @@ -160,6 +192,14 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface<R> { assert(size == sizeof(ClientAsyncReader)); } + /// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata + /// method for 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. void ReadInitialMetadata(void* tag) override { GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_); @@ -177,6 +217,11 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface<R> { call_.PerformOps(&read_ops_); } + /// See the \a ClientAsyncStreamingInterface.Finish method for semantics. + /// + /// Side effect: + /// - the \a ClientContext associated with this call is updated with + /// possible initial and trailing metadata received from the server. void Finish(Status* status, void* tag) override { finish_ops_.set_output_tag(tag); if (!context_->initial_metadata_received_) { @@ -214,16 +259,27 @@ template <class W> class ClientAsyncWriterInterface : public ClientAsyncStreamingInterface, public AsyncWriterInterface<W> { public: - /// Signal the client is done with the writes. - /// Thread-safe with respect to \a Read + /// Signal the client is done with the writes (half-close the client stream). + /// Thread-safe with respect to \a AsyncReaderInterface::Read /// /// \param[in] tag The tag identifying the operation. virtual void WritesDone(void* tag) = 0; }; +/// 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. template <class W> class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> { public: + /// Create a stream and write the first request out. + /// \a tag will be notified on \a cq when the call has been started (i.e. + /// intitial metadata sent) and \a request has been written out. + /// Note that \a context will be used to fill in custom initial metadata + /// used to send to the server when starting the call. + /// \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> static ClientAsyncWriter* Create(ChannelInterface* channel, CompletionQueue* cq, const RpcMethod& method, @@ -240,6 +296,13 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> { assert(size == sizeof(ClientAsyncWriter)); } + /// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata method for + /// 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. void ReadInitialMetadata(void* tag) override { GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_); @@ -272,6 +335,13 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> { call_.PerformOps(&write_ops_); } + /// See the \a ClientAsyncStreamingInterface.Finish method for semantics. + /// + /// Side effect: + /// - the \a ClientContext associated with this call is updated with + /// possible initial and trailing metadata received from the server. + /// - attempts to fill in the \a response parameter passed to this class's + /// constructor with the server's response message. void Finish(Status* status, void* tag) override { finish_ops_.set_output_tag(tag); if (!context_->initial_metadata_received_) { @@ -310,23 +380,34 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> { finish_ops_; }; -/// Client-side interface for asynchronous bi-directional streaming. +/// Async client-side interface for bi-directional streaming, +/// where the client-to-server message stream has messages of type \a W, +/// and the server-to-client message stream has messages of type \a R. template <class W, class R> class ClientAsyncReaderWriterInterface : public ClientAsyncStreamingInterface, public AsyncWriterInterface<W>, public AsyncReaderInterface<R> { public: - /// Signal the client is done with the writes. - /// Thread-safe with respect to \a Read + /// Signal the client is done with the writes (half-close the client stream). + /// Thread-safe with respect to \a AsyncReaderInterface::Read /// /// \param[in] tag The tag identifying the operation. virtual void WritesDone(void* tag) = 0; }; +/// 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. template <class W, class R> class ClientAsyncReaderWriter final : public ClientAsyncReaderWriterInterface<W, R> { public: + /// Create a stream and write the first request out. + /// \a tag will be notified on \a cq when the call has been started (i.e. + /// intitial metadata sent). + /// Note that \a context will be used to fill in custom initial metadata + /// used to send to the server when starting the call. static ClientAsyncReaderWriter* Create(ChannelInterface* channel, CompletionQueue* cq, const RpcMethod& method, @@ -343,6 +424,13 @@ class ClientAsyncReaderWriter final assert(size == sizeof(ClientAsyncReaderWriter)); } + /// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata method + /// for semantics of this method. + /// + /// 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. void ReadInitialMetadata(void* tag) override { GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_); @@ -384,6 +472,10 @@ class ClientAsyncReaderWriter final call_.PerformOps(&write_ops_); } + /// See the \a ClientAsyncStreamingInterface.Finish method for semantics. + /// Side effect + /// - the \a ClientContext associated with this call is updated with + /// possible initial and trailing metadata sent from the server. void Finish(Status* status, void* tag) override { finish_ops_.set_output_tag(tag); if (!context_->initial_metadata_received_) { @@ -422,17 +514,62 @@ template <class W, class R> class ServerAsyncReaderInterface : public ServerAsyncStreamingInterface, public AsyncReaderInterface<R> { 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. + /// 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'). + /// + /// 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. + /// 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. + /// + /// This call is meant to end the call with some error, and can be called at + /// any point that the server would like to "fail" the call (though note + /// 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. + /// + /// \param[in] tag Tag identifying this request. + /// \param[in] status To be sent to the client as the result of this call. + /// - Note: \a status must have a non-OK code. virtual void FinishWithError(const Status& status, void* tag) = 0; }; +/// Async server-side API for doing client-streaming RPCs, +/// where the incoming message stream from the client has messages of type \a R, +/// and the single response message sent from the server is type \a W. template <class W, class R> class ServerAsyncReader final : public ServerAsyncReaderInterface<W, R> { public: explicit ServerAsyncReader(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} + /// 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. void SendInitialMetadata(void* tag) override { GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_); @@ -452,6 +589,14 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface<W, R> { call_.PerformOps(&read_ops_); } + /// See the \a ServerAsyncReaderInterface.Read method for semantics + /// + /// Side effect: + /// - also sends initial metadata if not alreay sent. + /// - uses the \a ServerContext associated with this call to send possible + /// initial and trailing metadata. + /// + /// Note: \a msg is not sent if \a status has a non-OK code. void Finish(const W& msg, const Status& status, void* tag) override { finish_ops_.set_output_tag(tag); if (!ctx_->sent_initial_metadata_) { @@ -472,6 +617,12 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface<W, R> { call_.PerformOps(&finish_ops_); } + /// See the \a ServerAsyncReaderInterface.Read method for semantics + /// + /// Side effect: + /// - also sends initial metadata if not alreay sent. + /// - uses the \a ServerContext associated with this call to send possible + /// initial and trailing metadata. void FinishWithError(const Status& status, void* tag) override { GPR_CODEGEN_ASSERT(!status.ok()); finish_ops_.set_output_tag(tag); @@ -503,14 +654,32 @@ template <class W> class ServerAsyncWriterInterface : public ServerAsyncStreamingInterface, public AsyncWriterInterface<W> { public: + /// Indicate that the stream is to be finished with a certain 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. + /// + /// 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'. + /// * 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. + /// + /// \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. @@ -520,12 +689,21 @@ class ServerAsyncWriterInterface : public ServerAsyncStreamingInterface, const Status& status, void* tag) = 0; }; +/// Async server-side API for doing server streaming RPCs, +/// where the outgoing message stream from the server has messages of type \a W. template <class W> class ServerAsyncWriter final : public ServerAsyncWriterInterface<W> { public: explicit ServerAsyncWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} + /// 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. + /// + /// \param[in] tag Tag identifying this request. void SendInitialMetadata(void* tag) override { GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_); @@ -559,6 +737,13 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface<W> { call_.PerformOps(&write_ops_); } + /// See the \a ServerAsyncWriterInterface.WriteAndFinish method for semantics. + /// + /// Implicit input parameter: + /// - the \a ServerContext associated with this call is used + /// for sending trailing (and initial) metadata to the client. + /// + /// Note: \a status must have an OK code. void WriteAndFinish(const W& msg, WriteOptions options, const Status& status, void* tag) override { write_ops_.set_output_tag(tag); @@ -569,6 +754,14 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface<W> { call_.PerformOps(&write_ops_); } + /// 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. + /// + /// 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_); @@ -606,11 +799,30 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface, public AsyncWriterInterface<W>, public AsyncReaderInterface<R> { public: + /// Indicate that the stream is to be finished with a certain 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. + /// + /// 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'. + /// * 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. + /// + /// \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. @@ -623,6 +835,10 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface, const Status& status, void* tag) = 0; }; +/// 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. template <class W, class R> class ServerAsyncReaderWriter final : public ServerAsyncReaderWriterInterface<W, R> { @@ -630,6 +846,13 @@ class ServerAsyncReaderWriter final explicit ServerAsyncReaderWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} + /// 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. + /// + /// \param[in] tag Tag identifying this request. void SendInitialMetadata(void* tag) override { GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_); @@ -667,6 +890,14 @@ class ServerAsyncReaderWriter final call_.PerformOps(&write_ops_); } + /// See the \a ServerAsyncReaderWriterInterface.WriteAndFinish + /// method for semantics. + /// + /// Implicit input parameter: + /// - the \a ServerContext associated with this call is used + /// for sending trailing (and initial) metadata to the client. + /// + /// Note: \a status must have an OK code. void WriteAndFinish(const W& msg, WriteOptions options, const Status& status, void* tag) override { write_ops_.set_output_tag(tag); @@ -677,6 +908,14 @@ class ServerAsyncReaderWriter final call_.PerformOps(&write_ops_); } + /// 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. + /// + /// 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 a147a6acbf..aadf77d8a8 100644 --- a/include/grpc++/impl/codegen/async_unary_call.h +++ b/include/grpc++/impl/codegen/async_unary_call.h @@ -47,18 +47,49 @@ namespace grpc { class CompletionQueue; extern CoreCodegenInterface* g_core_codegen_interface; +/// An interface relevant for async client side unary RPCS (which send +/// one request message to a server and receive one response message). template <class R> class ClientAsyncResponseReaderInterface { public: virtual ~ClientAsyncResponseReaderInterface() {} + + /// Request notification of the reading of 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 Finish method. + /// + /// \param[in] tag Tag identifying this request. virtual void ReadInitialMetadata(void* tag) = 0; + + /// Request to receive the server's response \a msg and final \a status for + /// the call, and to notify \a tag on this call's completion queue when + /// finished. + /// + /// This function will return when either: + /// - when the server's response message and status have been received. + /// - when the server has returned a non-OK status (no message expected in + /// this case). + /// - when the call failed for some reason and the library generated a + /// non-OK status. + /// + /// \param[in] tag Tag identifying this request. + /// \param[out] status To be updated with the operation status. + /// \param[out] msg To be filled in with the server's response message. virtual void Finish(R* msg, Status* status, void* tag) = 0; }; +/// Async API for client-side unary RPCs, where the message response +/// received from the server is of type \a R. template <class R> class ClientAsyncResponseReader final : public ClientAsyncResponseReaderInterface<R> { public: + /// Start a call and write the request out. + /// \a tag will be notified on \a cq when the call has been started (i.e. + /// intitial metadata sent) and \a request has been written 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> static ClientAsyncResponseReader* Create(ChannelInterface* channel, CompletionQueue* cq, @@ -76,6 +107,12 @@ class ClientAsyncResponseReader final assert(size == sizeof(ClientAsyncResponseReader)); } + /// See \a ClientAsyncResponseReaderInterface::ReadInitialMetadata for + /// semantics. + /// + /// Side effect: + /// - the \a ClientContext associated with this call is updated with + /// possible initial and trailing metadata sent from the serve. void ReadInitialMetadata(void* tag) { GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_); @@ -84,6 +121,11 @@ class ClientAsyncResponseReader final call_.PerformOps(&meta_buf_); } + /// See \a ClientAysncResponseReaderInterface::Finish for semantics. + /// + /// Side effect: + /// - the \a ClientContext associated with this call is updated with + /// possible initial and trailing metadata sent from the server. void Finish(R* msg, Status* status, void* tag) { finish_buf_.set_output_tag(tag); if (!context_->initial_metadata_received_) { @@ -123,12 +165,21 @@ class ClientAsyncResponseReader final finish_buf_; }; +/// Async server-side API for handling unary calls, where the single +/// response message sent to the client is of type \a W. template <class W> class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { public: explicit ServerAsyncResponseWriter(ServerContext* ctx) : call_(nullptr, nullptr, nullptr), ctx_(ctx) {} + /// 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. + /// + /// \param[in] tag Tag identifying this request. void SendInitialMetadata(void* tag) override { GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_); @@ -142,6 +193,21 @@ class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { call_.PerformOps(&meta_buf_); } + /// 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. + /// + /// \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). + /// + /// Note: if \a status has a non-OK code, then \a msg will not be sent, + /// and the client will receive only the status with possible trailing + /// metadata. void Finish(const W& msg, const Status& status, void* tag) { finish_buf_.set_output_tag(tag); if (!ctx_->sent_initial_metadata_) { @@ -162,6 +228,18 @@ class ServerAsyncResponseWriter final : public ServerAsyncStreamingInterface { call_.PerformOps(&finish_buf_); } + /// Indicate that the stream is to be finished with a non-OK status, + /// and request notification for when the server has finished sending the + /// appropriate signals to the client to 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. + /// - 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). void FinishWithError(const Status& status, void* tag) { GPR_CODEGEN_ASSERT(!status.ok()); finish_buf_.set_output_tag(tag); 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..85a5f86ab7 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 +/// This is 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..b1b9be0fe2 100644 --- a/include/grpc++/impl/codegen/client_context.h +++ b/include/grpc++/impl/codegen/client_context.h @@ -151,6 +151,20 @@ namespace testing { class InteropClientContextInspector; } // namespace testing +/// A ClientContext allows the person implementing a service client to: +/// +/// - Add custom metadata key-value pairs that will propagated to the server +/// side. +/// - Control call settings such as compression and authentication. +/// - Initial and trailing metadata coming from the server. +/// - Get performance metrics (ie, census). +/// +/// Context settings are only relevant to the call they are invoked with, that +/// is to say, they aren't sticky. Some of these settings, such as the +/// compression options, can be made persistant at channel construction time +/// (see \a grpc::CreateCustomChannel). +/// +/// \warning ClientContext instances should \em not be reused across rpcs. class ClientContext { public: ClientContext(); @@ -178,9 +192,8 @@ class ClientContext { /// /// \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 - /// base64-encoding (see https://tools.ietf.org/html/rfc4648#section-4) and \a - /// meta_key must end in "-bin". + /// \param meta_value The metadata value. If its value is binary, the key name + /// must end in "-bin". void AddMetadata(const grpc::string& meta_key, const grpc::string& meta_value); @@ -222,13 +235,24 @@ class ClientContext { deadline_ = deadline_tp.raw_time(); } - /// EXPERIMENTAL: Set this request to be idempotent + /// EXPERIMENTAL: Indicate that this request is idempotent. + /// By default, RPCs are assumed to <i>not</i> be idempotent. + /// + /// If true, the gRPC library assumes that it's safe to initiate + /// this RPC multiple times. void set_idempotent(bool idempotent) { idempotent_ = idempotent; } - /// EXPERIMENTAL: Set this request to be cacheable + /// EXPERIMENTAL: Set this request to be cacheable. + /// If set, grpc is free to use the HTTP GET verb for sending the request, + /// with the possibility of receiving a cached respone. void set_cacheable(bool cacheable) { cacheable_ = cacheable; } - /// EXPERIMENTAL: Trigger wait-for-ready or not on this request + /// EXPERIMENTAL: Trigger wait-for-ready or not on this request. + /// See https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md. + /// If set, if an RPC is made when a channel's connectivity state is + /// TRANSIENT_FAILURE or CONNECTING, the call will not "fail fast", + /// and the channel will wait until the channel is READY before making the + /// call. void set_wait_for_ready(bool wait_for_ready) { wait_for_ready_ = wait_for_ready; wait_for_ready_explicitly_set_ = true; @@ -325,8 +349,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..48967c2e68 100644 --- a/include/grpc++/impl/codegen/server_context.h +++ b/include/grpc++/impl/codegen/server_context.h @@ -91,63 +91,128 @@ class InteropServerContextInspector; class ServerContextTestSpouse; } // namespace testing -// Interface of server side rpc context. +/// 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. +/// - 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 +/// to a \a grpc::ServerBuilder, via \a ServerBuilder::AddChannelArgument. +/// +/// \warning ServerContext instances should \em not be reused across rpcs. class ServerContext { public: ServerContext(); // for async calls ~ServerContext(); + /// Return the deadline for the server call. std::chrono::system_clock::time_point deadline() const { return Timespec2Timepoint(deadline_); } + /// 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. + /// + /// \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, the key name + /// 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. + /// + /// \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, the key name + /// must end in "-bin". 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 - // 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. + /// 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. 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). + /// + /// 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 + /// safe to access as soon as the call has begun on the server side. + /// + /// \return A multimap of initial metadata key-value pairs from the server. const std::multimap<grpc::string_ref, grpc::string_ref>& client_metadata() const { return *client_metadata_.map(); } + /// Return the compression algorithm to be used by the server call. grpc_compression_level compression_level() const { return compression_level_; } + /// Set \a algorithm to be the compression algorithm used for the server call. + /// + /// \param algorithm The compression algorithm used for the server call. void set_compression_level(grpc_compression_level level) { compression_level_set_ = true; compression_level_ = level; } + /// 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. bool compression_level_set() const { return compression_level_set_; } + /// Return the compression algorithm to be used by the server call. grpc_compression_algorithm compression_algorithm() const { return compression_algorithm_; } + /// Set \a algorithm to be the compression algorithm used for the server call. + /// + /// \param algorithm The compression algorithm used for the server call. void set_compression_algorithm(grpc_compression_algorithm algorithm); - // Set the load reporting costs in \a cost_data for the call. + /// Set the load reporting costs in \a cost_data for the call. void SetLoadReportingCosts(const std::vector<grpc::string>& cost_data); + /// Return the authentication context for this server call. + /// + /// \see grpc::AuthContext. std::shared_ptr<const AuthContext> auth_context() const { if (auth_context_.get() == nullptr) { auth_context_ = CreateAuthContext(call_); @@ -155,24 +220,25 @@ class ServerContext { return auth_context_; } - // Return the peer uri in a string. - // WARNING: this value is never authenticated or subject to any security - // related code. It must not be used for any authentication related - // functionality. Instead, use auth_context. + /// Return the peer uri in a string. + /// WARNING: this value is never authenticated or subject to any security + /// related code. It must not be used for any authentication related + /// functionality. Instead, use auth_context. grpc::string peer() const; + /// Get the census context associated with this server call. const struct census_context* census_context() const; - // Async only. Has to be called before the rpc starts. - // Returns the tag in completion queue when the rpc finishes. - // IsCancelled() can then be called to check whether the rpc was cancelled. + /// Async only. Has to be called before the rpc starts. + /// Returns the tag in completion queue when the rpc finishes. + /// IsCancelled() can then be called to check whether the rpc was cancelled. void AsyncNotifyWhenDone(void* tag) { has_notify_when_done_tag_ = true; async_notify_when_done_tag_ = tag; } - // 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: @@ -205,14 +271,14 @@ class ServerContext { friend class UnknownMethodHandler; friend class ::grpc::ClientContext; - // Prevent copying. + /// Prevent copying. ServerContext(const ServerContext&); ServerContext& operator=(const ServerContext&); class CompletionOp; void BeginCompletionOp(Call* call); - // Return the tag queued by BeginCompletionOp() + /// Return the tag queued by BeginCompletionOp() CompletionQueueTag* GetCompletionOpTag(); ServerContext(gpr_timespec deadline, grpc_metadata_array* arr); diff --git a/include/grpc++/impl/codegen/service_type.h b/include/grpc++/impl/codegen/service_type.h index bd65ea009e..b88019164d 100644 --- a/include/grpc++/impl/codegen/service_type.h +++ b/include/grpc++/impl/codegen/service_type.h @@ -54,6 +54,12 @@ 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. + /// + /// \param[in] tag Tag identifying this request. virtual void SendInitialMetadata(void* tag) = 0; private: @@ -61,6 +67,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) {} @@ -155,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/status_code_enum.h b/include/grpc++/impl/codegen/status_code_enum.h index 9a90a18e2a..c3d27fa3b0 100644 --- a/include/grpc++/impl/codegen/status_code_enum.h +++ b/include/grpc++/impl/codegen/status_code_enum.h @@ -136,6 +136,11 @@ 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..db9048d7e5 100644 --- a/include/grpc++/impl/codegen/sync_stream.h +++ b/include/grpc++/impl/codegen/sync_stream.h @@ -50,16 +50,30 @@ 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 \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(). + /// Block waiting until the stream finishes and a final status of the call is + /// 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 + /// \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"). /// /// This function will return either: - /// - when all incoming messages have been read and the server has returned + /// - 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. - /// - OR when the server has returned a non-OK status. + /// + /// Return values: + /// - \a Status contains the status code, message and details for the call + /// - the \a ClientContext associated with this call is updated with + /// possible trailing metadata sent from the server. virtual Status Finish() = 0; }; @@ -68,7 +82,12 @@ class ServerStreamingInterface { public: virtual ~ServerStreamingInterface() {} - /// Blocking send initial metadata to client. + /// Block to send initial metadata to client. + /// This call is optional, but if it is used, it cannot be used concurrently + /// with or after the \a Finish method. + /// + /// The initial metadata that will be sent to the client will be + /// taken from the \a ServerContext associated with the call. virtual void SendInitialMetadata() = 0; }; @@ -78,10 +97,11 @@ class ReaderInterface { public: virtual ~ReaderInterface() {} - /// 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; - /// Blocking read a message and parse to \a msg. Returns \a true on success. + /// Block to 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. @@ -100,8 +120,8 @@ class WriterInterface { public: virtual ~WriterInterface() {} - /// Blocking write \a msg to the stream with WriteOptions \a options. - /// This is thread-safe with respect to \a Read + /// Block to write \a msg to the stream with WriteOptions \a options. + /// This is thread-safe with respect to \a ReaderInterface::Read /// /// \param msg The message to be written to the stream. /// \param options The WriteOptions affecting the write operation. @@ -109,8 +129,8 @@ class WriterInterface { /// \return \a true on success, \a false when the stream has been closed. virtual bool Write(const W& msg, WriteOptions options) = 0; - /// Blocking write \a msg to the stream with default write options. - /// This is thread-safe with respect to \a Read + /// Block to write \a msg to the stream with default write options. + /// This is thread-safe with respect to \a ReaderInterface::Read /// /// \param msg The message to be written to the stream. /// @@ -122,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. @@ -141,17 +161,22 @@ template <class R> class ClientReaderInterface : public ClientStreamingInterface, public ReaderInterface<R> { public: - /// Blocking wait for initial metadata from server. The received metadata + /// Block to 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; }; +/// 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: - /// Blocking create a stream and write the first request out. + /// 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) @@ -172,6 +197,13 @@ class ClientReader final : public ClientReaderInterface<R> { cq_.Pluck(&ops); } + /// See the \a ClientStreamingInterface.WaitForInitialMetadata method for + /// semantics. + /// + // Side effect: + /// 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_); @@ -186,6 +218,11 @@ class ClientReader final : public ClientReaderInterface<R> { return true; } + /// 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 through the \a ClientContext associated with this call). bool Read(R* msg) override { CallOpSet<CallOpRecvInitialMetadata, CallOpRecvMessage<R>> ops; if (!context_->initial_metadata_received_) { @@ -196,6 +233,11 @@ class ClientReader final : public ClientReaderInterface<R> { return cq_.Pluck(&ops) && ops.got_message; } + /// 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. Status Finish() override { CallOpSet<CallOpClientRecvStatus> ops; Status status; @@ -211,23 +253,31 @@ class ClientReader final : public ClientReaderInterface<R> { Call call_; }; -/// Client-side interface for streaming writes of message of type \a W. +/// Client-side interface for streaming writes of message type \a W. template <class W> class ClientWriterInterface : public ClientStreamingInterface, public WriterInterface<W> { public: - /// Half close writing from the client. - /// Block until currently-pending writes are completed. - /// Thread safe with respect to \a Read operations only + /// Half close writing from the client. (signal that the stream of messages + /// coming from the clinet is complete). + /// Blocks until currently-pending writes are completed. + /// Thread safe with respect to \a ReaderInterface::Read operations only /// /// \return Whether the writes were successful. virtual bool WritesDone() = 0; }; +/// 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. template <class W> class ClientWriter : public ClientWriterInterface<W> { public: - /// Blocking create a stream. + /// 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) @@ -248,6 +298,12 @@ class ClientWriter : public ClientWriterInterface<W> { } } + /// See the \a ClientStreamingInterface.WaitForInitialMetadata method for + /// semantics. + /// + // Side effect: + /// 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_); @@ -257,6 +313,12 @@ class ClientWriter : public ClientWriterInterface<W> { cq_.Pluck(&ops); // status ignored } + /// See the WriterInterface.Write(const W& msg, WriteOptions options) method + /// for semantics. + /// + /// Side effect: + /// 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, @@ -287,7 +349,12 @@ class ClientWriter : public ClientWriterInterface<W> { return cq_.Pluck(&ops); } - /// Read the final response and wait for the final status. + /// 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. Status Finish() override { Status status; if (!context_->initial_metadata_received_) { @@ -308,29 +375,39 @@ class ClientWriter : public ClientWriterInterface<W> { Call call_; }; -/// Client-side interface for bi-directional streaming. +/// Client-side interface for bi-directional streaming with +/// client-to-server stream messages of type \a W and +/// server-to-client stream messages of type \a R. template <class W, class R> class ClientReaderWriterInterface : public ClientStreamingInterface, public WriterInterface<W>, public ReaderInterface<R> { public: - /// Blocking wait for initial metadata from server. The received metadata + /// Block to 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 currently-pending writes are completed. - /// Thread-safe with respect to \a Read + /// Half close writing from the client. (signal that the stream of messages + /// coming from the clinet is complete). + /// Blocks until currently-pending writes are completed. + /// Thread-safe with respect to \a ReaderInterface::Read /// /// \return Whether the writes were successful. 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. template <class W, class R> class ClientReaderWriter final : public ClientReaderWriterInterface<W, R> { public: - /// Blocking create a stream. + /// 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) : context_(context), @@ -347,6 +424,12 @@ class ClientReaderWriter final : public ClientReaderWriterInterface<W, R> { } } + /// Block waiting to read initial metadata from the server. + /// 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. void WaitForInitialMetadata() override { GPR_CODEGEN_ASSERT(!context_->initial_metadata_received_); @@ -361,6 +444,10 @@ class ClientReaderWriter final : public ClientReaderWriterInterface<W, R> { return true; } + /// See the \a ReaderInterface.Read method for semantics. + /// Side effect: + /// Also receives initial metadata if not already received (updates the \a + /// ClientContext associated with this call in that case). bool Read(R* msg) override { CallOpSet<CallOpRecvInitialMetadata, CallOpRecvMessage<R>> ops; if (!context_->initial_metadata_received_) { @@ -371,6 +458,11 @@ class ClientReaderWriter final : public ClientReaderWriterInterface<W, R> { return cq_.Pluck(&ops) && ops.got_message; } + /// See the \a WriterInterface.Write method for semantics. + /// + /// Side effect: + /// Also sends initial metadata if not already sent (using the + /// \a ClientContext associated with this call to fill in values). using WriterInterface<W>::Write; bool Write(const W& msg, WriteOptions options) override { CallOpSet<CallOpSendInitialMetadata, CallOpSendMessage, @@ -401,6 +493,11 @@ class ClientReaderWriter final : public ClientReaderWriterInterface<W, R> { return cq_.Pluck(&ops); } + /// See the ClientStreamingInterface.Finish method for semantics. + /// + /// Side effect: + /// - the \a ClientContext associated with this call is updated with + /// possible trailing metadata sent from the server. Status Finish() override { CallOpSet<CallOpRecvInitialMetadata, CallOpClientRecvStatus> ops; if (!context_->initial_metadata_received_) { @@ -424,11 +521,17 @@ template <class R> class ServerReaderInterface : public ServerStreamingInterface, public ReaderInterface<R> {}; +/// Synchronous (blocking) server-side API for doing client-streaming RPCs, +/// where the incoming message stream coming from the client has messages of +/// type \a R. template <class R> class ServerReader final : public ServerReaderInterface<R> { public: 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 + /// \a ServerContext associated with this call. void SendInitialMetadata() override { GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_); @@ -465,11 +568,18 @@ template <class W> class ServerWriterInterface : public ServerStreamingInterface, public WriterInterface<W> {}; +/// Synchronous (blocking) server-side API for doing for doing a +/// server-streaming RPCs, where the outgoing message stream coming from the +/// server has messages of type \a W. template <class W> class ServerWriter final : public ServerWriterInterface<W> { public: ServerWriter(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 + /// \a ServerContext associated with this call. void SendInitialMetadata() override { GPR_CODEGEN_ASSERT(!ctx_->sent_initial_metadata_); @@ -484,6 +594,11 @@ class ServerWriter final : public ServerWriterInterface<W> { call_->cq()->Pluck(&ops); } + /// See the \a WriterInterface.Write method for semantics. + /// + /// Side effect: + /// Also sends initial metadata if not already sent (using the + /// \a ClientContext associated with this call to fill in values). using WriterInterface<W>::Write; bool Write(const W& msg, WriteOptions options) override { if (options.is_last_message()) { @@ -516,7 +631,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,12 +691,18 @@ class ServerReaderWriterBody final { }; } // namespace internal -// class to represent the user API for a bidirectional streaming call +/// 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. 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 + /// \a ServerContext associated with this call. void SendInitialMetadata() override { body_.SendInitialMetadata(); } bool NextMessageSize(uint32_t* sz) override { @@ -590,6 +711,11 @@ 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. + /// Side effect: + /// Also sends initial metadata if not already sent (using the \a + /// ServerContext associated with this call). using WriterInterface<W>::Write; bool Write(const W& msg, WriteOptions options) override { return body_.Write(msg, options); @@ -604,8 +730,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> @@ -615,12 +740,27 @@ class ServerUnaryStreamer final ServerUnaryStreamer(Call* call, ServerContext* ctx) : body_(call, ctx), read_done_(false), write_done_(false) {} + /// Block to send initial metadata to client. + /// Implicit input parameter: + /// - the \a ServerContext associated with this call will be used for + /// sending initial metadata. void SendInitialMetadata() override { body_.SendInitialMetadata(); } + /// Get an upper bound on the request message size from the client. bool NextMessageSize(uint32_t* sz) override { return body_.NextMessageSize(sz); } + /// 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 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. bool Read(RequestType* request) override { if (read_done_) { return false; @@ -629,6 +769,13 @@ class ServerUnaryStreamer final return body_.Read(request); } + /// Block to write \a msg to the stream with WriteOptions \a options. + /// This is thread-safe with respect to \a ReaderInterface::Read + /// + /// \param msg The message to be written to the stream. + /// \param options The WriteOptions affecting the write operation. + /// + /// \return \a true on success, \a false when the stream has been closed. using WriterInterface<ResponseType>::Write; bool Write(const ResponseType& response, WriteOptions options) override { if (write_done_ || !read_done_) { @@ -656,12 +803,27 @@ class ServerSplitStreamer final ServerSplitStreamer(Call* call, ServerContext* ctx) : body_(call, ctx), read_done_(false) {} + /// Block to send initial metadata to client. + /// Implicit input parameter: + /// - the \a ServerContext associated with this call will be used for + /// sending initial metadata. void SendInitialMetadata() override { body_.SendInitialMetadata(); } + /// Get an upper bound on the request message size from the client. bool NextMessageSize(uint32_t* sz) override { return body_.NextMessageSize(sz); } + /// 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 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. bool Read(RequestType* request) override { if (read_done_) { return false; @@ -670,6 +832,13 @@ class ServerSplitStreamer final return body_.Read(request); } + /// Block to write \a msg to the stream with WriteOptions \a options. + /// This is thread-safe with respect to \a ReaderInterface::Read + /// + /// \param msg The message to be written to the stream. + /// \param options The WriteOptions affecting the write operation. + /// + /// \return \a true on success, \a false when the stream has been closed. using WriterInterface<ResponseType>::Write; bool Write(const ResponseType& response, WriteOptions options) override { return read_done_ && body_.Write(response, options); 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: diff --git a/include/grpc++/impl/server_builder_plugin.h b/include/grpc++/impl/server_builder_plugin.h index 00d806ddb1..d940f8cc7b 100644 --- a/include/grpc++/impl/server_builder_plugin.h +++ b/include/grpc++/impl/server_builder_plugin.h @@ -44,27 +44,31 @@ class ServerBuilder; class ServerInitializer; class ChannelArguments; +/// This interface is meant for internal usage only. Implementations of this +/// interface should add themselves to a \a ServerBuilder instance through the +/// \a InternalAddPluginFactory method. class ServerBuilderPlugin { public: virtual ~ServerBuilderPlugin() {} virtual grpc::string name() = 0; - /// UpdateServerBuilder will be called at the beginning of BuildAndStart. + /// UpdateServerBuilder will be called at the beginning of + /// \a ServerBuilder::BuildAndStart(). virtual void UpdateServerBuilder(ServerBuilder* builder) {} - // InitServer will be called in ServerBuilder::BuildAndStart(), after the - // Server instance is created. + /// InitServer will be called in ServerBuilder::BuildAndStart(), after the + /// Server instance is created. virtual void InitServer(ServerInitializer* si) = 0; - // Finish will be called at the end of ServerBuilder::BuildAndStart(). + /// Finish will be called at the end of ServerBuilder::BuildAndStart(). virtual void Finish(ServerInitializer* si) = 0; - // ChangeArguments is an interface that can be used in - // ServerBuilderOption::UpdatePlugins + /// ChangeArguments is an interface that can be used in + /// ServerBuilderOption::UpdatePlugins virtual void ChangeArguments(const grpc::string& name, void* value) = 0; - // UpdateChannelArguments will be called in ServerBuilder::BuildAndStart(), - // before the Server instance is created. + /// UpdateChannelArguments will be called in ServerBuilder::BuildAndStart(), + /// before the Server instance is created. virtual void UpdateChannelArguments(ChannelArguments* args) {} virtual bool has_sync_methods() const { return false; } diff --git a/include/grpc++/resource_quota.h b/include/grpc++/resource_quota.h index 68a514658d..1199ae9381 100644 --- a/include/grpc++/resource_quota.h +++ b/include/grpc++/resource_quota.h @@ -47,6 +47,7 @@ namespace grpc { /// all attached entities below the ResourceQuota bound. class ResourceQuota final : private GrpcLibraryCodegen { public: + /// \param name - a unique name for this ResourceQuota. explicit ResourceQuota(const grpc::string& name); ResourceQuota(); ~ResourceQuota(); diff --git a/include/grpc++/security/auth_metadata_processor.h b/include/grpc++/security/auth_metadata_processor.h index 1ae32d0f6c..3536923146 100644 --- a/include/grpc++/security/auth_metadata_processor.h +++ b/include/grpc++/security/auth_metadata_processor.h @@ -49,19 +49,19 @@ class AuthMetadataProcessor { virtual ~AuthMetadataProcessor() {} - // If this method returns true, the Process function will be scheduled in - // a different thread from the one processing the call. + /// If this method returns true, the Process function will be scheduled in + /// a different thread from the one processing the call. virtual bool IsBlocking() const { return true; } - // context is read/write: it contains the properties of the channel peer and - // it is the job of the Process method to augment it with properties derived - // from the passed-in auth_metadata. - // consumed_auth_metadata needs to be filled with metadata that has been - // consumed by the processor and will be removed from the call. - // response_metadata is the metadata that will be sent as part of the - // response. - // If the return value is not Status::OK, the rpc call will be aborted with - // the error code and error message sent back to the client. + /// context is read/write: it contains the properties of the channel peer and + /// it is the job of the Process method to augment it with properties derived + /// from the passed-in auth_metadata. + /// consumed_auth_metadata needs to be filled with metadata that has been + /// consumed by the processor and will be removed from the call. + /// response_metadata is the metadata that will be sent as part of the + /// response. + /// If the return value is not Status::OK, the rpc call will be aborted with + /// the error code and error message sent back to the client. virtual Status Process(const InputMetadata& auth_metadata, AuthContext* context, OutputMetadata* consumed_auth_metadata, diff --git a/include/grpc++/security/credentials.h b/include/grpc++/security/credentials.h index 59861b78d8..8d9d181fde 100644 --- a/include/grpc++/security/credentials.h +++ b/include/grpc++/security/credentials.h @@ -204,23 +204,23 @@ std::shared_ptr<ChannelCredentials> InsecureChannelCredentials(); /// Credentials for a channel using Cronet. std::shared_ptr<ChannelCredentials> CronetChannelCredentials(void* engine); -// User defined metadata credentials. +/// User defined metadata credentials. class MetadataCredentialsPlugin { public: virtual ~MetadataCredentialsPlugin() {} - // If this method returns true, the Process function will be scheduled in - // a different thread from the one processing the call. + /// If this method returns true, the Process function will be scheduled in + /// a different thread from the one processing the call. virtual bool IsBlocking() const { return true; } - // Type of credentials this plugin is implementing. + /// Type of credentials this plugin is implementing. virtual const char* GetType() const { return ""; } - // Gets the auth metatada produced by this plugin. - // The fully qualified method name is: - // service_url + "/" + method_name. - // The channel_auth_context contains (among other things), the identity of - // the server. + /// Gets the auth metatada produced by this plugin. + /// The fully qualified method name is: + /// service_url + "/" + method_name. + /// The channel_auth_context contains (among other things), the identity of + /// the server. virtual Status GetMetadata( grpc::string_ref service_url, grpc::string_ref method_name, const AuthContext& channel_auth_context, diff --git a/include/grpc++/security/server_credentials.h b/include/grpc++/security/server_credentials.h index 229bab8d84..4676b04c5d 100644 --- a/include/grpc++/security/server_credentials.h +++ b/include/grpc++/security/server_credentials.h @@ -46,13 +46,13 @@ struct grpc_server; namespace grpc { class Server; -// Wrapper around \a grpc_server_credentials, a way to authenticate a server. +/// Wrapper around \a grpc_server_credentials, a way to authenticate a server. class ServerCredentials { public: virtual ~ServerCredentials(); - // This method is not thread-safe and has to be called before the server is - // started. The last call to this function wins. + /// This method is not thread-safe and has to be called before the server is + /// started. The last call to this function wins. virtual void SetAuthMetadataProcessor( const std::shared_ptr<AuthMetadataProcessor>& processor) = 0; @@ -70,7 +70,7 @@ class ServerCredentials { /// Options to create ServerCredentials with SSL struct SslServerCredentialsOptions { - // Deprecated + /// Deprecated SslServerCredentialsOptions() : force_client_auth(false), client_certificate_request(GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE) {} @@ -84,12 +84,12 @@ struct SslServerCredentialsOptions { }; grpc::string pem_root_certs; std::vector<PemKeyCertPair> pem_key_cert_pairs; - // Deprecated + /// Deprecated bool force_client_auth; - // If both force_client_auth and client_certificate_request fields are set, - // force_client_auth takes effect i.e - // REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_AND_VERIFY will be enforced. + /// If both force_client_auth and client_certificate_request fields are set, + /// force_client_auth takes effect i.e + /// REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_AND_VERIFY will be enforced. grpc_ssl_client_certificate_request_type client_certificate_request; }; diff --git a/include/grpc++/server_builder.h b/include/grpc++/server_builder.h index a56f81dc4b..2185b283ac 100644 --- a/include/grpc++/server_builder.h +++ b/include/grpc++/server_builder.h @@ -46,6 +46,7 @@ #include <grpc/compression.h> #include <grpc/support/cpu.h> #include <grpc/support/useful.h> +#include <grpc/support/workaround_list.h> struct grpc_resource_quota; @@ -184,6 +185,11 @@ class ServerBuilder { static void InternalAddPluginFactory( std::unique_ptr<ServerBuilderPlugin> (*CreatePlugin)()); + /// Enable a server workaround. Do not use unless you know what the workaround + /// does. For explanation and detailed descriptions of workarounds, see + /// doc/workarounds.md. + ServerBuilder& EnableWorkaround(grpc_workaround_list id); + private: friend class ::grpc::testing::ServerBuilderPluginTest; @@ -195,7 +201,7 @@ class ServerBuilder { struct SyncServerSettings { SyncServerSettings() - : num_cqs(gpr_cpu_num_cores()), + : num_cqs(GPR_MAX(1, gpr_cpu_num_cores())), min_pollers(1), max_pollers(2), cq_timeout_msec(10000) {} diff --git a/include/grpc++/support/error_details.h b/include/grpc++/support/error_details.h index 411175fb46..d4324d35cf 100644 --- a/include/grpc++/support/error_details.h +++ b/include/grpc++/support/error_details.h @@ -44,16 +44,16 @@ class Status; namespace grpc { -// Maps a grpc::Status to a google::rpc::Status. -// The given \a to object will be cleared. -// On success, returns status with OK. -// Returns status with INVALID_ARGUMENT, if failed to deserialize. -// Returns status with FAILED_PRECONDITION, if \a to is nullptr. +/// Maps a grpc::Status to a google::rpc::Status. +/// The given \a to object will be cleared. +/// On success, returns status with OK. +/// Returns status with INVALID_ARGUMENT, if failed to deserialize. +/// Returns status with FAILED_PRECONDITION, if \a to is nullptr. Status ExtractErrorDetails(const Status& from, ::google::rpc::Status* to); -// Maps google::rpc::Status to a grpc::Status. -// Returns OK on success. -// Returns status with FAILED_PRECONDITION if \a to is nullptr. +/// Maps google::rpc::Status to a grpc::Status. +/// Returns OK on success. +/// Returns status with FAILED_PRECONDITION if \a to is nullptr. Status SetErrorDetails(const ::google::rpc::Status& from, Status* to); } // namespace grpc diff --git a/include/grpc++/test/mock_stream.h b/include/grpc++/test/mock_stream.h index f2de9472d6..f6e94a48b3 100644 --- a/include/grpc++/test/mock_stream.h +++ b/include/grpc++/test/mock_stream.h @@ -50,14 +50,14 @@ class MockClientReader : public ClientReaderInterface<R> { public: MockClientReader() = default; - // ClientStreamingInterface + /// ClientStreamingInterface MOCK_METHOD0_T(Finish, Status()); - // ReaderInterface + /// ReaderInterface MOCK_METHOD1_T(NextMessageSize, bool(uint32_t*)); MOCK_METHOD1_T(Read, bool(R*)); - // ClientReaderInterface + /// ClientReaderInterface MOCK_METHOD0_T(WaitForInitialMetadata, void()); }; @@ -66,13 +66,13 @@ class MockClientWriter : public ClientWriterInterface<W> { public: MockClientWriter() = default; - // ClientStreamingInterface + /// ClientStreamingInterface MOCK_METHOD0_T(Finish, Status()); - // WriterInterface + /// WriterInterface MOCK_METHOD2_T(Write, bool(const W&, const WriteOptions)); - // ClientWriterInterface + /// ClientWriterInterface MOCK_METHOD0_T(WritesDone, bool()); }; @@ -81,22 +81,22 @@ class MockClientReaderWriter : public ClientReaderWriterInterface<W, R> { public: MockClientReaderWriter() = default; - // ClientStreamingInterface + /// ClientStreamingInterface MOCK_METHOD0_T(Finish, Status()); - // ReaderInterface + /// ReaderInterface MOCK_METHOD1_T(NextMessageSize, bool(uint32_t*)); MOCK_METHOD1_T(Read, bool(R*)); - // WriterInterface + /// WriterInterface MOCK_METHOD2_T(Write, bool(const W&, const WriteOptions)); - // ClientReaderWriterInterface + /// ClientReaderWriterInterface MOCK_METHOD0_T(WaitForInitialMetadata, void()); MOCK_METHOD0_T(WritesDone, bool()); }; -// TODO: We do not support mocking an async RPC for now. +/// TODO: We do not support mocking an async RPC for now. template <class R> class MockClientAsyncResponseReader @@ -113,11 +113,11 @@ class MockClientAsyncReader : public ClientAsyncReaderInterface<R> { public: MockClientAsyncReader() = default; - // ClientAsyncStreamingInterface + /// ClientAsyncStreamingInterface MOCK_METHOD1_T(ReadInitialMetadata, void(void*)); MOCK_METHOD2_T(Finish, void(Status*, void*)); - // AsyncReaderInterface + /// AsyncReaderInterface MOCK_METHOD2_T(Read, void(R*, void*)); }; @@ -126,14 +126,14 @@ class MockClientAsyncWriter : public ClientAsyncWriterInterface<W> { public: MockClientAsyncWriter() = default; - // ClientAsyncStreamingInterface + /// ClientAsyncStreamingInterface MOCK_METHOD1_T(ReadInitialMetadata, void(void*)); MOCK_METHOD2_T(Finish, void(Status*, void*)); - // AsyncWriterInterface + /// AsyncWriterInterface MOCK_METHOD2_T(Write, void(const W&, void*)); - // ClientAsyncWriterInterface + /// ClientAsyncWriterInterface MOCK_METHOD1_T(WritesDone, void(void*)); }; @@ -143,17 +143,17 @@ class MockClientAsyncReaderWriter public: MockClientAsyncReaderWriter() = default; - // ClientAsyncStreamingInterface + /// ClientAsyncStreamingInterface MOCK_METHOD1_T(ReadInitialMetadata, void(void*)); MOCK_METHOD2_T(Finish, void(Status*, void*)); - // AsyncWriterInterface + /// AsyncWriterInterface MOCK_METHOD2_T(Write, void(const W&, void*)); - // AsyncReaderInterface + /// AsyncReaderInterface MOCK_METHOD2_T(Read, void(R*, void*)); - // ClientAsyncReaderWriterInterface + /// ClientAsyncReaderWriterInterface MOCK_METHOD1_T(WritesDone, void(void*)); }; diff --git a/include/grpc++/test/server_context_test_spouse.h b/include/grpc++/test/server_context_test_spouse.h index bac0db7bdc..5bd07e7aec 100644 --- a/include/grpc++/test/server_context_test_spouse.h +++ b/include/grpc++/test/server_context_test_spouse.h @@ -41,13 +41,13 @@ namespace grpc { namespace testing { -// A test-only class to access private members and methods of ServerContext. +/// A test-only class to access private members and methods of ServerContext. class ServerContextTestSpouse { public: explicit ServerContextTestSpouse(ServerContext* ctx) : ctx_(ctx) {} - // Inject client metadata to the ServerContext for the test. The test spouse - // must be alive when ServerContext::client_metadata is called. + /// Inject client metadata to the ServerContext for the test. The test spouse + /// must be alive when ServerContext::client_metadata is called. void AddClientMetadata(const grpc::string& key, const grpc::string& value) { client_metadata_storage_.insert( std::pair<grpc::string, grpc::string>(key, value)); @@ -70,7 +70,7 @@ class ServerContextTestSpouse { } private: - ServerContext* ctx_; // not owned + ServerContext* ctx_; /// not owned std::multimap<grpc::string, grpc::string> client_metadata_storage_; }; diff --git a/include/grpc/census.h b/include/grpc/census.h index 822c42c0a4..68cefd86a1 100644 --- a/include/grpc/census.h +++ b/include/grpc/census.h @@ -31,7 +31,7 @@ * */ -/* RPC-internal Census API's. These are designed to be generic enough that +/** RPC-internal Census API's. These are designed to be generic enough that * they can (ultimately) be used in many different RPC systems (with differing * implementations). */ @@ -44,12 +44,12 @@ extern "C" { #endif -/* Identify census features that can be enabled via census_initialize(). */ +/** Identify census features that can be enabled via census_initialize(). */ enum census_features { - CENSUS_FEATURE_NONE = 0, /* Do not enable census. */ - CENSUS_FEATURE_TRACING = 1, /* Enable census tracing. */ - CENSUS_FEATURE_STATS = 2, /* Enable Census stats collection. */ - CENSUS_FEATURE_CPU = 4, /* Enable Census CPU usage collection. */ + CENSUS_FEATURE_NONE = 0, /** Do not enable census. */ + CENSUS_FEATURE_TRACING = 1, /** Enable census tracing. */ + CENSUS_FEATURE_STATS = 2, /** Enable Census stats collection. */ + CENSUS_FEATURE_CPU = 4, /** Enable Census CPU usage collection. */ CENSUS_FEATURE_ALL = CENSUS_FEATURE_TRACING | CENSUS_FEATURE_STATS | CENSUS_FEATURE_CPU }; @@ -82,7 +82,7 @@ CENSUSAPI int census_enabled(void); metrics will be recorded. Keys are unique within a context. */ typedef struct census_context census_context; -/* A tag is a key:value pair. Both keys and values are nil-terminated strings, +/** A tag is a key:value pair. Both keys and values are nil-terminated strings, containing printable ASCII characters (decimal 32-126). Keys must be at least one character in length. Both keys and values can have at most CENSUS_MAX_TAG_KB_LEN characters (including the terminating nil). The @@ -97,36 +97,36 @@ typedef struct { uint8_t flags; } census_tag; -/* Maximum length of a tag's key or value. */ +/** Maximum length of a tag's key or value. */ #define CENSUS_MAX_TAG_KV_LEN 255 -/* Maximum number of propagatable tags. */ +/** Maximum number of propagatable tags. */ #define CENSUS_MAX_PROPAGATED_TAGS 255 -/* Tag flags. */ -#define CENSUS_TAG_PROPAGATE 1 /* Tag should be propagated over RPC */ -#define CENSUS_TAG_STATS 2 /* Tag will be used for statistics aggregation */ -#define CENSUS_TAG_RESERVED 4 /* Reserved for internal use. */ -/* Flag values 4,8,16,32,64,128 are reserved for future/internal use. Clients +/** Tag flags. */ +#define CENSUS_TAG_PROPAGATE 1 /** Tag should be propagated over RPC */ +#define CENSUS_TAG_STATS 2 /** Tag will be used for statistics aggregation */ +#define CENSUS_TAG_RESERVED 4 /** Reserved for internal use. */ +/** Flag values 4,8,16,32,64,128 are reserved for future/internal use. Clients should not use or rely on their values. */ #define CENSUS_TAG_IS_PROPAGATED(flags) (flags & CENSUS_TAG_PROPAGATE) #define CENSUS_TAG_IS_STATS(flags) (flags & CENSUS_TAG_STATS) -/* An instance of this structure is kept by every context, and records the +/** An instance of this structure is kept by every context, and records the basic information associated with the creation of that context. */ typedef struct { - int n_propagated_tags; /* number of propagated tags */ - int n_local_tags; /* number of non-propagated (local) tags */ - int n_deleted_tags; /* number of tags that were deleted */ - int n_added_tags; /* number of tags that were added */ - int n_modified_tags; /* number of tags that were modified */ - int n_invalid_tags; /* number of tags with bad keys or values (e.g. + int n_propagated_tags; /** number of propagated tags */ + int n_local_tags; /** number of non-propagated (local) tags */ + int n_deleted_tags; /** number of tags that were deleted */ + int n_added_tags; /** number of tags that were added */ + int n_modified_tags; /** number of tags that were modified */ + int n_invalid_tags; /** number of tags with bad keys or values (e.g. longer than CENSUS_MAX_TAG_KV_LEN) */ - int n_ignored_tags; /* number of tags ignored because of + int n_ignored_tags; /** number of tags ignored because of CENSUS_MAX_PROPAGATED_TAGS limit. */ } census_context_status; -/* Create a new context, adding and removing tags from an existing context. +/** Create a new context, adding and removing tags from an existing context. This will copy all tags from the 'tags' input, so it is recommended to add as many tags in a single operation as is practical for the client. @param base Base context to build upon. Can be NULL. @@ -148,15 +148,15 @@ CENSUSAPI census_context *census_context_create( const census_context *base, const census_tag *tags, int ntags, census_context_status const **status); -/* Destroy a context. Once this function has been called, the context cannot +/** Destroy a context. Once this function has been called, the context cannot be reused. */ CENSUSAPI void census_context_destroy(census_context *context); -/* Get a pointer to the original status from the context creation. */ +/** Get a pointer to the original status from the context creation. */ CENSUSAPI const census_context_status *census_context_get_status( const census_context *context); -/* Structure used for iterating over the tags in a context. API clients should +/** Structure used for iterating over the tags in a context. API clients should not use or reference internal fields - neither their contents or presence/absence are guaranteed. */ typedef struct { @@ -166,25 +166,25 @@ typedef struct { char *kvm; } census_context_iterator; -/* Initialize a census_tag_iterator. Must be called before first use. */ +/** Initialize a census_tag_iterator. Must be called before first use. */ CENSUSAPI void census_context_initialize_iterator( const census_context *context, census_context_iterator *iterator); -/* Get the contents of the "next" tag in the context. If there are no more +/** Get the contents of the "next" tag in the context. If there are no more tags, returns 0 (and 'tag' contents will be unchanged), otherwise returns 1. */ CENSUSAPI int census_context_next_tag(census_context_iterator *iterator, census_tag *tag); -/* Get a context tag by key. Returns 0 if the key is not present. */ +/** Get a context tag by key. Returns 0 if the key is not present. */ CENSUSAPI int census_context_get_tag(const census_context *context, const char *key, census_tag *tag); -/* Tag set encode/decode functionality. These functions are intended +/** Tag set encode/decode functionality. These functions are intended for use by RPC systems only, for purposes of transmitting/receiving contexts. */ -/* Encode a context into a buffer. +/** Encode a context into a buffer. @param context context to be encoded @param buffer buffer into which the context will be encoded. @param buf_size number of available bytes in buffer. @@ -193,15 +193,15 @@ CENSUSAPI int census_context_get_tag(const census_context *context, CENSUSAPI size_t census_context_encode(const census_context *context, char *buffer, size_t buf_size); -/* Decode context buffer encoded with census_context_encode(). Returns NULL +/** Decode context buffer encoded with census_context_encode(). Returns NULL if there is an error in parsing either buffer. */ CENSUSAPI census_context *census_context_decode(const char *buffer, size_t size); -/* Distributed traces can have a number of options. */ +/** Distributed traces can have a number of options. */ enum census_trace_mask_values { - CENSUS_TRACE_MASK_NONE = 0, /* Default, empty flags */ - CENSUS_TRACE_MASK_IS_SAMPLED = 1 /* RPC tracing enabled for this context. */ + CENSUS_TRACE_MASK_NONE = 0, /** Default, empty flags */ + CENSUS_TRACE_MASK_IS_SAMPLED = 1 /** RPC tracing enabled for this context. */ }; /** Get the current trace mask associated with this context. The value returned @@ -211,7 +211,7 @@ CENSUSAPI int census_trace_mask(const census_context *context); /** Set the trace mask associated with a context. */ CENSUSAPI void census_set_trace_mask(int trace_mask); -/* The concept of "operation" is a fundamental concept for Census. In an RPC +/** The concept of "operation" is a fundamental concept for Census. In an RPC system, an operation typically represents a single RPC, or a significant sub-part thereof (e.g. a single logical "read" RPC to a distributed storage system might do several other actions in parallel, from looking up metadata @@ -238,7 +238,7 @@ CENSUSAPI void census_set_trace_mask(int trace_mask); at which an operation begins. */ typedef struct { - /* Use gpr_timespec for default implementation. High performance + /** Use gpr_timespec for default implementation. High performance * implementations should use a cycle-counter based timestamp. */ gpr_timespec ts; } census_timestamp; @@ -398,12 +398,12 @@ CENSUSAPI void census_trace_print(census_context *context, uint32_t type, /** Trace record. */ typedef struct { - census_timestamp timestamp; /* Time of record creation */ - uint64_t trace_id; /* Trace ID associated with record */ - uint64_t op_id; /* Operation ID associated with record */ - uint32_t type; /* Type (as used in census_trace_print() */ - const char *buffer; /* Buffer (from census_trace_print() */ - size_t buf_size; /* Number of bytes inside buffer */ + census_timestamp timestamp; /** Time of record creation */ + uint64_t trace_id; /** Trace ID associated with record */ + uint64_t op_id; /** Operation ID associated with record */ + uint32_t type; /** Type (as used in census_trace_print() */ + const char *buffer; /** Buffer (from census_trace_print() */ + size_t buf_size; /** Number of bytes inside buffer */ } census_trace_record; /** Start a scan of existing trace records. While a scan is ongoing, addition @@ -431,7 +431,7 @@ CENSUSAPI int census_get_trace_record(census_trace_record *trace_record); /** End a scan previously started by census_trace_scan_start() */ CENSUSAPI void census_trace_scan_end(); -/* Core stats collection API's. The following concepts are used: +/** Core stats collection API's. The following concepts are used: * Resource: Users record measurements for a single resource. Examples include RPC latency, CPU seconds consumed, and bytes transmitted. * Aggregation: An aggregation of a set of measurements. Census supports the @@ -450,7 +450,7 @@ CENSUSAPI void census_trace_scan_end(); implementations. The proto definitions can be found in src/proto/census. */ -/* Define a new resource. `resource_pb` should contain an encoded Resource +/** Define a new resource. `resource_pb` should contain an encoded Resource protobuf, `resource_pb_size` being the size of the buffer. Returns a -ve value on error, or a positive (>= 0) resource id (for use in census_delete_resource() and census_record_values()). In order to be valid, a @@ -459,21 +459,21 @@ CENSUSAPI void census_trace_scan_end(); CENSUSAPI int32_t census_define_resource(const uint8_t *resource_pb, size_t resource_pb_size); -/* Delete a resource created by census_define_resource(). */ +/** Delete a resource created by census_define_resource(). */ CENSUSAPI void census_delete_resource(int32_t resource_id); -/* Determine the id of a resource, given its name. returns -1 if the resource +/** Determine the id of a resource, given its name. returns -1 if the resource does not exist. */ CENSUSAPI int32_t census_resource_id(const char *name); -/* A single value to be recorded comprises two parts: an ID for the particular +/** A single value to be recorded comprises two parts: an ID for the particular * resource and the value to be recorded against it. */ typedef struct { int32_t resource_id; double value; } census_value; -/* Record new usage values against the given context. */ +/** Record new usage values against the given context. */ CENSUSAPI void census_record_values(census_context *context, census_value *values, size_t nvalues); diff --git a/include/grpc/grpc.h b/include/grpc/grpc.h index 1eeb075927..a36367fa8f 100644 --- a/include/grpc/grpc.h +++ b/include/grpc/grpc.h @@ -287,7 +287,7 @@ GRPCAPI grpc_channel *grpc_lame_client_channel_create( /** Close and destroy a grpc channel */ GRPCAPI void grpc_channel_destroy(grpc_channel *channel); -/* Error handling for grpc_call +/** Error handling for grpc_call Most grpc_call functions return a grpc_error. If the error is not GRPC_OK then the operation failed due to some unsatisfied precondition. If a grpc_call fails, it's guaranteed that no change to the call state diff --git a/include/grpc/grpc_security.h b/include/grpc/grpc_security.h index 5d3cc4fd67..4f35506882 100644 --- a/include/grpc/grpc_security.h +++ b/include/grpc/grpc_security.h @@ -42,7 +42,7 @@ extern "C" { #endif -/* --- Authentication Context. --- */ +/** --- Authentication Context. --- */ typedef struct grpc_auth_context grpc_auth_context; @@ -52,84 +52,84 @@ typedef struct grpc_auth_property_iterator { const char *name; } grpc_auth_property_iterator; -/* value, if not NULL, is guaranteed to be NULL terminated. */ +/** value, if not NULL, is guaranteed to be NULL terminated. */ typedef struct grpc_auth_property { char *name; char *value; size_t value_length; } grpc_auth_property; -/* Returns NULL when the iterator is at the end. */ +/** Returns NULL when the iterator is at the end. */ GRPCAPI const grpc_auth_property *grpc_auth_property_iterator_next( grpc_auth_property_iterator *it); -/* Iterates over the auth context. */ +/** Iterates over the auth context. */ GRPCAPI grpc_auth_property_iterator grpc_auth_context_property_iterator(const grpc_auth_context *ctx); -/* Gets the peer identity. Returns an empty iterator (first _next will return +/** Gets the peer identity. Returns an empty iterator (first _next will return NULL) if the peer is not authenticated. */ GRPCAPI grpc_auth_property_iterator grpc_auth_context_peer_identity(const grpc_auth_context *ctx); -/* Finds a property in the context. May return an empty iterator (first _next +/** Finds a property in the context. May return an empty iterator (first _next will return NULL) if no property with this name was found in the context. */ GRPCAPI grpc_auth_property_iterator grpc_auth_context_find_properties_by_name( const grpc_auth_context *ctx, const char *name); -/* Gets the name of the property that indicates the peer identity. Will return +/** Gets the name of the property that indicates the peer identity. Will return NULL if the peer is not authenticated. */ GRPCAPI const char *grpc_auth_context_peer_identity_property_name( const grpc_auth_context *ctx); -/* Returns 1 if the peer is authenticated, 0 otherwise. */ +/** Returns 1 if the peer is authenticated, 0 otherwise. */ GRPCAPI int grpc_auth_context_peer_is_authenticated( const grpc_auth_context *ctx); -/* Gets the auth context from the call. Caller needs to call +/** Gets the auth context from the call. Caller needs to call grpc_auth_context_release on the returned context. */ GRPCAPI grpc_auth_context *grpc_call_auth_context(grpc_call *call); -/* Releases the auth context returned from grpc_call_auth_context. */ +/** Releases the auth context returned from grpc_call_auth_context. */ GRPCAPI void grpc_auth_context_release(grpc_auth_context *context); -/* -- +/** -- The following auth context methods should only be called by a server metadata processor to set properties extracted from auth metadata. -- */ -/* Add a property. */ +/** Add a property. */ GRPCAPI void grpc_auth_context_add_property(grpc_auth_context *ctx, const char *name, const char *value, size_t value_length); -/* Add a C string property. */ +/** Add a C string property. */ GRPCAPI void grpc_auth_context_add_cstring_property(grpc_auth_context *ctx, const char *name, const char *value); -/* Sets the property name. Returns 1 if successful or 0 in case of failure +/** Sets the property name. Returns 1 if successful or 0 in case of failure (which means that no property with this name exists). */ GRPCAPI int grpc_auth_context_set_peer_identity_property_name( grpc_auth_context *ctx, const char *name); -/* --- grpc_channel_credentials object. --- +/** --- grpc_channel_credentials object. --- A channel credentials object represents a way to authenticate a client on a channel. */ typedef struct grpc_channel_credentials grpc_channel_credentials; -/* Releases a channel credentials object. +/** Releases a channel credentials object. The creator of the credentials object is responsible for its release. */ GRPCAPI void grpc_channel_credentials_release(grpc_channel_credentials *creds); -/* Creates default credentials to connect to a google gRPC service. +/** Creates default credentials to connect to a google gRPC service. WARNING: Do NOT use this credentials to connect to a non-google service as this could result in an oauth2 token leak. */ GRPCAPI grpc_channel_credentials *grpc_google_default_credentials_create(void); -/* Callback for getting the SSL roots override from the application. +/** Callback for getting the SSL roots override from the application. In case of success, *pem_roots_certs must be set to a NULL terminated string containing the list of PEM encoded root certificates. The ownership is passed to the core and freed (laster by the core) with gpr_free. @@ -138,7 +138,7 @@ GRPCAPI grpc_channel_credentials *grpc_google_default_credentials_create(void); typedef grpc_ssl_roots_override_result (*grpc_ssl_roots_override_callback)( char **pem_root_certs); -/* Setup a callback to override the default TLS/SSL roots. +/** Setup a callback to override the default TLS/SSL roots. This function is not thread-safe and must be called at initialization time before any ssl credentials are created to have the desired side effect. If GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment is set to a valid path, the @@ -146,18 +146,18 @@ typedef grpc_ssl_roots_override_result (*grpc_ssl_roots_override_callback)( GRPCAPI void grpc_set_ssl_roots_override_callback( grpc_ssl_roots_override_callback cb); -/* Object that holds a private key / certificate chain pair in PEM format. */ +/** Object that holds a private key / certificate chain pair in PEM format. */ typedef struct { - /* private_key is the NULL-terminated string containing the PEM encoding of + /** private_key is the NULL-terminated string containing the PEM encoding of the client's private key. */ const char *private_key; - /* cert_chain is the NULL-terminated string containing the PEM encoding of + /** cert_chain is the NULL-terminated string containing the PEM encoding of the client's certificate chain. */ const char *cert_chain; } grpc_ssl_pem_key_cert_pair; -/* Creates an SSL credentials object. +/** Creates an SSL credentials object. - pem_root_certs is the NULL-terminated string containing the PEM encoding of the server root certificates. If this parameter is NULL, the implementation will first try to dereference the file pointed by the @@ -172,7 +172,7 @@ GRPCAPI grpc_channel_credentials *grpc_ssl_credentials_create( const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pair, void *reserved); -/* --- grpc_call_credentials object. +/** --- grpc_call_credentials object. A call credentials object represents a way to authenticate on a particular call. These credentials can be composed with a channel credentials object @@ -180,21 +180,21 @@ GRPCAPI grpc_channel_credentials *grpc_ssl_credentials_create( typedef struct grpc_call_credentials grpc_call_credentials; -/* Releases a call credentials object. +/** Releases a call credentials object. The creator of the credentials object is responsible for its release. */ GRPCAPI void grpc_call_credentials_release(grpc_call_credentials *creds); -/* Creates a composite channel credentials object. */ +/** Creates a composite channel credentials object. */ GRPCAPI grpc_channel_credentials *grpc_composite_channel_credentials_create( grpc_channel_credentials *channel_creds, grpc_call_credentials *call_creds, void *reserved); -/* Creates a composite call credentials object. */ +/** Creates a composite call credentials object. */ GRPCAPI grpc_call_credentials *grpc_composite_call_credentials_create( grpc_call_credentials *creds1, grpc_call_credentials *creds2, void *reserved); -/* Creates a compute engine credentials object for connecting to Google. +/** Creates a compute engine credentials object for connecting to Google. WARNING: Do NOT use this credentials to connect to a non-google service as this could result in an oauth2 token leak. */ GRPCAPI grpc_call_credentials *grpc_google_compute_engine_credentials_create( @@ -202,7 +202,7 @@ GRPCAPI grpc_call_credentials *grpc_google_compute_engine_credentials_create( GRPCAPI gpr_timespec grpc_max_auth_token_lifetime(); -/* Creates a JWT credentials object. May return NULL if the input is invalid. +/** Creates a JWT credentials object. May return NULL if the input is invalid. - json_key is the JSON key string containing the client's private key. - token_lifetime is the lifetime of each Json Web Token (JWT) created with this credentials. It should not exceed grpc_max_auth_token_lifetime or @@ -212,7 +212,7 @@ grpc_service_account_jwt_access_credentials_create(const char *json_key, gpr_timespec token_lifetime, void *reserved); -/* Creates an Oauth2 Refresh Token credentials object for connecting to Google. +/** Creates an Oauth2 Refresh Token credentials object for connecting to Google. May return NULL if the input is invalid. WARNING: Do NOT use this credentials to connect to a non-google service as this could result in an oauth2 token leak. @@ -221,17 +221,17 @@ grpc_service_account_jwt_access_credentials_create(const char *json_key, GRPCAPI grpc_call_credentials *grpc_google_refresh_token_credentials_create( const char *json_refresh_token, void *reserved); -/* Creates an Oauth2 Access Token credentials with an access token that was +/** Creates an Oauth2 Access Token credentials with an access token that was aquired by an out of band mechanism. */ GRPCAPI grpc_call_credentials *grpc_access_token_credentials_create( const char *access_token, void *reserved); -/* Creates an IAM credentials object for connecting to Google. */ +/** Creates an IAM credentials object for connecting to Google. */ GRPCAPI grpc_call_credentials *grpc_google_iam_credentials_create( const char *authorization_token, const char *authority_selector, void *reserved); -/* Callback function to be called by the metadata credentials plugin +/** Callback function to be called by the metadata credentials plugin implementation when the metadata is ready. - user_data is the opaque pointer that was passed in the get_metadata method of the grpc_metadata_credentials_plugin (see below). @@ -246,31 +246,31 @@ typedef void (*grpc_credentials_plugin_metadata_cb)( void *user_data, const grpc_metadata *creds_md, size_t num_creds_md, grpc_status_code status, const char *error_details); -/* Context that can be used by metadata credentials plugin in order to create +/** Context that can be used by metadata credentials plugin in order to create auth related metadata. */ typedef struct { - /* The fully qualifed service url. */ + /** The fully qualifed service url. */ const char *service_url; - /* The method name of the RPC being called (not fully qualified). + /** The method name of the RPC being called (not fully qualified). The fully qualified method name can be built from the service_url: full_qualified_method_name = ctx->service_url + '/' + ctx->method_name. */ const char *method_name; - /* The auth_context of the channel which gives the server's identity. */ + /** The auth_context of the channel which gives the server's identity. */ const grpc_auth_context *channel_auth_context; - /* Reserved for future use. */ + /** Reserved for future use. */ void *reserved; } grpc_auth_metadata_context; -/* grpc_metadata_credentials plugin is an API user provided structure used to +/** grpc_metadata_credentials plugin is an API user provided structure used to create grpc_credentials objects that can be set on a channel (composed) or a call. See grpc_credentials_metadata_create_from_plugin below. The grpc client stack will call the get_metadata method of the plugin for every call in scope for the credentials created from it. */ typedef struct { - /* The implementation of this method has to be non-blocking. + /** The implementation of this method has to be non-blocking. - context is the information that can be used by the plugin to create auth metadata. - cb is the callback that needs to be called when the metadata is ready. @@ -278,39 +278,39 @@ typedef struct { void (*get_metadata)(void *state, grpc_auth_metadata_context context, grpc_credentials_plugin_metadata_cb cb, void *user_data); - /* Destroys the plugin state. */ + /** Destroys the plugin state. */ void (*destroy)(void *state); - /* State that will be set as the first parameter of the methods above. */ + /** State that will be set as the first parameter of the methods above. */ void *state; - /* Type of credentials that this plugin is implementing. */ + /** Type of credentials that this plugin is implementing. */ const char *type; } grpc_metadata_credentials_plugin; -/* Creates a credentials object from a plugin. */ +/** Creates a credentials object from a plugin. */ GRPCAPI grpc_call_credentials *grpc_metadata_credentials_create_from_plugin( grpc_metadata_credentials_plugin plugin, void *reserved); -/* --- Secure channel creation. --- */ +/** --- Secure channel creation. --- */ -/* Creates a secure channel using the passed-in credentials. */ +/** Creates a secure channel using the passed-in credentials. */ GRPCAPI grpc_channel *grpc_secure_channel_create( grpc_channel_credentials *creds, const char *target, const grpc_channel_args *args, void *reserved); -/* --- grpc_server_credentials object. --- +/** --- grpc_server_credentials object. --- A server credentials object represents a way to authenticate a server. */ typedef struct grpc_server_credentials grpc_server_credentials; -/* Releases a server_credentials object. +/** Releases a server_credentials object. The creator of the server_credentials object is responsible for its release. */ GRPCAPI void grpc_server_credentials_release(grpc_server_credentials *creds); -/* Deprecated in favor of grpc_ssl_server_credentials_create_ex. +/** Deprecated in favor of grpc_ssl_server_credentials_create_ex. Creates an SSL server_credentials object. - pem_roots_cert is the NULL-terminated string containing the PEM encoding of the client root certificates. This parameter may be NULL if the server does @@ -326,7 +326,7 @@ GRPCAPI grpc_server_credentials *grpc_ssl_server_credentials_create( const char *pem_root_certs, grpc_ssl_pem_key_cert_pair *pem_key_cert_pairs, size_t num_key_cert_pairs, int force_client_auth, void *reserved); -/* Same as grpc_ssl_server_credentials_create method except uses +/** Same as grpc_ssl_server_credentials_create method except uses grpc_ssl_client_certificate_request_type enum to support more ways to authenticate client cerificates.*/ GRPCAPI grpc_server_credentials *grpc_ssl_server_credentials_create_ex( @@ -335,25 +335,25 @@ GRPCAPI grpc_server_credentials *grpc_ssl_server_credentials_create_ex( grpc_ssl_client_certificate_request_type client_certificate_request, void *reserved); -/* --- Server-side secure ports. --- */ +/** --- Server-side secure ports. --- */ -/* Add a HTTP2 over an encrypted link over tcp listener. +/** Add a HTTP2 over an encrypted link over tcp listener. Returns bound port number on success, 0 on failure. REQUIRES: server not started */ GRPCAPI int grpc_server_add_secure_http2_port(grpc_server *server, const char *addr, grpc_server_credentials *creds); -/* --- Call specific credentials. --- */ +/** --- Call specific credentials. --- */ -/* Sets a credentials to a call. Can only be called on the client side before +/** Sets a credentials to a call. Can only be called on the client side before grpc_call_start_batch. */ GRPCAPI grpc_call_error grpc_call_set_credentials(grpc_call *call, grpc_call_credentials *creds); -/* --- Auth Metadata Processing --- */ +/** --- Auth Metadata Processing --- */ -/* Callback function that is called when the metadata processing is done. +/** Callback function that is called when the metadata processing is done. - Consumed metadata will be removed from the set of metadata available on the call. consumed_md may be NULL if no metadata has been consumed. - Response metadata will be set on the response. response_md may be NULL. @@ -367,9 +367,9 @@ typedef void (*grpc_process_auth_metadata_done_cb)( const grpc_metadata *response_md, size_t num_response_md, grpc_status_code status, const char *error_details); -/* Pluggable server-side metadata processor object. */ +/** Pluggable server-side metadata processor object. */ typedef struct { - /* The context object is read/write: it contains the properties of the + /** The context object is read/write: it contains the properties of the channel peer and it is the job of the process function to augment it with properties derived from the passed-in metadata. The lifetime of these objects is guaranteed until cb is invoked. */ diff --git a/include/grpc/grpc_security_constants.h b/include/grpc/grpc_security_constants.h index da05c5a97b..d7ac0b2745 100644 --- a/include/grpc/grpc_security_constants.h +++ b/include/grpc/grpc_security_constants.h @@ -45,30 +45,30 @@ extern "C" { #define GRPC_X509_SAN_PROPERTY_NAME "x509_subject_alternative_name" #define GRPC_X509_PEM_CERT_PROPERTY_NAME "x509_pem_cert" -/* Environment variable that points to the default SSL roots file. This file +/** Environment variable that points to the default SSL roots file. This file must be a PEM encoded file with all the roots such as the one that can be downloaded from https://pki.google.com/roots.pem. */ #define GRPC_DEFAULT_SSL_ROOTS_FILE_PATH_ENV_VAR \ "GRPC_DEFAULT_SSL_ROOTS_FILE_PATH" -/* Environment variable that points to the google default application +/** Environment variable that points to the google default application credentials json key or refresh token. Used in the grpc_google_default_credentials_create function. */ #define GRPC_GOOGLE_CREDENTIALS_ENV_VAR "GOOGLE_APPLICATION_CREDENTIALS" -/* Results for the SSL roots override callback. */ +/** Results for the SSL roots override callback. */ typedef enum { GRPC_SSL_ROOTS_OVERRIDE_OK, - GRPC_SSL_ROOTS_OVERRIDE_FAIL_PERMANENTLY, /* Do not try fallback options. */ + GRPC_SSL_ROOTS_OVERRIDE_FAIL_PERMANENTLY, /** Do not try fallback options. */ GRPC_SSL_ROOTS_OVERRIDE_FAIL } grpc_ssl_roots_override_result; typedef enum { - /* Server does not request client certificate. A client can present a self + /** Server does not request client certificate. A client can present a self signed or signed certificates if it wishes to do so and they would be accepted. */ GRPC_SSL_DONT_REQUEST_CLIENT_CERTIFICATE, - /* Server requests client certificate but does not enforce that the client + /** Server requests client certificate but does not enforce that the client presents a certificate. If the client presents a certificate, the client authentication is left to @@ -77,7 +77,7 @@ typedef enum { The key cert pair should still be valid for the SSL connection to be established. */ GRPC_SSL_REQUEST_CLIENT_CERTIFICATE_BUT_DONT_VERIFY, - /* Server requests client certificate but does not enforce that the client + /** Server requests client certificate but does not enforce that the client presents a certificate. If the client presents a certificate, the client authentication is done by @@ -87,7 +87,7 @@ typedef enum { The key cert pair should still be valid for the SSL connection to be established. */ GRPC_SSL_REQUEST_CLIENT_CERTIFICATE_AND_VERIFY, - /* Server requests client certificate but enforces that the client presents a + /** Server requests client certificate but enforces that the client presents a certificate. If the client presents a certificate, the client authentication is left to @@ -96,7 +96,7 @@ typedef enum { The key cert pair should still be valid for the SSL connection to be established. */ GRPC_SSL_REQUEST_AND_REQUIRE_CLIENT_CERTIFICATE_BUT_DONT_VERIFY, - /* Server requests client certificate but enforces that the client presents a + /** Server requests client certificate but enforces that the client presents a certificate. The cerificate presented by the client is verified by grpc framework (The diff --git a/include/grpc/impl/codegen/atm.h b/include/grpc/impl/codegen/atm.h index 4bd572d6d1..d348f32f67 100644 --- a/include/grpc/impl/codegen/atm.h +++ b/include/grpc/impl/codegen/atm.h @@ -34,7 +34,7 @@ #ifndef GRPC_IMPL_CODEGEN_ATM_H #define GRPC_IMPL_CODEGEN_ATM_H -/* This interface provides atomic operations and barriers. +/** This interface provides atomic operations and barriers. It is internal to gpr support code and should not be used outside it. If an operation with acquire semantics precedes another memory access by the diff --git a/include/grpc/impl/codegen/atm_windows.h b/include/grpc/impl/codegen/atm_windows.h index a533651f6f..fa842a3048 100644 --- a/include/grpc/impl/codegen/atm_windows.h +++ b/include/grpc/impl/codegen/atm_windows.h @@ -34,7 +34,7 @@ #ifndef GRPC_IMPL_CODEGEN_ATM_WINDOWS_H #define GRPC_IMPL_CODEGEN_ATM_WINDOWS_H -/* Win32 variant of atm_platform.h */ +/** Win32 variant of atm_platform.h */ #include <grpc/impl/codegen/port_platform.h> typedef intptr_t gpr_atm; @@ -64,7 +64,7 @@ static __inline void gpr_atm_no_barrier_store(gpr_atm *p, gpr_atm value) { } static __inline int gpr_atm_no_barrier_cas(gpr_atm *p, gpr_atm o, gpr_atm n) { -/* InterlockedCompareExchangePointerNoFence() not available on vista or +/** InterlockedCompareExchangePointerNoFence() not available on vista or windows7 */ #ifdef GPR_ARCH_64 return o == (gpr_atm)InterlockedCompareExchangeAcquire64( @@ -107,7 +107,7 @@ static __inline int gpr_atm_full_cas(gpr_atm *p, gpr_atm o, gpr_atm n) { static __inline gpr_atm gpr_atm_no_barrier_fetch_add(gpr_atm *p, gpr_atm delta) { - /* Use the CAS operation to get pointer-sized fetch and add */ + /** Use the CAS operation to get pointer-sized fetch and add */ gpr_atm old; do { old = *p; @@ -116,7 +116,7 @@ static __inline gpr_atm gpr_atm_no_barrier_fetch_add(gpr_atm *p, } static __inline gpr_atm gpr_atm_full_fetch_add(gpr_atm *p, gpr_atm delta) { - /* Use a CAS operation to get pointer-sized fetch and add */ + /** Use a CAS operation to get pointer-sized fetch and add */ gpr_atm old; #ifdef GPR_ARCH_64 do { diff --git a/include/grpc/impl/codegen/byte_buffer_reader.h b/include/grpc/impl/codegen/byte_buffer_reader.h index 85a4864140..354a28a14e 100644 --- a/include/grpc/impl/codegen/byte_buffer_reader.h +++ b/include/grpc/impl/codegen/byte_buffer_reader.h @@ -43,9 +43,9 @@ struct grpc_byte_buffer; struct grpc_byte_buffer_reader { struct grpc_byte_buffer *buffer_in; struct grpc_byte_buffer *buffer_out; - /* Different current objects correspond to different types of byte buffers */ + /** Different current objects correspond to different types of byte buffers */ union { - /* Index into a slice buffer's array of slices */ + /** Index into a slice buffer's array of slices */ unsigned index; } current; }; diff --git a/include/grpc/impl/codegen/compression_types.h b/include/grpc/impl/codegen/compression_types.h index a563711e32..953b51d9c4 100644 --- a/include/grpc/impl/codegen/compression_types.h +++ b/include/grpc/impl/codegen/compression_types.h @@ -67,7 +67,7 @@ extern "C" { "grpc.compression_enabled_algorithms_bitset" /** \} */ -/* The various compression algorithms supported by gRPC */ +/** The various compression algorithms supported by gRPC */ typedef enum { GRPC_COMPRESS_NONE = 0, GRPC_COMPRESS_DEFLATE, diff --git a/include/grpc/impl/codegen/gpr_slice.h b/include/grpc/impl/codegen/gpr_slice.h index c62e976b8f..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/gpr_types.h b/include/grpc/impl/codegen/gpr_types.h index 34d8156b61..ee4425233d 100644 --- a/include/grpc/impl/codegen/gpr_types.h +++ b/include/grpc/impl/codegen/gpr_types.h @@ -42,22 +42,22 @@ extern "C" { #endif -/* The clocks we support. */ +/** The clocks we support. */ typedef enum { - /* Monotonic clock. Epoch undefined. Always moves forwards. */ + /** Monotonic clock. Epoch undefined. Always moves forwards. */ GPR_CLOCK_MONOTONIC = 0, - /* Realtime clock. May jump forwards or backwards. Settable by + /** Realtime clock. May jump forwards or backwards. Settable by the system administrator. Has its epoch at 0:00:00 UTC 1 Jan 1970. */ GPR_CLOCK_REALTIME, - /* CPU cycle time obtained by rdtsc instruction on x86 platforms. Epoch + /** CPU cycle time obtained by rdtsc instruction on x86 platforms. Epoch undefined. Degrades to GPR_CLOCK_REALTIME on other platforms. */ GPR_CLOCK_PRECISE, - /* Unmeasurable clock type: no base, created by taking the difference + /** Unmeasurable clock type: no base, created by taking the difference between two times */ GPR_TIMESPAN } gpr_clock_type; -/* Analogous to struct timespec. On some machines, absolute times may be in +/** Analogous to struct timespec. On some machines, absolute times may be in * local time. */ typedef struct gpr_timespec { int64_t tv_sec; diff --git a/include/grpc/impl/codegen/grpc_types.h b/include/grpc/impl/codegen/grpc_types.h index ffb5a77d79..072452cec3 100644 --- a/include/grpc/impl/codegen/grpc_types.h +++ b/include/grpc/impl/codegen/grpc_types.h @@ -50,7 +50,7 @@ extern "C" { typedef enum { GRPC_BB_RAW - /* Future types may include GRPC_BB_PROTOBUF, etc. */ + /** Future types may include GRPC_BB_PROTOBUF, etc. */ } grpc_byte_buffer_type; typedef struct grpc_byte_buffer { @@ -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,7 +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. */ +/** \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. */ @@ -170,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. */ @@ -182,7 +183,7 @@ typedef struct { /** Enable/disable support for deadline checking. Defaults to 1, unless GRPC_ARG_MINIMAL_STACK is enabled, in which case it defaults to 0 */ #define GRPC_ARG_ENABLE_DEADLINE_CHECKS "grpc.enable_deadline_checking" -/** Initial sequence number for http2 transports. Int valued. */ +/** Initial stream ID for http2 transports. Int valued. */ #define GRPC_ARG_HTTP2_INITIAL_SEQUENCE_NUMBER \ "grpc.http2.initial_sequence_number" /** Amount to read ahead on individual streams. Defaults to 64kb, larger @@ -197,27 +198,24 @@ typedef struct { #define GRPC_ARG_HTTP2_HPACK_TABLE_SIZE_ENCODER \ "grpc.http2.hpack_table_size.encoder" /** How big a frame are we willing to receive via HTTP2. - Min 16384, max 16777215. - Larger values give lower CPU usage for large messages, but more head of line - blocking for small messages. */ + Min 16384, max 16777215. Larger values give lower CPU usage for large + messages, but more head of line blocking for small messages. */ #define GRPC_ARG_HTTP2_MAX_FRAME_SIZE "grpc.http2.max_frame_size" /** Should BDP probing be performed? */ #define GRPC_ARG_HTTP2_BDP_PROBE "grpc.http2.bdp_probe" /** Minimum time (in milliseconds) between successive ping frames being sent */ #define GRPC_ARG_HTTP2_MIN_TIME_BETWEEN_PINGS_MS \ "grpc.http2.min_time_between_pings_ms" -/* Channel arg to override the http2 :scheme header */ +/** Channel arg to override the http2 :scheme header */ #define GRPC_ARG_HTTP2_SCHEME "grpc.http2_scheme" /** How many pings can we send before needing to send a data frame or header - frame? - (0 indicates that an infinite number of pings can be sent without sending - a data frame or header frame) */ + frame? (0 indicates that an infinite number of pings can be sent without + sending a data frame or header frame) */ #define GRPC_ARG_HTTP2_MAX_PINGS_WITHOUT_DATA \ "grpc.http2.max_pings_without_data" /** How many misbehaving pings the server can bear before sending goaway and - closing the transport? - (0 indicates that the server can bear an infinite number of misbehaving - pings) */ + closing the transport? (0 indicates that the server can bear an infinite + number of misbehaving pings) */ #define GRPC_ARG_HTTP2_MAX_PING_STRIKES "grpc.http2.max_ping_strikes" /** Minimum allowed time between two pings without sending any data frame. Int valued, seconds */ @@ -256,20 +254,22 @@ typedef struct { /** The time between the first and second connection attempts, in ms */ #define GRPC_ARG_INITIAL_RECONNECT_BACKOFF_MS \ "grpc.initial_reconnect_backoff_ms" -/* The caller of the secure_channel_create functions may override the target - name used for SSL host name checking using this channel argument which is of - type \a GRPC_ARG_STRING. This *should* be used for testing only. - If this argument is not specified, the name used for SSL host name checking - will be the target parameter (assuming that the secure channel is an SSL - channel). If this parameter is specified and the underlying is not an SSL - channel, it will just be ignored. */ +/** This *should* be used for testing only. + The caller of the secure_channel_create functions may override the target + name used for SSL host name checking using this channel argument which is of + type \a GRPC_ARG_STRING. If this argument is not specified, the name used + for SSL host name checking will be the target parameter (assuming that the + secure channel is an SSL channel). If this parameter is specified and the + underlying is not an SSL channel, it will just be ignored. */ #define GRPC_SSL_TARGET_NAME_OVERRIDE_ARG "grpc.ssl_target_name_override" -/* Maximum metadata size, in bytes. */ +/** Maximum metadata size, in bytes. Note this limit applies to the max sum of + all metadata key-value entries in a batch of headers. */ #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 (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" @@ -281,13 +281,16 @@ 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 + * channel arg is unspecified. */ #define GRPC_TCP_DEFAULT_READ_SLICE_SIZE 8192 #define GRPC_ARG_TCP_MIN_READ_CHUNK_SIZE \ "grpc.experimental.tcp_min_read_chunk_size" @@ -331,8 +334,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, @@ -340,12 +343,12 @@ typedef enum grpc_call_error { GRPC_CALL_ERROR_PAYLOAD_TYPE_MISMATCH } grpc_call_error; -/* Default send/receive message size limits in bytes. -1 for unlimited. */ -/* TODO(roth) Make this match the default receive limit after next release */ +/** Default send/receive message size limits in bytes. -1 for unlimited. */ +/** TODO(roth) Make this match the default receive limit after next release */ #define GRPC_DEFAULT_MAX_SEND_MESSAGE_LENGTH -1 #define GRPC_DEFAULT_MAX_RECV_MESSAGE_LENGTH (4 * 1024 * 1024) -/* Write Flags: */ +/** Write Flags: */ /** Hint that the write may be buffered and need not go out on the wire immediately. GRPC is free to buffer the message until the next non-buffered write, or until writes_done, but it need not buffer completely or at all. */ @@ -356,7 +359,7 @@ typedef enum grpc_call_error { /** Mask of all valid flags. */ #define GRPC_WRITE_USED_MASK (GRPC_WRITE_BUFFER_HINT | GRPC_WRITE_NO_COMPRESS) -/* Initial metadata flags */ +/** Initial metadata flags */ /** Signal that the call is idempotent */ #define GRPC_INITIAL_METADATA_IDEMPOTENT_REQUEST (0x00000010u) /** Signal that the call should not return UNAVAILABLE before it has started */ @@ -379,8 +382,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 +450,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 +474,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; @@ -513,7 +514,7 @@ typedef struct grpc_op { size_t trailing_metadata_count; grpc_metadata *trailing_metadata; grpc_status_code status; - /* optional: set to NULL if no details need sending, non-NULL if they do + /** optional: set to NULL if no details need sending, non-NULL if they do * pointer will not be retained past the start_batch call */ grpc_slice *status_details; @@ -537,8 +538,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; @@ -553,10 +553,10 @@ typedef struct grpc_op { /** Information requested from the channel. */ typedef struct { - /* If non-NULL, will be set to point to a string indicating the LB + /** If non-NULL, will be set to point to a string indicating the LB * policy name. Caller takes ownership. */ char **lb_policy_name; - /* If non-NULL, will be set to point to a string containing the + /** If non-NULL, will be set to point to a string containing the * service config used by the channel in JSON form. */ char **service_config_json; } grpc_channel_info; @@ -600,9 +600,9 @@ typedef enum { #define GRPC_CQ_CURRENT_VERSION 1 typedef struct grpc_completion_queue_attributes { - /* The version number of this structure. More fields might be added to this + /** The version number of this structure. More fields might be added to this structure in future. */ - int version; /* Set to GRPC_CQ_CURRENT_VERSION */ + int version; /** Set to GRPC_CQ_CURRENT_VERSION */ grpc_cq_completion_type cq_completion_type; diff --git a/include/grpc/impl/codegen/propagation_bits.h b/include/grpc/impl/codegen/propagation_bits.h index 4b64558764..f58edb0e8b 100644 --- a/include/grpc/impl/codegen/propagation_bits.h +++ b/include/grpc/impl/codegen/propagation_bits.h @@ -40,7 +40,7 @@ extern "C" { #endif -/* Propagation bits: this can be bitwise or-ed to form propagation_mask for +/** Propagation bits: this can be bitwise or-ed to form propagation_mask for * grpc_call */ /** Propagate deadline */ #define GRPC_PROPAGATE_DEADLINE ((uint32_t)1) @@ -50,7 +50,7 @@ extern "C" { /** Propagate cancellation */ #define GRPC_PROPAGATE_CANCELLATION ((uint32_t)8) -/* Default propagation mask: clients of the core API are encouraged to encode +/** Default propagation mask: clients of the core API are encouraged to encode deltas from this in their implementations... ie write: GRPC_PROPAGATE_DEFAULTS & ~GRPC_PROPAGATE_DEADLINE to disable deadline propagation. Doing so gives flexibility in the future to define new diff --git a/include/grpc/impl/codegen/slice.h b/include/grpc/impl/codegen/slice.h index b89a3f7910..5c01c87cb8 100644 --- a/include/grpc/impl/codegen/slice.h +++ b/include/grpc/impl/codegen/slice.h @@ -43,7 +43,7 @@ typedef struct grpc_slice grpc_slice; -/* Slice API +/** Slice API A slice represents a contiguous reference counted array of bytes. It is cheap to take references to a slice, and it is cheap to create a @@ -63,14 +63,14 @@ typedef struct grpc_slice_refcount_vtable { uint32_t (*hash)(grpc_slice slice); } grpc_slice_refcount_vtable; -/* Reference count container for grpc_slice. Contains function pointers to +/** Reference count container for grpc_slice. Contains function pointers to increment and decrement reference counts. Implementations should cleanup when the reference count drops to zero. Typically client code should not touch this, and use grpc_slice_malloc, grpc_slice_new, or grpc_slice_new_with_len instead. */ typedef struct grpc_slice_refcount { const grpc_slice_refcount_vtable *vtable; - /* If a subset of this slice is taken, use this pointer for the refcount. + /** If a subset of this slice is taken, use this pointer for the refcount. Typically points back to the refcount itself, however iterning implementations can use this to avoid a verification step on each hash or equality check */ @@ -79,7 +79,7 @@ typedef struct grpc_slice_refcount { #define GRPC_SLICE_INLINED_SIZE (sizeof(size_t) + sizeof(uint8_t *) - 1) -/* A grpc_slice s, if initialized, represents the byte range +/** A grpc_slice s, if initialized, represents the byte range s.bytes[0..s.length-1]. It can have an associated ref count which has a destruction routine to be run @@ -104,23 +104,23 @@ struct grpc_slice { #define GRPC_SLICE_BUFFER_INLINE_ELEMENTS 8 -/* Represents an expandable array of slices, to be interpreted as a +/** Represents an expandable array of slices, to be interpreted as a single item. */ typedef struct { - /* This is for internal use only. External users (i.e any code outside grpc + /** This is for internal use only. External users (i.e any code outside grpc * core) MUST NOT use this field */ grpc_slice *base_slices; - /* slices in the array (Points to the first valid grpc_slice in the array) */ + /** slices in the array (Points to the first valid grpc_slice in the array) */ grpc_slice *slices; - /* the number of slices in the array */ + /** the number of slices in the array */ size_t count; - /* the number of slices allocated in the array. External users (i.e any code + /** the number of slices allocated in the array. External users (i.e any code * outside grpc core) MUST NOT use this field */ size_t capacity; - /* the combined length of all slices in the array */ + /** the combined length of all slices in the array */ size_t length; - /* inlined elements to avoid allocations */ + /** inlined elements to avoid allocations */ grpc_slice inlined[GRPC_SLICE_BUFFER_INLINE_ELEMENTS]; } grpc_slice_buffer; diff --git a/include/grpc/impl/codegen/status.h b/include/grpc/impl/codegen/status.h index 29e4570f7c..a2ad6b19e6 100644 --- a/include/grpc/impl/codegen/status.h +++ b/include/grpc/impl/codegen/status.h @@ -39,40 +39,40 @@ extern "C" { #endif typedef enum { - /* Not an error; returned on success */ + /** Not an error; returned on success */ GRPC_STATUS_OK = 0, - /* The operation was cancelled (typically by the caller). */ + /** The operation was cancelled (typically by the caller). */ GRPC_STATUS_CANCELLED = 1, - /* Unknown error. An example of where this error may be returned is + /** Unknown error. An example of where this error may be returned is if a Status value received from another address space belongs to an error-space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error. */ GRPC_STATUS_UNKNOWN = 2, - /* Client specified an invalid argument. Note that this differs + /** Client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name). */ GRPC_STATUS_INVALID_ARGUMENT = 3, - /* Deadline expired before operation could complete. For operations + /** Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. */ GRPC_STATUS_DEADLINE_EXCEEDED = 4, - /* Some requested entity (e.g., file or directory) was not found. */ + /** Some requested entity (e.g., file or directory) was not found. */ GRPC_STATUS_NOT_FOUND = 5, - /* Some entity that we attempted to create (e.g., file or directory) + /** Some entity that we attempted to create (e.g., file or directory) already exists. */ GRPC_STATUS_ALREADY_EXISTS = 6, - /* The caller does not have permission to execute the specified + /** The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be @@ -80,15 +80,15 @@ typedef enum { instead for those errors). */ GRPC_STATUS_PERMISSION_DENIED = 7, - /* The request does not have valid authentication credentials for the + /** The request does not have valid authentication credentials for the operation. */ GRPC_STATUS_UNAUTHENTICATED = 16, - /* Some resource has been exhausted, perhaps a per-user quota, or + /** Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. */ GRPC_STATUS_RESOURCE_EXHAUSTED = 8, - /* Operation was rejected because the system is not in a state + /** Operation was rejected because the system is not in a state required for the operation's execution. For example, directory to be deleted may be non-empty, an rmdir operation is applied to a non-directory, etc. @@ -109,14 +109,14 @@ typedef enum { read-modify-write on the same resource. */ GRPC_STATUS_FAILED_PRECONDITION = 9, - /* The operation was aborted, typically due to a concurrency issue + /** The operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc. See litmus test above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE. */ GRPC_STATUS_ABORTED = 10, - /* Operation was attempted past the valid range. E.g., seeking or + /** Operation was attempted past the valid range. E.g., seeking or reading past end of file. Unlike INVALID_ARGUMENT, this error indicates a problem that may @@ -133,26 +133,31 @@ typedef enum { they are done. */ GRPC_STATUS_OUT_OF_RANGE = 11, - /* Operation is not implemented or not supported/enabled in this service. */ + /** Operation is not implemented or not supported/enabled in this service. */ GRPC_STATUS_UNIMPLEMENTED = 12, - /* Internal errors. Means some invariants expected by underlying + /** Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. */ GRPC_STATUS_INTERNAL = 13, - /* The service is currently unavailable. This is a most likely a + /** 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. */ GRPC_STATUS_UNAVAILABLE = 14, - /* Unrecoverable data loss or corruption. */ + /** Unrecoverable data loss or corruption. */ GRPC_STATUS_DATA_LOSS = 15, - /* Force users to include a default branch: */ + /** Force users to include a default branch: */ GRPC_STATUS__DO_NOT_USE = -1 } grpc_status_code; diff --git a/include/grpc/impl/codegen/sync.h b/include/grpc/impl/codegen/sync.h index 6a8e8a644f..5a135fab4c 100644 --- a/include/grpc/impl/codegen/sync.h +++ b/include/grpc/impl/codegen/sync.h @@ -33,7 +33,7 @@ #ifndef GRPC_IMPL_CODEGEN_SYNC_H #define GRPC_IMPL_CODEGEN_SYNC_H -/* Synchronization primitives for GPR. +/** Synchronization primitives for GPR. The type gpr_mu provides a non-reentrant mutex (lock). diff --git a/include/grpc/slice.h b/include/grpc/slice.h index 9c4b158ae8..19f546afb6 100644 --- a/include/grpc/slice.h +++ b/include/grpc/slice.h @@ -41,11 +41,11 @@ extern "C" { #endif -/* Increment the refcount of s. Requires slice is initialized. +/** Increment the refcount of s. Requires slice is initialized. Returns s. */ GPRAPI grpc_slice grpc_slice_ref(grpc_slice s); -/* Decrement the ref count of s. If the ref count of s reaches zero, all +/** Decrement the ref count of s. If the ref count of s reaches zero, all slices sharing the ref count are destroyed, and considered no longer initialized. If s is ultimately derived from a call to grpc_slice_new(start, len, dest) where dest!=NULL , then (*dest)(start) is called, else if s is @@ -53,15 +53,15 @@ GPRAPI grpc_slice grpc_slice_ref(grpc_slice s); where dest!=NULL , then (*dest)(start, len). Requires s initialized. */ GPRAPI void grpc_slice_unref(grpc_slice s); -/* Copy slice - create a new slice that contains the same data as s */ +/** Copy slice - create a new slice that contains the same data as s */ GPRAPI grpc_slice grpc_slice_copy(grpc_slice s); -/* Create a slice pointing at some data. Calls malloc to allocate a refcount +/** Create a slice pointing at some data. Calls malloc to allocate a refcount for the object, and arranges that destroy will be called with the pointer passed in at destruction. */ GPRAPI grpc_slice grpc_slice_new(void *p, size_t len, void (*destroy)(void *)); -/* Equivalent to grpc_slice_new, but with a separate pointer that is +/** Equivalent to grpc_slice_new, but with a separate pointer that is passed to the destroy function. This function can be useful when the data is part of a larger structure that must be destroyed when the data is no longer needed. */ @@ -69,12 +69,12 @@ GPRAPI grpc_slice grpc_slice_new_with_user_data(void *p, size_t len, void (*destroy)(void *), void *user_data); -/* Equivalent to grpc_slice_new, but with a two argument destroy function that +/** Equivalent to grpc_slice_new, but with a two argument destroy function that also takes the slice length. */ GPRAPI grpc_slice grpc_slice_new_with_len(void *p, size_t len, void (*destroy)(void *, size_t)); -/* Equivalent to grpc_slice_new(malloc(len), len, free), but saves one malloc() +/** Equivalent to grpc_slice_new(malloc(len), len, free), but saves one malloc() call. Aborts if malloc() fails. */ GPRAPI grpc_slice grpc_slice_malloc(size_t length); @@ -86,13 +86,13 @@ GPRAPI grpc_slice grpc_slice_malloc_large(size_t length); .data.inlined = {.length = (uint8_t)(len)}} \ : grpc_slice_malloc_large((len))) -/* Intern a slice: +/** Intern a slice: The return value for two invocations of this function with the same sequence of bytes is a slice which points to the same memory. */ GPRAPI grpc_slice grpc_slice_intern(grpc_slice slice); -/* Create a slice by copying a string. +/** Create a slice by copying a string. Does not preserve null terminators. Equivalent to: size_t len = strlen(source); @@ -100,29 +100,29 @@ GPRAPI grpc_slice grpc_slice_intern(grpc_slice slice); memcpy(slice->data, source, len); */ GPRAPI grpc_slice grpc_slice_from_copied_string(const char *source); -/* Create a slice by copying a buffer. +/** Create a slice by copying a buffer. Equivalent to: grpc_slice slice = grpc_slice_malloc(len); memcpy(slice->data, source, len); */ GPRAPI grpc_slice grpc_slice_from_copied_buffer(const char *source, size_t len); -/* Create a slice pointing to constant memory */ +/** Create a slice pointing to constant memory */ GPRAPI grpc_slice grpc_slice_from_static_string(const char *source); -/* Create a slice pointing to constant memory */ +/** Create a slice pointing to constant memory */ GPRAPI grpc_slice grpc_slice_from_static_buffer(const void *source, size_t len); -/* Return a result slice derived from s, which shares a ref count with \a s, +/** Return a result slice derived from s, which shares a ref count with \a s, where result.data==s.data+begin, and result.length==end-begin. The ref count of \a s is increased by one. Do not assign result back to \a s. Requires s initialized, begin <= end, begin <= s.length, and end <= source->length. */ GPRAPI grpc_slice grpc_slice_sub(grpc_slice s, size_t begin, size_t end); -/* The same as grpc_slice_sub, but without altering the ref count */ +/** The same as grpc_slice_sub, but without altering the ref count */ GPRAPI grpc_slice grpc_slice_sub_no_ref(grpc_slice s, size_t begin, size_t end); -/* Splits s into two: modifies s to be s[0:split], and returns a new slice, +/** Splits s into two: modifies s to be s[0:split], and returns a new slice, sharing a refcount with s, that contains s[split:s.length]. Requires s intialized, split <= s.length */ GPRAPI grpc_slice grpc_slice_split_tail(grpc_slice *s, size_t split); @@ -133,13 +133,13 @@ typedef enum { GRPC_SLICE_REF_BOTH = 1 + 2 } grpc_slice_ref_whom; -/* The same as grpc_slice_split_tail, but with an option to skip altering +/** The same as grpc_slice_split_tail, but with an option to skip altering * refcounts (grpc_slice_split_tail_maybe_ref(..., true) is equivalent to * grpc_slice_split_tail(...)) */ GPRAPI grpc_slice grpc_slice_split_tail_maybe_ref(grpc_slice *s, size_t split, grpc_slice_ref_whom ref_whom); -/* Splits s into two: modifies s to be s[split:s.length], and returns a new +/** Splits s into two: modifies s to be s[split:s.length], and returns a new slice, sharing a refcount with s, that contains s[0:split]. Requires s intialized, split <= s.length */ GPRAPI grpc_slice grpc_slice_split_head(grpc_slice *s, size_t split); @@ -151,35 +151,35 @@ GPRAPI int grpc_slice_default_eq_impl(grpc_slice a, grpc_slice b); GPRAPI int grpc_slice_eq(grpc_slice a, grpc_slice b); -/* Returns <0 if a < b, ==0 if a == b, >0 if a > b +/** Returns <0 if a < b, ==0 if a == b, >0 if a > b The order is arbitrary, and is not guaranteed to be stable across different versions of the API. */ GPRAPI int grpc_slice_cmp(grpc_slice a, grpc_slice b); GPRAPI int grpc_slice_str_cmp(grpc_slice a, const char *b); GPRAPI int grpc_slice_buf_cmp(grpc_slice a, const void *b, size_t blen); -/* return non-zero if the first blen bytes of a are equal to b */ +/** return non-zero if the first blen bytes of a are equal to b */ GPRAPI int grpc_slice_buf_start_eq(grpc_slice a, const void *b, size_t blen); -/* return the index of the last instance of \a c in \a s, or -1 if not found */ +/** return the index of the last instance of \a c in \a s, or -1 if not found */ GPRAPI int grpc_slice_rchr(grpc_slice s, char c); GPRAPI int grpc_slice_chr(grpc_slice s, char c); -/* return the index of the first occurance of \a needle in \a haystack, or -1 if - * it's not found */ +/** return the index of the first occurance of \a needle in \a haystack, or -1 + if it's not found */ GPRAPI int grpc_slice_slice(grpc_slice haystack, grpc_slice needle); GPRAPI uint32_t grpc_slice_hash(grpc_slice s); -/* Do two slices point at the same memory, with the same length +/** Do two slices point at the same memory, with the same length If a or b is inlined, actually compares data */ GPRAPI int grpc_slice_is_equivalent(grpc_slice a, grpc_slice b); -/* Return a slice pointing to newly allocated memory that has the same contents +/** Return a slice pointing to newly allocated memory that has the same contents * as \a s */ GPRAPI grpc_slice grpc_slice_dup(grpc_slice a); -/* Return a copy of slice as a C string. Offers no protection against embedded +/** Return a copy of slice as a C string. Offers no protection against embedded NULL's. Returned string must be freed with gpr_free. */ GPRAPI char *grpc_slice_to_c_string(grpc_slice s); diff --git a/include/grpc/slice_buffer.h b/include/grpc/slice_buffer.h index cdbd74776c..0d593954dc 100644 --- a/include/grpc/slice_buffer.h +++ b/include/grpc/slice_buffer.h @@ -40,15 +40,15 @@ extern "C" { #endif -/* initialize a slice buffer */ +/** initialize a slice buffer */ GPRAPI void grpc_slice_buffer_init(grpc_slice_buffer *sb); -/* destroy a slice buffer - unrefs any held elements */ +/** destroy a slice buffer - unrefs any held elements */ GPRAPI void grpc_slice_buffer_destroy(grpc_slice_buffer *sb); -/* Add an element to a slice buffer - takes ownership of the slice. +/** Add an element to a slice buffer - takes ownership of the slice. This function is allowed to concatenate the passed in slice to the end of some other slice if desired by the slice buffer. */ GPRAPI void grpc_slice_buffer_add(grpc_slice_buffer *sb, grpc_slice slice); -/* add an element to a slice buffer - takes ownership of the slice and returns +/** add an element to a slice buffer - takes ownership of the slice and returns the index of the slice. Guarantees that the slice will not be concatenated at the end of another slice (i.e. the data for this slice will begin at the first byte of the @@ -59,35 +59,35 @@ GPRAPI size_t grpc_slice_buffer_add_indexed(grpc_slice_buffer *sb, grpc_slice slice); GPRAPI void grpc_slice_buffer_addn(grpc_slice_buffer *sb, grpc_slice *slices, size_t n); -/* add a very small (less than 8 bytes) amount of data to the end of a slice +/** add a very small (less than 8 bytes) amount of data to the end of a slice buffer: returns a pointer into which to add the data */ GPRAPI uint8_t *grpc_slice_buffer_tiny_add(grpc_slice_buffer *sb, size_t len); -/* pop the last buffer, but don't unref it */ +/** pop the last buffer, but don't unref it */ GPRAPI void grpc_slice_buffer_pop(grpc_slice_buffer *sb); -/* clear a slice buffer, unref all elements */ +/** clear a slice buffer, unref all elements */ GPRAPI void grpc_slice_buffer_reset_and_unref(grpc_slice_buffer *sb); -/* swap the contents of two slice buffers */ +/** swap the contents of two slice buffers */ GPRAPI void grpc_slice_buffer_swap(grpc_slice_buffer *a, grpc_slice_buffer *b); -/* move all of the elements of src into dst */ +/** move all of the elements of src into dst */ GPRAPI void grpc_slice_buffer_move_into(grpc_slice_buffer *src, grpc_slice_buffer *dst); -/* remove n bytes from the end of a slice buffer */ +/** remove n bytes from the end of a slice buffer */ GPRAPI void grpc_slice_buffer_trim_end(grpc_slice_buffer *src, size_t n, grpc_slice_buffer *garbage); -/* move the first n bytes of src into dst */ +/** move the first n bytes of src into dst */ GPRAPI void grpc_slice_buffer_move_first(grpc_slice_buffer *src, size_t n, grpc_slice_buffer *dst); -/* move the first n bytes of src into dst without adding references */ +/** move the first n bytes of src into dst without adding references */ GPRAPI void grpc_slice_buffer_move_first_no_ref(grpc_slice_buffer *src, size_t n, grpc_slice_buffer *dst); -/* move the first n bytes of src into dst (copying them) */ +/** move the first n bytes of src into dst (copying them) */ GPRAPI void grpc_slice_buffer_move_first_into_buffer(grpc_exec_ctx *exec_ctx, grpc_slice_buffer *src, size_t n, void *dst); -/* take the first slice in the slice buffer */ +/** take the first slice in the slice buffer */ GPRAPI grpc_slice grpc_slice_buffer_take_first(grpc_slice_buffer *src); -/* undo the above with (a possibly different) \a slice */ +/** undo the above with (a possibly different) \a slice */ GPRAPI void grpc_slice_buffer_undo_take_first(grpc_slice_buffer *src, grpc_slice slice); diff --git a/include/grpc/support/alloc.h b/include/grpc/support/alloc.h index 017d75a3d0..99be2d161a 100644 --- a/include/grpc/support/alloc.h +++ b/include/grpc/support/alloc.h @@ -44,26 +44,26 @@ extern "C" { typedef struct gpr_allocation_functions { void *(*malloc_fn)(size_t size); - void *(*zalloc_fn)(size_t size); /* if NULL, uses malloc_fn then memset */ + void *(*zalloc_fn)(size_t size); /** if NULL, uses malloc_fn then memset */ void *(*realloc_fn)(void *ptr, size_t size); void (*free_fn)(void *ptr); } gpr_allocation_functions; -/* malloc. +/** malloc. * If size==0, always returns NULL. Otherwise this function never returns NULL. * The pointer returned is suitably aligned for any kind of variable it could * contain. */ GPRAPI void *gpr_malloc(size_t size); -/* like malloc, but zero all bytes before returning them */ +/** like malloc, but zero all bytes before returning them */ GPRAPI void *gpr_zalloc(size_t size); -/* free */ +/** free */ GPRAPI void gpr_free(void *ptr); -/* realloc, never returns NULL */ +/** realloc, never returns NULL */ GPRAPI void *gpr_realloc(void *p, size_t size); -/* aligned malloc, never returns NULL, will align to 1 << alignment_log */ +/** aligned malloc, never returns NULL, will align to 1 << alignment_log */ GPRAPI void *gpr_malloc_aligned(size_t size, size_t alignment_log); -/* free memory allocated by gpr_malloc_aligned */ +/** free memory allocated by gpr_malloc_aligned */ GPRAPI void gpr_free_aligned(void *ptr); /** Request the family of allocation functions in \a functions be used. NOTE diff --git a/include/grpc/support/cmdline.h b/include/grpc/support/cmdline.h index 5b7bc82594..5a83afb464 100644 --- a/include/grpc/support/cmdline.h +++ b/include/grpc/support/cmdline.h @@ -40,7 +40,7 @@ extern "C" { #endif -/* Simple command line parser. +/** Simple command line parser. Supports flags that can be specified as -foo, --foo, --no-foo, -no-foo, etc And integers, strings that can be specified as -foo=4, -foo blah, etc @@ -68,32 +68,32 @@ extern "C" { typedef struct gpr_cmdline gpr_cmdline; -/* Construct a command line parser: takes a short description of the tool +/** Construct a command line parser: takes a short description of the tool doing the parsing */ GPRAPI gpr_cmdline *gpr_cmdline_create(const char *description); -/* Add an integer parameter, with a name (used on the command line) and some +/** Add an integer parameter, with a name (used on the command line) and some helpful text (used in the command usage) */ GPRAPI void gpr_cmdline_add_int(gpr_cmdline *cl, const char *name, const char *help, int *value); -/* The same, for a boolean flag */ +/** The same, for a boolean flag */ GPRAPI void gpr_cmdline_add_flag(gpr_cmdline *cl, const char *name, const char *help, int *value); -/* And for a string */ +/** And for a string */ GPRAPI void gpr_cmdline_add_string(gpr_cmdline *cl, const char *name, const char *help, char **value); -/* Set a callback for non-named arguments */ +/** Set a callback for non-named arguments */ GPRAPI void gpr_cmdline_on_extra_arg( gpr_cmdline *cl, const char *name, const char *help, void (*on_extra_arg)(void *user_data, const char *arg), void *user_data); -/* Enable surviving failure: default behavior is to exit the process */ +/** Enable surviving failure: default behavior is to exit the process */ GPRAPI void gpr_cmdline_set_survive_failure(gpr_cmdline *cl); -/* Parse the command line; returns 1 on success, on failure either dies +/** Parse the command line; returns 1 on success, on failure either dies (by default) or returns 0 if gpr_cmdline_set_survive_failure() has been called */ GPRAPI int gpr_cmdline_parse(gpr_cmdline *cl, int argc, char **argv); -/* Destroy the parser */ +/** Destroy the parser */ GPRAPI void gpr_cmdline_destroy(gpr_cmdline *cl); -/* Get a string describing usage */ +/** Get a string describing usage */ GPRAPI char *gpr_cmdline_usage_string(gpr_cmdline *cl, const char *argv0); #ifdef __cplusplus diff --git a/include/grpc/support/cpu.h b/include/grpc/support/cpu.h index 6734feb391..0da02ada22 100644 --- a/include/grpc/support/cpu.h +++ b/include/grpc/support/cpu.h @@ -40,13 +40,13 @@ extern "C" { #endif -/* Interface providing CPU information for currently running system */ +/** Interface providing CPU information for currently running system */ -/* Return the number of CPU cores on the current system. Will return 0 if +/** Return the number of CPU cores on the current system. Will return 0 if the information is not available. */ GPRAPI unsigned gpr_cpu_num_cores(void); -/* Return the CPU on which the current thread is executing; N.B. This should +/** Return the CPU on which the current thread is executing; N.B. This should be considered advisory only - it is possible that the thread is switched to a different CPU at any time. Returns a value in range [0, gpr_cpu_num_cores() - 1] */ diff --git a/include/grpc/support/histogram.h b/include/grpc/support/histogram.h index c545038528..96db758878 100644 --- a/include/grpc/support/histogram.h +++ b/include/grpc/support/histogram.h @@ -48,7 +48,7 @@ GPRAPI gpr_histogram *gpr_histogram_create(double resolution, GPRAPI void gpr_histogram_destroy(gpr_histogram *h); GPRAPI void gpr_histogram_add(gpr_histogram *h, double x); -/* The following merges the second histogram into the first. It only works +/** The following merges the second histogram into the first. It only works if they have the same buckets and resolution. Returns 0 on failure, 1 on success */ GPRAPI int gpr_histogram_merge(gpr_histogram *dst, const gpr_histogram *src); diff --git a/include/grpc/support/host_port.h b/include/grpc/support/host_port.h index 15819543a9..ee786beb19 100644 --- a/include/grpc/support/host_port.h +++ b/include/grpc/support/host_port.h @@ -40,7 +40,7 @@ extern "C" { #endif -/* Given a host and port, creates a newly-allocated string of the form +/** Given a host and port, creates a newly-allocated string of the form "host:port" or "[ho:st]:port", depending on whether the host contains colons like an IPv6 literal. If the host is already bracketed, then additional brackets will not be added. @@ -52,7 +52,7 @@ extern "C" { In the unlikely event of an error, returns -1 and sets *out to NULL. */ GPRAPI int gpr_join_host_port(char **out, const char *host, int port); -/* Given a name in the form "host:port" or "[ho:st]:port", split into hostname +/** Given a name in the form "host:port" or "[ho:st]:port", split into hostname and port number, into newly allocated strings, which must later be destroyed using gpr_free(). Return 1 on success, 0 on failure. Guarantees *host and *port == NULL on diff --git a/include/grpc/support/log.h b/include/grpc/support/log.h index 88346cc9f4..917b01183a 100644 --- a/include/grpc/support/log.h +++ b/include/grpc/support/log.h @@ -44,7 +44,7 @@ extern "C" { #endif -/* GPR log API. +/** GPR log API. Usage (within grpc): @@ -54,7 +54,7 @@ extern "C" { gpr_log(GPR_INFO, "hello world"); gpr_log(GPR_ERROR, "%d %s!!", argument1, argument2); */ -/* The severity of a log message - use the #defines below when calling into +/** The severity of a log message - use the #defines below when calling into gpr_log to additionally supply file and line data */ typedef enum gpr_log_severity { GPR_LOG_SEVERITY_DEBUG, @@ -64,15 +64,15 @@ typedef enum gpr_log_severity { #define GPR_LOG_VERBOSITY_UNSET -1 -/* Returns a string representation of the log severity */ +/** Returns a string representation of the log severity */ const char *gpr_log_severity_string(gpr_log_severity severity); -/* Macros to build log contexts at various severity levels */ +/** Macros to build log contexts at various severity levels */ #define GPR_DEBUG __FILE__, __LINE__, GPR_LOG_SEVERITY_DEBUG #define GPR_INFO __FILE__, __LINE__, GPR_LOG_SEVERITY_INFO #define GPR_ERROR __FILE__, __LINE__, GPR_LOG_SEVERITY_ERROR -/* Log a message. It's advised to use GPR_xxx above to generate the context +/** Log a message. It's advised to use GPR_xxx above to generate the context * for each message */ GPRAPI void gpr_log(const char *file, int line, gpr_log_severity severity, const char *format, ...) GPR_PRINT_FORMAT_CHECK(4, 5); @@ -80,12 +80,12 @@ GPRAPI void gpr_log(const char *file, int line, gpr_log_severity severity, GPRAPI void gpr_log_message(const char *file, int line, gpr_log_severity severity, const char *message); -/* Set global log verbosity */ +/** Set global log verbosity */ GPRAPI void gpr_set_log_verbosity(gpr_log_severity min_severity_to_print); GPRAPI void gpr_log_verbosity_init(); -/* Log overrides: applications can use this API to intercept logging calls +/** Log overrides: applications can use this API to intercept logging calls and use their own implementations */ typedef struct { @@ -98,7 +98,7 @@ typedef struct { typedef void (*gpr_log_func)(gpr_log_func_args *args); GPRAPI void gpr_set_log_function(gpr_log_func func); -/* abort() the process if x is zero, having written a line to the log. +/** abort() the process if x is zero, having written a line to the log. Intended for internal invariants. If the error can be recovered from, without the possibility of corruption, or might best be reflected via diff --git a/include/grpc/support/log_windows.h b/include/grpc/support/log_windows.h index 943a8e908b..b8a4078464 100644 --- a/include/grpc/support/log_windows.h +++ b/include/grpc/support/log_windows.h @@ -40,7 +40,7 @@ extern "C" { #endif -/* Returns a string allocated with gpr_malloc that contains a UTF-8 +/** Returns a string allocated with gpr_malloc that contains a UTF-8 * formatted error message, corresponding to the error messageid. * Use in conjunction with GetLastError() et al. */ diff --git a/include/grpc/support/string_util.h b/include/grpc/support/string_util.h index 5ab983d15d..8b268a6006 100644 --- a/include/grpc/support/string_util.h +++ b/include/grpc/support/string_util.h @@ -40,13 +40,13 @@ extern "C" { #endif -/* String utility functions */ +/** String utility functions */ -/* Returns a copy of src that can be passed to gpr_free(). +/** Returns a copy of src that can be passed to gpr_free(). If allocation fails or if src is NULL, returns NULL. */ GPRAPI char *gpr_strdup(const char *src); -/* printf to a newly-allocated string. The set of supported formats may vary +/** printf to a newly-allocated string. The set of supported formats may vary between platforms. On success, returns the number of bytes printed (excluding the final '\0'), diff --git a/include/grpc/support/subprocess.h b/include/grpc/support/subprocess.h index 2baa43ece2..dfb80989dc 100644 --- a/include/grpc/support/subprocess.h +++ b/include/grpc/support/subprocess.h @@ -42,13 +42,13 @@ extern "C" { typedef struct gpr_subprocess gpr_subprocess; -/* .exe on windows, empty on unices */ +/** .exe on windows, empty on unices */ GPRAPI const char *gpr_subprocess_binary_extension(); GPRAPI gpr_subprocess *gpr_subprocess_create(int argc, const char **argv); -/* if subprocess has not been joined, kill it */ +/** if subprocess has not been joined, kill it */ GPRAPI void gpr_subprocess_destroy(gpr_subprocess *p); -/* returns exit status; can be called at most once */ +/** returns exit status; can be called at most once */ GPRAPI int gpr_subprocess_join(gpr_subprocess *p); GPRAPI void gpr_subprocess_interrupt(gpr_subprocess *p); diff --git a/include/grpc/support/sync.h b/include/grpc/support/sync.h index 5cfeecb601..7d727a0cfc 100644 --- a/include/grpc/support/sync.h +++ b/include/grpc/support/sync.h @@ -41,49 +41,49 @@ extern "C" { #endif -/* --- Mutex interface --- +/** --- Mutex interface --- At most one thread may hold an exclusive lock on a mutex at any given time. Actions taken by a thread that holds a mutex exclusively happen after actions taken by all previous holders of the mutex. Variables of type gpr_mu are uninitialized when first declared. */ -/* Initialize *mu. Requires: *mu uninitialized. */ +/** Initialize *mu. Requires: *mu uninitialized. */ GPRAPI void gpr_mu_init(gpr_mu *mu); -/* Cause *mu no longer to be initialized, freeing any memory in use. Requires: +/** Cause *mu no longer to be initialized, freeing any memory in use. Requires: *mu initialized; no other concurrent operation on *mu. */ GPRAPI void gpr_mu_destroy(gpr_mu *mu); -/* Wait until no thread has a lock on *mu, cause the calling thread to own an +/** Wait until no thread has a lock on *mu, cause the calling thread to own an exclusive lock on *mu, then return. May block indefinitely or crash if the calling thread has a lock on *mu. Requires: *mu initialized. */ GPRAPI void gpr_mu_lock(gpr_mu *mu); -/* Release an exclusive lock on *mu held by the calling thread. Requires: *mu +/** Release an exclusive lock on *mu held by the calling thread. Requires: *mu initialized; the calling thread holds an exclusive lock on *mu. */ GPRAPI void gpr_mu_unlock(gpr_mu *mu); -/* Without blocking, attempt to acquire an exclusive lock on *mu for the +/** Without blocking, attempt to acquire an exclusive lock on *mu for the calling thread, then return non-zero iff success. Fail, if any thread holds the lock; succeeds with high probability if no thread holds the lock. Requires: *mu initialized. */ GPRAPI int gpr_mu_trylock(gpr_mu *mu); -/* --- Condition variable interface --- +/** --- Condition variable interface --- A while-loop should be used with gpr_cv_wait() when waiting for conditions to become true. See the example below. Variables of type gpr_cv are uninitialized when first declared. */ -/* Initialize *cv. Requires: *cv uninitialized. */ +/** Initialize *cv. Requires: *cv uninitialized. */ GPRAPI void gpr_cv_init(gpr_cv *cv); -/* Cause *cv no longer to be initialized, freeing any memory in use. Requires: +/** Cause *cv no longer to be initialized, freeing any memory in use. Requires: *cv initialized; no other concurrent operation on *cv.*/ GPRAPI void gpr_cv_destroy(gpr_cv *cv); -/* Atomically release *mu and wait on *cv. When the calling thread is woken +/** Atomically release *mu and wait on *cv. When the calling thread is woken from *cv or the deadline abs_deadline is exceeded, execute gpr_mu_lock(mu) and return whether the deadline was exceeded. Use abs_deadline==gpr_inf_future for no deadline. abs_deadline can be either @@ -92,83 +92,83 @@ GPRAPI void gpr_cv_destroy(gpr_cv *cv); holds an exclusive lock on *mu. */ GPRAPI int gpr_cv_wait(gpr_cv *cv, gpr_mu *mu, gpr_timespec abs_deadline); -/* If any threads are waiting on *cv, wake at least one. +/** If any threads are waiting on *cv, wake at least one. Clients may treat this as an optimization of gpr_cv_broadcast() for use in the case where waking more than one waiter is not useful. Requires: *cv initialized. */ GPRAPI void gpr_cv_signal(gpr_cv *cv); -/* Wake all threads waiting on *cv. Requires: *cv initialized. */ +/** Wake all threads waiting on *cv. Requires: *cv initialized. */ GPRAPI void gpr_cv_broadcast(gpr_cv *cv); -/* --- One-time initialization --- +/** --- One-time initialization --- gpr_once must be declared with static storage class, and initialized with GPR_ONCE_INIT. e.g., static gpr_once once_var = GPR_ONCE_INIT; */ -/* Ensure that (*init_routine)() has been called exactly once (for the +/** Ensure that (*init_routine)() has been called exactly once (for the specified gpr_once instance) and then return. If multiple threads call gpr_once() on the same gpr_once instance, one of them will call (*init_routine)(), and the others will block until that call finishes.*/ GPRAPI void gpr_once_init(gpr_once *once, void (*init_routine)(void)); -/* --- One-time event notification --- +/** --- One-time event notification --- These operations act on a gpr_event, which should be initialized with gpr_ev_init(), or with GPR_EVENT_INIT if static, e.g., static gpr_event event_var = GPR_EVENT_INIT; It requires no destruction. */ -/* Initialize *ev. */ +/** Initialize *ev. */ GPRAPI void gpr_event_init(gpr_event *ev); -/* Set *ev so that gpr_event_get() and gpr_event_wait() will return value. +/** Set *ev so that gpr_event_get() and gpr_event_wait() will return value. Requires: *ev initialized; value != NULL; no prior or concurrent calls to gpr_event_set(ev, ...) since initialization. */ GPRAPI void gpr_event_set(gpr_event *ev, void *value); -/* Return the value set by gpr_event_set(ev, ...), or NULL if no such call has +/** Return the value set by gpr_event_set(ev, ...), or NULL if no such call has completed. If the result is non-NULL, all operations that occurred prior to the gpr_event_set(ev, ...) set will be visible after this call returns. Requires: *ev initialized. This operation is faster than acquiring a mutex on most platforms. */ GPRAPI void *gpr_event_get(gpr_event *ev); -/* Wait until *ev is set by gpr_event_set(ev, ...), or abs_deadline is +/** Wait until *ev is set by gpr_event_set(ev, ...), or abs_deadline is exceeded, then return gpr_event_get(ev). Requires: *ev initialized. Use abs_deadline==gpr_inf_future for no deadline. When the event has been signalled before the call, this operation is faster than acquiring a mutex on most platforms. */ GPRAPI void *gpr_event_wait(gpr_event *ev, gpr_timespec abs_deadline); -/* --- Reference counting --- +/** --- Reference counting --- These calls act on the type gpr_refcount. It requires no destruction. */ -/* Initialize *r to value n. */ +/** Initialize *r to value n. */ GPRAPI void gpr_ref_init(gpr_refcount *r, int n); -/* Increment the reference count *r. Requires *r initialized. */ +/** Increment the reference count *r. Requires *r initialized. */ GPRAPI void gpr_ref(gpr_refcount *r); -/* Increment the reference count *r. Requires *r initialized. +/** Increment the reference count *r. Requires *r initialized. Crashes if refcount is zero */ GPRAPI void gpr_ref_non_zero(gpr_refcount *r); -/* Increment the reference count *r by n. Requires *r initialized, n > 0. */ +/** Increment the reference count *r by n. Requires *r initialized, n > 0. */ GPRAPI void gpr_refn(gpr_refcount *r, int n); -/* Decrement the reference count *r and return non-zero iff it has reached +/** Decrement the reference count *r and return non-zero iff it has reached zero. . Requires *r initialized. */ GPRAPI int gpr_unref(gpr_refcount *r); -/* Return non-zero iff the reference count of *r is one, and thus is owned +/** Return non-zero iff the reference count of *r is one, and thus is owned by exactly one object. */ GPRAPI int gpr_ref_is_unique(gpr_refcount *r); -/* --- Stats counters --- +/** --- Stats counters --- These calls act on the integral type gpr_stats_counter. It requires no destruction. Static instances may be initialized with @@ -176,16 +176,16 @@ GPRAPI int gpr_ref_is_unique(gpr_refcount *r); Beware: These operations do not imply memory barriers. Do not use them to synchronize other events. */ -/* Initialize *c to the value n. */ +/** Initialize *c to the value n. */ GPRAPI void gpr_stats_init(gpr_stats_counter *c, intptr_t n); -/* *c += inc. Requires: *c initialized. */ +/** *c += inc. Requires: *c initialized. */ GPRAPI void gpr_stats_inc(gpr_stats_counter *c, intptr_t inc); -/* Return *c. Requires: *c initialized. */ +/** Return *c. Requires: *c initialized. */ GPRAPI intptr_t gpr_stats_read(const gpr_stats_counter *c); -/* ==================Example use of interface=================== +/** ==================Example use of interface=================== A producer-consumer queue of up to N integers, illustrating the use of the calls in this interface. */ #if 0 diff --git a/include/grpc/support/thd.h b/include/grpc/support/thd.h index 0514288793..ba6cbb0cb0 100644 --- a/include/grpc/support/thd.h +++ b/include/grpc/support/thd.h @@ -33,7 +33,7 @@ #ifndef GRPC_SUPPORT_THD_H #define GRPC_SUPPORT_THD_H -/* Thread interface for GPR. +/** Thread interface for GPR. Types gpr_thd_id a thread identifier. @@ -50,37 +50,37 @@ extern "C" { typedef uintptr_t gpr_thd_id; -/* Thread creation options. */ +/** Thread creation options. */ typedef struct { - int flags; /* Opaque field. Get and set with accessors below. */ + int flags; /** Opaque field. Get and set with accessors below. */ } gpr_thd_options; -/* Create a new thread running (*thd_body)(arg) and place its thread identifier +/** Create a new thread running (*thd_body)(arg) and place its thread identifier in *t, and return true. If there are insufficient resources, return false. If options==NULL, default options are used. The thread is immediately runnable, and exits when (*thd_body)() returns. */ GPRAPI int gpr_thd_new(gpr_thd_id *t, void (*thd_body)(void *arg), void *arg, const gpr_thd_options *options); -/* Return a gpr_thd_options struct with all fields set to defaults. */ +/** Return a gpr_thd_options struct with all fields set to defaults. */ GPRAPI gpr_thd_options gpr_thd_options_default(void); -/* Set the thread to become detached on startup - this is the default. */ +/** Set the thread to become detached on startup - this is the default. */ GPRAPI void gpr_thd_options_set_detached(gpr_thd_options *options); -/* Set the thread to become joinable - mutually exclusive with detached. */ +/** Set the thread to become joinable - mutually exclusive with detached. */ GPRAPI void gpr_thd_options_set_joinable(gpr_thd_options *options); -/* Returns non-zero if the option detached is set. */ +/** Returns non-zero if the option detached is set. */ GPRAPI int gpr_thd_options_is_detached(const gpr_thd_options *options); -/* Returns non-zero if the option joinable is set. */ +/** Returns non-zero if the option joinable is set. */ GPRAPI int gpr_thd_options_is_joinable(const gpr_thd_options *options); -/* Returns the identifier of the current thread. */ +/** Returns the identifier of the current thread. */ GPRAPI gpr_thd_id gpr_thd_currentid(void); -/* Blocks until the specified thread properly terminates. +/** Blocks until the specified thread properly terminates. Calling this on a detached thread has unpredictable results. */ GPRAPI void gpr_thd_join(gpr_thd_id t); diff --git a/include/grpc/support/time.h b/include/grpc/support/time.h index 66bcfca6ed..2384f5e906 100644 --- a/include/grpc/support/time.h +++ b/include/grpc/support/time.h @@ -43,11 +43,11 @@ extern "C" { #endif -/* Time constants. */ +/** Time constants. */ GPRAPI gpr_timespec -gpr_time_0(gpr_clock_type type); /* The zero time interval. */ -GPRAPI gpr_timespec gpr_inf_future(gpr_clock_type type); /* The far future */ -GPRAPI gpr_timespec gpr_inf_past(gpr_clock_type type); /* The far past. */ +gpr_time_0(gpr_clock_type type); /** The zero time interval. */ +GPRAPI gpr_timespec gpr_inf_future(gpr_clock_type type); /** The far future */ +GPRAPI gpr_timespec gpr_inf_past(gpr_clock_type type); /** The far past. */ #define GPR_MS_PER_SEC 1000 #define GPR_US_PER_SEC 1000000 @@ -56,28 +56,28 @@ GPRAPI gpr_timespec gpr_inf_past(gpr_clock_type type); /* The far past. */ #define GPR_NS_PER_US 1000 #define GPR_US_PER_MS 1000 -/* initialize time subsystem */ +/** initialize time subsystem */ GPRAPI void gpr_time_init(void); -/* Return the current time measured from the given clocks epoch. */ +/** Return the current time measured from the given clocks epoch. */ GPRAPI gpr_timespec gpr_now(gpr_clock_type clock); -/* Convert a timespec from one clock to another */ +/** Convert a timespec from one clock to another */ GPRAPI gpr_timespec gpr_convert_clock_type(gpr_timespec t, gpr_clock_type target_clock); -/* Return -ve, 0, or +ve according to whether a < b, a == b, or a > b +/** Return -ve, 0, or +ve according to whether a < b, a == b, or a > b respectively. */ GPRAPI int gpr_time_cmp(gpr_timespec a, gpr_timespec b); GPRAPI gpr_timespec gpr_time_max(gpr_timespec a, gpr_timespec b); GPRAPI gpr_timespec gpr_time_min(gpr_timespec a, gpr_timespec b); -/* Add and subtract times. Calculations saturate at infinities. */ +/** Add and subtract times. Calculations saturate at infinities. */ GPRAPI gpr_timespec gpr_time_add(gpr_timespec a, gpr_timespec b); GPRAPI gpr_timespec gpr_time_sub(gpr_timespec a, gpr_timespec b); -/* Return a timespec representing a given number of time units. INT64_MIN is +/** Return a timespec representing a given number of time units. INT64_MIN is interpreted as gpr_inf_past, and INT64_MAX as gpr_inf_future. */ GPRAPI gpr_timespec gpr_time_from_micros(int64_t x, gpr_clock_type clock_type); GPRAPI gpr_timespec gpr_time_from_nanos(int64_t x, gpr_clock_type clock_type); @@ -88,12 +88,12 @@ GPRAPI gpr_timespec gpr_time_from_hours(int64_t x, gpr_clock_type clock_type); GPRAPI int32_t gpr_time_to_millis(gpr_timespec timespec); -/* Return 1 if two times are equal or within threshold of each other, +/** Return 1 if two times are equal or within threshold of each other, 0 otherwise */ GPRAPI int gpr_time_similar(gpr_timespec a, gpr_timespec b, gpr_timespec threshold); -/* Sleep until at least 'until' - an absolute timeout */ +/** Sleep until at least 'until' - an absolute timeout */ GPRAPI void gpr_sleep_until(gpr_timespec until); GPRAPI double gpr_timespec_to_micros(gpr_timespec t); diff --git a/include/grpc/support/tls.h b/include/grpc/support/tls.h index 5365449f0d..a48c73b26f 100644 --- a/include/grpc/support/tls.h +++ b/include/grpc/support/tls.h @@ -36,7 +36,7 @@ #include <grpc/support/port_platform.h> -/* Thread local storage. +/** Thread local storage. A minimal wrapper that should be implementable across many compilers, and implementable efficiently across most modern compilers. diff --git a/include/grpc/support/tls_gcc.h b/include/grpc/support/tls_gcc.h index a47275f6f4..9667524d34 100644 --- a/include/grpc/support/tls_gcc.h +++ b/include/grpc/support/tls_gcc.h @@ -38,7 +38,7 @@ #include <grpc/support/log.h> -/* Thread local storage based on gcc compiler primitives. +/** Thread local storage based on gcc compiler primitives. #include tls.h to use this - and see that file for documentation */ #ifndef NDEBUG @@ -58,7 +58,7 @@ struct gpr_gcc_thread_local { *((tls)->inited) = true; \ } while (0) -/* It is allowed to call gpr_tls_init after gpr_tls_destroy is called. */ +/** It is allowed to call gpr_tls_init after gpr_tls_destroy is called. */ #define gpr_tls_destroy(tls) \ do { \ GPR_ASSERT(*((tls)->inited)); \ diff --git a/include/grpc/support/tls_msvc.h b/include/grpc/support/tls_msvc.h index efc653b4e4..4ef8eeff0d 100644 --- a/include/grpc/support/tls_msvc.h +++ b/include/grpc/support/tls_msvc.h @@ -34,7 +34,7 @@ #ifndef GRPC_SUPPORT_TLS_MSVC_H #define GRPC_SUPPORT_TLS_MSVC_H -/* Thread local storage based on ms visual c compiler primitives. +/** Thread local storage based on ms visual c compiler primitives. #include tls.h to use this - and see that file for documentation */ struct gpr_msvc_thread_local { diff --git a/include/grpc/support/tls_pthread.h b/include/grpc/support/tls_pthread.h index e681da2ecd..7cc6a40645 100644 --- a/include/grpc/support/tls_pthread.h +++ b/include/grpc/support/tls_pthread.h @@ -37,7 +37,7 @@ #include <grpc/support/log.h> /* for GPR_ASSERT */ #include <pthread.h> -/* Thread local storage based on pthread library calls. +/** Thread local storage based on pthread library calls. #include tls.h to use this - and see that file for documentation */ struct gpr_pthread_thread_local { diff --git a/include/grpc/support/useful.h b/include/grpc/support/useful.h index 9d8314e4be..c261fbaa14 100644 --- a/include/grpc/support/useful.h +++ b/include/grpc/support/useful.h @@ -34,12 +34,12 @@ #ifndef GRPC_SUPPORT_USEFUL_H #define GRPC_SUPPORT_USEFUL_H -/* useful macros that don't belong anywhere else */ +/** useful macros that don't belong anywhere else */ #define GPR_MIN(a, b) ((a) < (b) ? (a) : (b)) #define GPR_MAX(a, b) ((a) > (b) ? (a) : (b)) #define GPR_CLAMP(a, min, max) ((a) < (min) ? (min) : (a) > (max) ? (max) : (a)) -/* rotl, rotr assume x is unsigned */ +/** rotl, rotr assume x is unsigned */ #define GPR_ROTL(x, n) (((x) << (n)) | ((x) >> (sizeof(x) * 8 - (n)))) #define GPR_ROTR(x, n) (((x) >> (n)) | ((x) << (sizeof(x) * 8 - (n)))) diff --git a/include/grpc/support/workaround_list.h b/include/grpc/support/workaround_list.h index 6a8aa1f955..ec4766510f 100644 --- a/include/grpc/support/workaround_list.h +++ b/include/grpc/support/workaround_list.h @@ -36,7 +36,7 @@ /* The list of IDs of server workarounds currently maintained by gRPC. For * explanation and detailed descriptions of workarounds, see - * /docs/workarounds.md + * /doc/workarounds.md */ typedef enum { GRPC_WORKAROUND_ID_CRONET_COMPRESSION = 0, |