Skip to content
Snippets Groups Projects
Commit c4de3a2c authored by David Garcia Quintas's avatar David Garcia Quintas
Browse files

Docstrings for Channel, ChannelCreate and ChannelArguments.

parent 4dd03f9f
Branches
Tags
No related merge requests found
...@@ -65,18 +65,19 @@ class ClientAsyncReaderWriter; ...@@ -65,18 +65,19 @@ class ClientAsyncReaderWriter;
template <class R> template <class R>
class ClientAsyncResponseReader; class ClientAsyncResponseReader;
/// Channels represent a connection to an endpoint. Created by \a CreateChannel.
class Channel GRPC_FINAL : public GrpcLibrary, class Channel GRPC_FINAL : public GrpcLibrary,
public CallHook, public CallHook,
public std::enable_shared_from_this<Channel> { public std::enable_shared_from_this<Channel> {
public: public:
~Channel(); ~Channel();
// Get the current channel state. If the channel is in IDLE and try_to_connect /// Get the current channel state. If the channel is in IDLE and try_to_connect
// is set to true, try to connect. /// is set to true, try to connect.
grpc_connectivity_state GetState(bool try_to_connect); grpc_connectivity_state GetState(bool try_to_connect);
// Return the tag on cq when the channel state is changed or deadline expires. /// Return the tag on cq when the channel state is changed or deadline expires.
// GetState needs to called to get the current state. /// GetState needs to called to get the current state.
template <typename T> template <typename T>
void NotifyOnStateChange(grpc_connectivity_state last_observed, T deadline, void NotifyOnStateChange(grpc_connectivity_state last_observed, T deadline,
CompletionQueue* cq, void* tag) { CompletionQueue* cq, void* tag) {
...@@ -84,8 +85,8 @@ class Channel GRPC_FINAL : public GrpcLibrary, ...@@ -84,8 +85,8 @@ class Channel GRPC_FINAL : public GrpcLibrary,
NotifyOnStateChangeImpl(last_observed, deadline_tp.raw_time(), cq, tag); NotifyOnStateChangeImpl(last_observed, deadline_tp.raw_time(), cq, tag);
} }
// Blocking wait for channel state change or deadline expiration. /// Blocking wait for channel state change or deadline expiration.
// GetState needs to called to get the current state. /// GetState needs to called to get the current state.
template <typename T> template <typename T>
bool WaitForStateChange(grpc_connectivity_state last_observed, T deadline) { bool WaitForStateChange(grpc_connectivity_state last_observed, T deadline) {
TimePoint<T> deadline_tp(deadline); TimePoint<T> deadline_tp(deadline);
......
...@@ -42,7 +42,12 @@ ...@@ -42,7 +42,12 @@
namespace grpc { namespace grpc {
// If creds does not hold an object or is invalid, a lame channel is returned. /// Create a new \a Channel pointing to \a target
///
/// \param target The URI of the endpoint to connect to.
/// \param creds Credentials to use for the created channel. If it does not hold
/// an object or is invalid, a lame channel is returned.
/// \param args Options for channel creation.
std::shared_ptr<Channel> CreateChannel( std::shared_ptr<Channel> CreateChannel(
const grpc::string& target, const std::shared_ptr<Credentials>& creds, const grpc::string& target, const std::shared_ptr<Credentials>& creds,
const ChannelArguments& args); const ChannelArguments& args);
......
...@@ -46,9 +46,9 @@ namespace testing { ...@@ -46,9 +46,9 @@ namespace testing {
class ChannelArgumentsTest; class ChannelArgumentsTest;
} // namespace testing } // namespace testing
// Options for channel creation. The user can use generic setters to pass /// Options for channel creation. The user can use generic setters to pass
// key value pairs down to c channel creation code. For grpc related options, /// key value pairs down to c channel creation code. For grpc related options,
// concrete setters are provided. /// concrete setters are provided.
class ChannelArguments { class ChannelArguments {
public: public:
ChannelArguments() {} ChannelArguments() {}
...@@ -62,21 +62,26 @@ class ChannelArguments { ...@@ -62,21 +62,26 @@ class ChannelArguments {
void Swap(ChannelArguments& other); void Swap(ChannelArguments& other);
// grpc specific channel argument setters /// Populates this instance with the arguments from \a channel_args. Does not
// Set target name override for SSL host name checking. /// take ownership of \a channel_args.
///
/// Note that the underlying arguments are shared. Changes made to either \a
/// channel_args or this instance would be reflected on both.
void SetChannelArgs(grpc_channel_args* channel_args) const;
// gRPC specific channel argument setters
/// Set target name override for SSL host name checking.
void SetSslTargetNameOverride(const grpc::string& name); void SetSslTargetNameOverride(const grpc::string& name);
// TODO(yangg) add flow control options // TODO(yangg) add flow control options
/// Set the compression algorithm for the channel.
// Set the compression algorithm for the channel.
void SetCompressionAlgorithm(grpc_compression_algorithm algorithm); void SetCompressionAlgorithm(grpc_compression_algorithm algorithm);
// Generic channel argument setters. Only for advanced use cases. // Generic channel argument setters. Only for advanced use cases.
/// Set an integer argument \a value under \a key.
void SetInt(const grpc::string& key, int value); void SetInt(const grpc::string& key, int value);
/// Set a textual argument \a value under \a key.
void SetString(const grpc::string& key, const grpc::string& value); void SetString(const grpc::string& key, const grpc::string& value);
// Populates given channel_args with args_, does not take ownership.
void SetChannelArgs(grpc_channel_args* channel_args) const;
private: private:
friend class SecureCredentials; friend class SecureCredentials;
friend class testing::ChannelArgumentsTest; friend class testing::ChannelArgumentsTest;
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment