natas_hw
/
grpc
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

cpp doc nits

This commit is contained in:
Alexander Polcyn 2017-05-03 14:49:41 -07:00
parent 3f716baa0a
commit d809a15ec4
72 changed files with 507 additions and 478 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/PROTOCOL-WEB.md
View File

@ -1,4 +1,4 @@
# Overview
# gRPC Web
gRPC-Web provides a JS client library that supports the same API
as gRPC-Node to access a gRPC service. Due to browser limitation,

4
doc/compression.md
View File

@ -1,4 +1,4 @@
## **gRPC Compression**
## gRPC Compression
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
@ -112,7 +112,7 @@ unsupported condition as well as the supported ones. The returned
1. An ill-constructed message with its [Compressed-Flag
bit](PROTOCOL-HTTP2.md#compressed-flag)
set but lacking a
"[grpc-encoding](PROTOCOL-HTTP2.md#message-encoding)"
[grpc-encoding](PROTOCOL-HTTP2.md#message-encoding)
entry different from _identity_ in its metadata MUST fail with `INTERNAL`
status, its associated description indicating the invalid Compressed-Flag
condition.

3
doc/cpp-style-guide.md
View File

@ -5,5 +5,4 @@ The majority of gRPC's C++ requirements are drawn from the [Google C++ style
guide] (https://google.github.io/styleguide/cppguide.html). Additionally,
as in C, layout rules are defined by clang-format, and all code
should be passed through clang-format. A (docker-based) script to do
so is included in [tools/distrib/clang\_format\_code.sh]
(../tools/distrib/clang_format_code.sh).
so is included in [tools/distrib/clang_format_code.sh](../tools/distrib/clang_format_code.sh).

2
doc/fail_fast.md
View File

@ -1 +1 @@
Moved to wait-for-ready.md
Moved to [wait-for-ready.md](wait-for-ready.md)

4
doc/service_config.md
View File

@ -131,8 +131,8 @@ functionality is introduced.
# Architecture
A service config is associated with a server name. The [name
resolver](naming.md) plugin, when asked to resolve a particular server
A service config is associated with a server name. The [nameresolver](naming.md)
plugin, when asked to resolve a particular server
name, will return both the resolved addresses and the service config.
TODO(roth): Design how the service config will be encoded in DNS.

2
doc/stress_test_framework.md
View File

@ -2,7 +2,7 @@
(Sree Kuchibhotla - sreek@)
> Status: This is implemented. More details at [README.md](https://github.com/grpc/grpc/blob/master/tools/run_tests/stress_test/README.md)
Status: This is implemented. More details at [README.md](https://github.com/grpc/grpc/blob/master/tools/run_tests/stress_test/README.md)
**I. GOALS**

4
include/grpc++/ext/health_check_service_server_builder_option.h
View File

@ -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 {}

4
include/grpc++/ext/proto_server_reflection_plugin.h
View File

@ -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

6
include/grpc++/generic/generic_stub.h
View File

@ -43,14 +43,14 @@ 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
std::unique_ptr<GenericClientAsyncReaderWriter> Call(
ClientContext* context, const grpc::string& method, CompletionQueue* cq,
void* tag);

18
include/grpc++/health_check_service_interface.h
View File

@ -41,26 +41,26 @@ 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.
/// NOT thread safe.
bool DefaultHealthCheckServiceEnabled();
} // namespace grpc

6
include/grpc++/impl/codegen/async_stream.h
View File

@ -155,7 +155,7 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface<R> {
ClientAsyncReader(call, context, request, tag);
}
// always allocated against a call arena, no memory free required
/// always allocated against a call arena, no memory free required
static void operator delete(void* ptr, std::size_t size) {
assert(size == sizeof(ClientAsyncReader));
}
@ -235,7 +235,7 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> {
ClientAsyncWriter(call, context, response, tag);
}
// always allocated against a call arena, no memory free required
/// always allocated against a call arena, no memory free required
static void operator delete(void* ptr, std::size_t size) {
assert(size == sizeof(ClientAsyncWriter));
}
@ -338,7 +338,7 @@ class ClientAsyncReaderWriter final
ClientAsyncReaderWriter(call, context, tag);
}
// always allocated against a call arena, no memory free required
/// always allocated against a call arena, no memory free required
static void operator delete(void* ptr, std::size_t size) {
assert(size == sizeof(ClientAsyncReaderWriter));
}

2
include/grpc++/impl/codegen/async_unary_call.h
View File

@ -71,7 +71,7 @@ class ClientAsyncResponseReader final
ClientAsyncResponseReader(call, context, request);
}
// always allocated against a call arena, no memory free required
/// always allocated against a call arena, no memory free required
static void operator delete(void* ptr, std::size_t size) {
assert(size == sizeof(ClientAsyncResponseReader));
}

4
include/grpc++/impl/codegen/call.h
View File

@ -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),

3
include/grpc++/impl/codegen/call_hook.h
View File

@ -39,7 +39,8 @@ namespace grpc {
class CallOpSetInterface;
class Call;
/// Channel and Server implement this to allow them to hook performing ops
/// An interface that Channel and Server implement to allow them to hook
/// performing ops
class CallHook {
public:
virtual ~CallHook() {}

5
include/grpc++/impl/codegen/client_context.h
View File

@ -151,6 +151,7 @@ namespace testing {
class InteropClientContextInspector;
} // namespace testing
/// Gives access to client side RPC configuration.
class ClientContext {
public:
ClientContext();
@ -325,8 +326,8 @@ class ClientContext {
};
static void SetGlobalCallbacks(GlobalCallbacks* callbacks);
// Should be used for framework-level extensions only.
// Applications never need to call this method.
/// Should be used for framework-level extensions only.
/// Applications never need to call this method.
grpc_call* c_call() { return call_; }
private:

2
include/grpc++/impl/codegen/client_unary_call.h
View File

@ -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,

3
include/grpc++/impl/codegen/completion_queue.h
View File

@ -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

8
include/grpc++/impl/codegen/completion_queue_tag.h
View File

@ -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;
};

6
include/grpc++/impl/codegen/config.h
View File

@ -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

24
include/grpc++/impl/codegen/method_handler_impl.h
View File

@ -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>

1
include/grpc++/impl/codegen/rpc_method.h
View File

@ -40,6 +40,7 @@
namespace grpc {
/// Descriptor of an RPC method
class RpcMethod {
public:
enum RpcType {

8
include/grpc++/impl/codegen/rpc_service_method.h
View File

@ -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); }

2
include/grpc++/impl/codegen/security/auth_context.h
View File

@ -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;

8
include/grpc++/impl/codegen/server_context.h
View File

@ -91,7 +91,7 @@ class InteropServerContextInspector;
class ServerContextTestSpouse;
} // namespace testing
// Interface of server side rpc context.
/// Interface of server side rpc context.
class ServerContext {
public:
ServerContext(); // for async calls
@ -106,9 +106,9 @@ class ServerContext {
void AddInitialMetadata(const grpc::string& key, const grpc::string& value);
void AddTrailingMetadata(const grpc::string& key, const grpc::string& value);
// IsCancelled is always safe to call when using sync API
// When using async API, it is only safe to call IsCancelled after
// the AsyncNotifyWhenDone tag has been delivered
/// IsCancelled is always safe to call when using sync API
/// When using async API, it is only safe to call IsCancelled after
/// the AsyncNotifyWhenDone tag has been delivered
bool IsCancelled() const;
// Cancel the Call from the server. This is a best-effort API and depending on

1
include/grpc++/impl/codegen/service_type.h
View File

@ -61,6 +61,7 @@ class ServerAsyncStreamingInterface {
virtual void BindCall(Call* call) = 0;
};
/// Desriptor of an RPC service and its various RPC methods
class Service {
public:
Service() : server_(nullptr) {}

6
include/grpc++/impl/codegen/status_code_enum.h
View File

@ -136,6 +136,12 @@ enum StatusCode {
/// The service is currently unavailable. This is a most likely a transient
/// condition and may be corrected by retrying with a backoff.
///
/// \warning: Although data MIGHT not have been transmitted when this
/// status occurs, there is NOT A GUARANTEE that the server has not seen
/// anything. So in general it is unsafe to retry on this status code
/// if the call is non-idempotent.
///
///
/// See litmus test above for deciding between FAILED_PRECONDITION, ABORTED,
/// and UNAVAILABLE.
UNAVAILABLE = 14,

16
include/grpc++/impl/codegen/string_ref.h
View File

@ -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; }

1
include/grpc++/impl/codegen/stub_options.h
View File

@ -36,6 +36,7 @@
namespace grpc {
/// Useful interface for generated stubs
class StubOptions {};
} // namespace grpc

4
include/grpc++/impl/codegen/sync_stream.h
View File

@ -516,7 +516,7 @@ class ServerReaderWriterInterface : public ServerStreamingInterface,
public WriterInterface<W>,
public ReaderInterface<R> {};
// Actual implementation of bi-directional streaming
/// Actual implementation of bi-directional streaming
namespace internal {
template <class W, class R>
class ServerReaderWriterBody final {
@ -576,7 +576,7 @@ class ServerReaderWriterBody final {
};
} // namespace internal
// class to represent the user API for a bidirectional streaming call
/// class to represent the user API for a bidirectional streaming call
template <class W, class R>
class ServerReaderWriter final : public ServerReaderWriterInterface<W, R> {
public:

17
include/grpc++/impl/codegen/time.h
View File

@ -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:
/** 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.
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:

14
include/grpc++/impl/server_builder_plugin.h
View File

@ -48,19 +48,19 @@ class ServerBuilderPlugin {
virtual ~ServerBuilderPlugin() {}
virtual grpc::string name() = 0;
// 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; }

1
include/grpc++/resource_quota.h
View File

@ -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();

22
include/grpc++/security/auth_metadata_processor.h
View File

@ -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,

18
include/grpc++/security/credentials.h
View File

@ -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,

16
include/grpc++/security/server_credentials.h
View File

@ -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;
};

16
include/grpc++/support/error_details.h
View File

@ -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

40
include/grpc++/test/mock_stream.h
View File

@ -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*));
};

8
include/grpc++/test/server_context_test_spouse.h
View File

@ -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_;
};

98
include/grpc/census.h
View File

@ -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);

2
include/grpc/grpc.h
View File

@ -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

116
include/grpc/grpc_security.h
View File

@ -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. */

18
include/grpc/grpc_security_constants.h
View File

@ -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

2
include/grpc/impl/codegen/atm.h
View File

@ -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

8
include/grpc/impl/codegen/atm_windows.h
View File

@ -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 {

4
include/grpc/impl/codegen/byte_buffer_reader.h
View File

@ -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;
};

2
include/grpc/impl/codegen/compression_types.h
View File

@ -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,

3
include/grpc/impl/codegen/gpr_slice.h
View File

@ -33,7 +33,8 @@
#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
/** 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

12
include/grpc/impl/codegen/gpr_types.h
View File

@ -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;

63
include/grpc/impl/codegen/grpc_types.h
View File

@ -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 {
@ -162,7 +162,9 @@ 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. */
@ -182,7 +184,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
@ -206,7 +208,7 @@ typedef struct {
/** 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?
@ -256,20 +258,24 @@ 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"
@ -285,9 +291,13 @@ typedef struct {
* 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"
@ -334,12 +344,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. */
@ -350,7 +360,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 */
@ -373,7 +383,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
/** 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;
@ -507,7 +518,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;
@ -547,10 +558,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;
@ -594,9 +605,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;

4
include/grpc/impl/codegen/propagation_bits.h
View File

@ -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

22
include/grpc/impl/codegen/slice.h
View File

@ -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;

41
include/grpc/impl/codegen/status.h
View File

@ -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;

2
include/grpc/impl/codegen/sync.h
View File

@ -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).

49
include/grpc/slice.h
View File

@ -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,36 @@ 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
/** 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);

30
include/grpc/slice_buffer.h
View File

@ -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);

14
include/grpc/support/alloc.h
View File

@ -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

20
include/grpc/support/cmdline.h
View File

@ -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

6
include/grpc/support/cpu.h
View File

@ -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] */

2
include/grpc/support/histogram.h
View File

@ -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);

4
include/grpc/support/host_port.h
View File

@ -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

16
include/grpc/support/log.h
View File

@ -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

2
include/grpc/support/log_windows.h
View File

@ -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.
*/

6
include/grpc/support/string_util.h
View File

@ -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'),

6
include/grpc/support/subprocess.h
View File

@ -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);

62
include/grpc/support/sync.h
View File

@ -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

22
include/grpc/support/thd.h
View File

@ -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);

24
include/grpc/support/time.h
View File

@ -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);

2
include/grpc/support/tls.h
View File

@ -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.

4
include/grpc/support/tls_gcc.h
View File

@ -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)); \

2
include/grpc/support/tls_msvc.h
View File

@ -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 {

2
include/grpc/support/tls_pthread.h
View File

@ -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 {

4
include/grpc/support/useful.h
View File

@ -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))))