Chiebot-Mirror
/
grpc
8
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #13529 from ctiller/api-cleanup

Browse Source 
ServerBuilder interface cleanup
pull/13374/merge
Craig Tiller 7 years ago committed by GitHub
parent 8a2a831b4e e8c47036fb
commit bf51c97fd6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 83 additions and 63 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 146
      include/grpc++/server_builder.h

146
include/grpc++/server_builder.h
Unescape View File

@ -55,13 +55,18 @@ class ServerBuilder {
ServerBuilder();
~ServerBuilder();
/// Options for synchronous servers.
enum SyncServerOption {
NUM_CQS, ///< Number of completion queues.
MIN_POLLERS, ///< Minimum number of polling threads.
MAX_POLLERS, ///< Maximum number of polling threads.
CQ_TIMEOUT_MSEC ///< Completion queue timeout in milliseconds.
};
//////////////////////////////////////////////////////////////////////////////
// Primary API's
/// Return a running server which is ready for processing calls.
/// Before calling, one typically needs to ensure that:
/// 1. a service is registered - so that the server knows what to serve
/// (via RegisterService, or RegisterAsyncGenericService)
/// 2. a listening port has been added - so the server knows where to receive
/// traffic (via AddListeningPort)
/// 3. [for async api only] completion queues have been added via
/// AddCompletionQueue
std::unique_ptr<Server> BuildAndStart();
/// Register a service. This call does not take ownership of the service.
/// The service must exist for the lifetime of the \a Server instance returned
@ -69,9 +74,60 @@ class ServerBuilder {
/// Matches requests with any :authority
ServerBuilder& RegisterService(Service* service);
/// Register a generic service.
/// Matches requests with any :authority
ServerBuilder& RegisterAsyncGenericService(AsyncGenericService* service);
/// Enlists an endpoint \a addr (port with an optional IP address) to
/// bind the \a grpc::Server object to be created to.
///
/// It can be invoked multiple times.
///
/// \param addr_uri The address to try to bind to the server in URI form. If
/// the scheme name is omitted, "dns:///" is assumed. To bind to any address,
/// please use IPv6 any, i.e., [::]:<port>, which also accepts IPv4
/// connections. Valid values include dns:///localhost:1234, /
/// 192.168.1.1:31416, dns:///[::1]:27182, etc.).
/// \param creds The credentials associated with the server.
/// \param selected_port[out] If not `nullptr`, gets populated with the port
/// number bound to the \a grpc::Server for the corresponding endpoint after
/// it is successfully bound, 0 otherwise.
///
ServerBuilder& AddListeningPort(const grpc::string& addr_uri,
std::shared_ptr<ServerCredentials> creds,
int* selected_port = nullptr);
/// Add a completion queue for handling asynchronous services.
///
/// Best performance is typically obtained by using one thread per polling
/// completion queue.
///
/// Caller is required to shutdown the server prior to shutting down the
/// returned completion queue. Caller is also required to drain the
/// completion queue after shutting it down. A typical usage scenario:
///
/// // While building the server:
/// ServerBuilder builder;
/// ...
/// cq_ = builder.AddCompletionQueue();
/// server_ = builder.BuildAndStart();
///
/// // While shutting down the server;
/// server_->Shutdown();
/// cq_->Shutdown(); // Always *after* the associated server's Shutdown()!
/// // Drain the cq_ that was created
/// void* ignored_tag;
/// bool ignored_ok;
/// while (cq_->Next(&ignored_tag, &ignored_ok)) { }
///
/// \param is_frequently_polled This is an optional parameter to inform gRPC
/// library about whether this completion queue would be frequently polled
/// (i.e. by calling \a Next() or \a AsyncNext()). The default value is
/// 'true' and is the recommended setting. Setting this to 'false' (i.e.
/// not polling the completion queue frequently) will have a significantly
/// negative performance impact and hence should not be used in production
/// use cases.
std::unique_ptr<ServerCompletionQueue> AddCompletionQueue(
bool is_frequently_polled = true);
//////////////////////////////////////////////////////////////////////////////
// Less commonly used RegisterService variants
/// Register a service. This call does not take ownership of the service.
/// The service must exist for the lifetime of the \a Server instance returned
@ -79,6 +135,15 @@ class ServerBuilder {
/// Only matches requests with :authority \a host
ServerBuilder& RegisterService(const grpc::string& host, Service* service);
/// Register a generic service.
/// Matches requests with any :authority
/// This is mostly useful for writing generic gRPC Proxies where the exact
/// serialization format is unknown
ServerBuilder& RegisterAsyncGenericService(AsyncGenericService* service);
//////////////////////////////////////////////////////////////////////////////
// Fine control knobs
/// Set max receive message size in bytes.
ServerBuilder& SetMaxReceiveMessageSize(int max_receive_message_size) {
max_receive_message_size_ = max_receive_message_size;
@ -119,6 +184,14 @@ class ServerBuilder {
ServerBuilder& SetOption(std::unique_ptr<ServerBuilderOption> option);
/// Options for synchronous servers.
enum SyncServerOption {
NUM_CQS, ///< Number of completion queues.
MIN_POLLERS, ///< Minimum number of polling threads.
MAX_POLLERS, ///< Maximum number of polling threads.
CQ_TIMEOUT_MSEC ///< Completion queue timeout in milliseconds.
};
/// Only useful if this is a Synchronous server.
ServerBuilder& SetSyncServerOption(SyncServerOption option, int value);
@ -129,59 +202,6 @@ class ServerBuilder {
return SetOption(MakeChannelArgumentOption(arg, value));
}
/// Enlists an endpoint \a addr (port with an optional IP address) to
/// bind the \a grpc::Server object to be created to.
///
/// It can be invoked multiple times.
///
/// \param addr_uri The address to try to bind to the server in URI form. If
/// the scheme name is omitted, "dns:///" is assumed. To bind to any address,
/// please use IPv6 any, i.e., [::]:<port>, which also accepts IPv4
/// connections. Valid values include dns:///localhost:1234, /
/// 192.168.1.1:31416, dns:///[::1]:27182, etc.).
/// \param creds The credentials associated with the server.
/// \param selected_port[out] If not `nullptr`, gets populated with the port
/// number bound to the \a grpc::Server for the corresponding endpoint after
/// it is successfully bound, 0 otherwise.
///
// TODO(dgq): the "port" part seems to be a misnomer.
ServerBuilder& AddListeningPort(const grpc::string& addr_uri,
std::shared_ptr<ServerCredentials> creds,
int* selected_port = nullptr);
/// Add a completion queue for handling asynchronous services.
///
/// Caller is required to shutdown the server prior to shutting down the
/// returned completion queue. Caller is also required to drain the
/// completion queue after shutting it down. A typical usage scenario:
///
/// // While building the server:
/// ServerBuilder builder;
/// ...
/// cq_ = builder.AddCompletionQueue();
/// server_ = builder.BuildAndStart();
///
/// // While shutting down the server;
/// server_->Shutdown();
/// cq_->Shutdown(); // Always *after* the associated server's Shutdown()!
/// // Drain the cq_ that was created
/// void* ignored_tag;
/// bool ignored_ok;
/// while (cq_->Next(&ignored_tag, &ignored_ok)) { }
///
/// \param is_frequently_polled This is an optional parameter to inform gRPC
/// library about whether this completion queue would be frequently polled
/// (i.e. by calling \a Next() or \a AsyncNext()). The default value is
/// 'true' and is the recommended setting. Setting this to 'false' (i.e.
/// not polling the completion queue frequently) will have a significantly
/// negative performance impact and hence should not be used in production
/// use cases.
std::unique_ptr<ServerCompletionQueue> AddCompletionQueue(
bool is_frequently_polled = true);
/// Return a running server which is ready for processing calls.
std::unique_ptr<Server> BuildAndStart();
/// For internal use only: Register a ServerBuilderPlugin factory function.
static void InternalAddPluginFactory(
std::unique_ptr<ServerBuilderPlugin> (*CreatePlugin)());

Write Preview
Loading…
Cancel
Save