diff options
author | Mark D. Roth <roth@google.com> | 2017-12-01 08:56:25 -0800 |
---|---|---|
committer | Mark D. Roth <roth@google.com> | 2017-12-01 08:56:25 -0800 |
commit | e109ddf89f966b1f99290ec15a14ec3859049099 (patch) | |
tree | d9505ff4cc7e19c87a740cc7d379c47810b19417 /include | |
parent | c5d0df9e44068b82a9980e4f700ffebfbabc9ed2 (diff) | |
parent | 44c143c587c219ddae4ec3dbce003c0bd6c6c9e6 (diff) |
Merge remote-tracking branch 'upstream/master' into server_connection_timeout
Diffstat (limited to 'include')
-rw-r--r-- | include/grpc++/impl/codegen/core_codegen_interface.h | 4 | ||||
-rw-r--r-- | include/grpc++/server_builder.h | 146 | ||||
-rw-r--r-- | include/grpc/fork.h | 24 | ||||
-rw-r--r-- | include/grpc/impl/codegen/fork.h | 48 | ||||
-rw-r--r-- | include/grpc/impl/codegen/grpc_types.h | 2 | ||||
-rw-r--r-- | include/grpc/module.modulemap | 4 | ||||
-rw-r--r-- | include/grpc/support/histogram.h | 64 |
7 files changed, 159 insertions, 133 deletions
diff --git a/include/grpc++/impl/codegen/core_codegen_interface.h b/include/grpc++/impl/codegen/core_codegen_interface.h index 1949cdab76..d7ad7a4b57 100644 --- a/include/grpc++/impl/codegen/core_codegen_interface.h +++ b/include/grpc++/impl/codegen/core_codegen_interface.h @@ -25,10 +25,6 @@ #include <grpc/impl/codegen/grpc_types.h> #include <grpc/impl/codegen/sync.h> -extern "C" { -struct grpc_byte_buffer; -} - namespace grpc { /// Interface between the codegen library and the minimal subset of core diff --git a/include/grpc++/server_builder.h b/include/grpc++/server_builder.h index 0888bef0d9..e2bae4b41f 100644 --- a/include/grpc++/server_builder.h +++ b/include/grpc++/server_builder.h @@ -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)()); diff --git a/include/grpc/fork.h b/include/grpc/fork.h new file mode 100644 index 0000000000..ca45e1139c --- /dev/null +++ b/include/grpc/fork.h @@ -0,0 +1,24 @@ +/* + * + * Copyright 2017 gRPC authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ + +#ifndef GRPC_FORK_H +#define GRPC_FORK_H + +#include <grpc/impl/codegen/fork.h> + +#endif /* GRPC_FORK_H */ diff --git a/include/grpc/impl/codegen/fork.h b/include/grpc/impl/codegen/fork.h new file mode 100644 index 0000000000..baec7a2f10 --- /dev/null +++ b/include/grpc/impl/codegen/fork.h @@ -0,0 +1,48 @@ +/* + * + * Copyright 2017 gRPC authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ + +#ifndef GRPC_IMPL_CODEGEN_FORK_H +#define GRPC_IMPL_CODEGEN_FORK_H + +/** + * gRPC applications should call this before calling fork(). There should be no + * active gRPC function calls between calling grpc_prefork() and + * grpc_postfork_parent()/grpc_postfork_child(). + * + * + * Typical use: + * grpc_prefork(); + * int pid = fork(); + * if (pid) { + * grpc_postfork_parent(); + * // Parent process.. + * } else { + * grpc_postfork_child(); + * // Child process... + * } + */ + +void grpc_prefork(); + +void grpc_postfork_parent(); + +void grpc_postfork_child(); + +void grpc_fork_handlers_auto_register(); + +#endif /* GRPC_IMPL_CODEGEN_FORK_H */ diff --git a/include/grpc/impl/codegen/grpc_types.h b/include/grpc/impl/codegen/grpc_types.h index 73669d9e84..77844aa2af 100644 --- a/include/grpc/impl/codegen/grpc_types.h +++ b/include/grpc/impl/codegen/grpc_types.h @@ -563,7 +563,7 @@ typedef struct grpc_op { grpc_slice* status_details; /** If this is not nullptr, it will be populated with the full fidelity * error string for debugging purposes. The application is responsible - * for freeing the data. */ + * for freeing the data by using gpr_free(). */ const char** error_string; } recv_status_on_client; struct grpc_op_recv_close_on_server { diff --git a/include/grpc/module.modulemap b/include/grpc/module.modulemap index 342adc0dc9..67136cba8a 100644 --- a/include/grpc/module.modulemap +++ b/include/grpc/module.modulemap @@ -7,7 +7,6 @@ framework module grpc { header "support/avl.h" header "support/cmdline.h" header "support/cpu.h" - header "support/histogram.h" header "support/host_port.h" header "support/log.h" header "support/log_windows.h" @@ -21,6 +20,7 @@ framework module grpc { header "support/tls.h" header "support/useful.h" header "impl/codegen/atm.h" + header "impl/codegen/fork.h" header "impl/codegen/gpr_slice.h" header "impl/codegen/gpr_types.h" header "impl/codegen/port_platform.h" @@ -36,6 +36,7 @@ framework module grpc { header "impl/codegen/slice.h" header "impl/codegen/status.h" header "impl/codegen/atm.h" + header "impl/codegen/fork.h" header "impl/codegen/gpr_slice.h" header "impl/codegen/gpr_types.h" header "impl/codegen/port_platform.h" @@ -45,6 +46,7 @@ framework module grpc { header "byte_buffer.h" header "byte_buffer_reader.h" header "compression.h" + header "fork.h" header "grpc.h" header "grpc_posix.h" header "grpc_security_constants.h" diff --git a/include/grpc/support/histogram.h b/include/grpc/support/histogram.h deleted file mode 100644 index d2794d847e..0000000000 --- a/include/grpc/support/histogram.h +++ /dev/null @@ -1,64 +0,0 @@ -/* - * - * Copyright 2015 gRPC authors. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * - */ - -#ifndef GRPC_SUPPORT_HISTOGRAM_H -#define GRPC_SUPPORT_HISTOGRAM_H - -#include <grpc/support/port_platform.h> -#include <stddef.h> - -#ifdef __cplusplus -extern "C" { -#endif - -typedef struct gpr_histogram gpr_histogram; - -GPRAPI gpr_histogram* gpr_histogram_create(double resolution, - double max_bucket_start); -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 - 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); - -GPRAPI double gpr_histogram_percentile(gpr_histogram* histogram, - double percentile); -GPRAPI double gpr_histogram_mean(gpr_histogram* histogram); -GPRAPI double gpr_histogram_stddev(gpr_histogram* histogram); -GPRAPI double gpr_histogram_variance(gpr_histogram* histogram); -GPRAPI double gpr_histogram_maximum(gpr_histogram* histogram); -GPRAPI double gpr_histogram_minimum(gpr_histogram* histogram); -GPRAPI double gpr_histogram_count(gpr_histogram* histogram); -GPRAPI double gpr_histogram_sum(gpr_histogram* histogram); -GPRAPI double gpr_histogram_sum_of_squares(gpr_histogram* histogram); - -GPRAPI const uint32_t* gpr_histogram_get_contents(gpr_histogram* histogram, - size_t* count); -GPRAPI void gpr_histogram_merge_contents(gpr_histogram* histogram, - const uint32_t* data, - size_t data_count, double min_seen, - double max_seen, double sum, - double sum_of_squares, double count); - -#ifdef __cplusplus -} -#endif - -#endif /* GRPC_SUPPORT_HISTOGRAM_H */ |