Merge branch 'master' into threadnames

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 c8c1437c91..ad668b4f11 100644
--- a/include/grpc/impl/codegen/grpc_types.h
+++ b/include/grpc/impl/codegen/grpc_types.h
@@ -560,7 +560,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 */