grpc 1.42.0 → 1.45.0

data/include/grpc/event_engine/event_engine.h

@@ -97,6 +97,12 @@ class EventEngine {
   struct TaskHandle {
     intptr_t keys[2];
   };
+  /// A handle to a cancellable connection attempt.
+  ///
+  /// Returned by \a Connect, and can be passed to \a CancelConnect.
+  struct ConnectionHandle {
+    intptr_t keys[2];
+  };
   /// Thin wrapper around a platform-specific sockaddr type. A sockaddr struct
   /// exists on all platforms that gRPC supports.
   ///
@@ -224,23 +230,30 @@ class EventEngine {
       std::unique_ptr<MemoryAllocatorFactory> memory_allocator_factory) = 0;
   /// Creates a client network connection to a remote network listener.
   ///
-  /// May return an error status immediately if there was a failure in the
-  /// synchronous part of establishing a connection. In that event, the \a
-  /// on_connect callback *will not* have been executed. Otherwise, it is
-  /// expected that the \a on_connect callback will be asynchronously executed
-  /// exactly once by the EventEngine.
+  /// Even in the event of an error, it is expected that the \a on_connect
+  /// callback will be asynchronously executed exactly once by the EventEngine.
+  /// A connection attempt can be cancelled using the \a CancelConnect method.
   ///
   /// Implementation Note: it is important that the \a memory_allocator be used
   /// for all read/write buffer allocations in the EventEngine implementation.
   /// This allows gRPC's \a ResourceQuota system to monitor and control memory
   /// usage with graceful degradation mechanisms. Please see the \a
   /// MemoryAllocator API for more information.
-  virtual absl::Status Connect(OnConnectCallback on_connect,
-                               const ResolvedAddress& addr,
-                               const EndpointConfig& args,
-                               MemoryAllocator memory_allocator,
-                               absl::Time deadline) = 0;
+  virtual ConnectionHandle Connect(OnConnectCallback on_connect,
+                                   const ResolvedAddress& addr,
+                                   const EndpointConfig& args,
+                                   MemoryAllocator memory_allocator,
+                                   absl::Time deadline) = 0;
 
+  /// Request cancellation of a connection attempt.
+  ///
+  /// If the associated connection has already been completed, it will not be
+  /// cancelled, and this method will return false.
+  ///
+  /// If the associated connection has not been completed, it will be cancelled,
+  /// and this method will return true. The \a OnConnectCallback will not be
+  /// called.
+  virtual bool CancelConnect(ConnectionHandle handle) = 0;
   /// Provides asynchronous resolution.
   class DNSResolver {
    public:
@@ -365,9 +378,20 @@ class EventEngine {
   virtual bool Cancel(TaskHandle handle) = 0;
 };
 
-// TODO(hork): finalize the API and document it. We need to firm up the story
-// around user-provided EventEngines.
-std::shared_ptr<EventEngine> DefaultEventEngineFactory();
+/// Replace gRPC's default EventEngine factory.
+///
+/// Applications may call \a SetDefaultEventEngineFactory at any time to replace
+/// the default factory used within gRPC. EventEngines will be created when
+/// necessary, when they are otherwise not provided by the application.
+///
+/// To be certain that none of the gRPC-provided built-in EventEngines are
+/// created, applications must set a custom EventEngine factory method *before*
+/// grpc is initialized.
+void SetDefaultEventEngineFactory(
+    const std::function<std::unique_ptr<EventEngine>()>* factory);
+
+/// Create an EventEngine using the default factory.
+std::unique_ptr<EventEngine> CreateEventEngine();
 
 }  // namespace experimental
 }  // namespace grpc_event_engine

data/include/grpc/event_engine/internal/memory_allocator_impl.h

@@ -21,42 +21,12 @@
 #include <type_traits>
 #include <vector>
 
+#include <grpc/event_engine/memory_request.h>
 #include <grpc/slice.h>
 
-// forward-declaring an internal struct, not used publicly.
-struct grpc_slice_buffer;
-
 namespace grpc_event_engine {
 namespace experimental {
 
-/// Reservation request - how much memory do we want to allocate?
-class MemoryRequest {
- public:
-  /// Request a fixed amount of memory.
-  // NOLINTNEXTLINE(google-explicit-constructor)
-  MemoryRequest(size_t n) : min_(n), max_(n) {}
-  /// Request a range of memory.
-  /// Requires: \a min <= \a max.
-  /// Requires: \a max <= max_size()
-  MemoryRequest(size_t min, size_t max) : min_(min), max_(max) {}
-
-  /// Maximum allowable request size - hard coded to 1GB.
-  static constexpr size_t max_allowed_size() { return 1024 * 1024 * 1024; }
-
-  /// Increase the size by \a amount.
-  /// Undefined behavior if min() + amount or max() + amount overflows.
-  MemoryRequest Increase(size_t amount) const {
-    return MemoryRequest(min_ + amount, max_ + amount);
-  }
-
-  size_t min() const { return min_; }
-  size_t max() const { return max_; }
-
- private:
-  size_t min_;
-  size_t max_;
-};
-
 namespace internal {
 
 /// Underlying memory allocation interface.

data/include/grpc/event_engine/memory_allocator.h

@@ -16,6 +16,8 @@
 
 #include <grpc/impl/codegen/port_platform.h>
 
+#include <stdlib.h>  // for abort()
+
 #include <algorithm>
 #include <memory>
 #include <type_traits>
@@ -42,6 +44,9 @@ class SliceBuffer {
   grpc_slice_buffer* slice_buffer_;
 };
 
+// Tracks memory allocated by one system.
+// Is effectively a thin wrapper/smart pointer for a MemoryAllocatorImpl,
+// providing a convenient and stable API.
 class MemoryAllocator {
  public:
   /// Construct a MemoryAllocator given an internal::MemoryAllocatorImpl
@@ -50,6 +55,8 @@ class MemoryAllocator {
   explicit MemoryAllocator(
       std::shared_ptr<internal::MemoryAllocatorImpl> allocator)
       : allocator_(std::move(allocator)) {}
+  // Construct an invalid MemoryAllocator.
+  MemoryAllocator() : allocator_(nullptr) {}
   ~MemoryAllocator() {
     if (allocator_ != nullptr) allocator_->Shutdown();
   }
@@ -60,6 +67,14 @@ class MemoryAllocator {
   MemoryAllocator(MemoryAllocator&&) = default;
   MemoryAllocator& operator=(MemoryAllocator&&) = default;
 
+  /// Drop the underlying allocator and make this an empty object.
+  /// The object will not be usable after this call unless it's a valid
+  /// allocator is moved into it.
+  void Reset() {
+    if (allocator_ != nullptr) allocator_->Shutdown();
+    allocator_.reset();
+  }
+
   /// Reserve bytes from the quota.
   /// If we enter overcommit, reclamation will begin concurrently.
   /// Returns the number of bytes reserved.
@@ -68,13 +83,6 @@ class MemoryAllocator {
   /// Release some bytes that were previously reserved.
   void Release(size_t n) { return allocator_->Release(n); }
 
-  /// Return a pointer to the underlying implementation.
-  /// Note that the interface of said implementatoin is unstable and likely to
-  /// change at any time.
-  internal::MemoryAllocatorImpl* get_internal_impl_ptr() {
-    return allocator_.get();
-  }
-
   //
   // The remainder of this type are helper functions implemented in terms of
   // Reserve/Release.
@@ -175,8 +183,15 @@ class MemoryAllocator {
   };
 
  protected:
-  const std::shared_ptr<internal::MemoryAllocatorImpl>& allocator() {
-    return allocator_;
+  /// Return a pointer to the underlying implementation.
+  /// Note that the interface of said implementation is unstable and likely to
+  /// change at any time.
+  internal::MemoryAllocatorImpl* get_internal_impl_ptr() {
+    return allocator_.get();
+  }
+
+  const internal::MemoryAllocatorImpl* get_internal_impl_ptr() const {
+    return allocator_.get();
   }
 
  private:
@@ -198,10 +213,11 @@ class MemoryAllocatorFactory {
   virtual ~MemoryAllocatorFactory() = default;
   /// On Endpoint creation, call \a CreateMemoryAllocator to create a new
   /// allocator for the endpoint.
+  /// \a name is used to label the memory allocator in debug logs.
   /// Typically we'll want to:
-  ///    auto allocator = factory->CreateMemoryAllocator();
+  ///    auto allocator = factory->CreateMemoryAllocator(peer_address_string);
   ///    auto* endpoint = allocator->New<MyEndpoint>(std::move(allocator), ...);
-  virtual MemoryAllocator CreateMemoryAllocator() = 0;
+  virtual MemoryAllocator CreateMemoryAllocator(absl::string_view name) = 0;
 };
 
 }  // namespace experimental

data/include/grpc/event_engine/memory_request.h

@@ -0,0 +1,57 @@
+// Copyright 2021 The 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_EVENT_ENGINE_MEMORY_REQUEST_H
+#define GRPC_EVENT_ENGINE_MEMORY_REQUEST_H
+
+#include <grpc/support/port_platform.h>
+
+#include <stddef.h>
+
+#include "absl/strings/string_view.h"
+
+namespace grpc_event_engine {
+namespace experimental {
+
+/// Reservation request - how much memory do we want to allocate?
+class MemoryRequest {
+ public:
+  /// Request a fixed amount of memory.
+  // NOLINTNEXTLINE(google-explicit-constructor)
+  MemoryRequest(size_t n) : min_(n), max_(n) {}
+  /// Request a range of memory.
+  /// Requires: \a min <= \a max.
+  /// Requires: \a max <= max_size()
+  MemoryRequest(size_t min, size_t max) : min_(min), max_(max) {}
+
+  /// Maximum allowable request size - hard coded to 1GB.
+  static constexpr size_t max_allowed_size() { return 1024 * 1024 * 1024; }
+
+  /// Increase the size by \a amount.
+  /// Undefined behavior if min() + amount or max() + amount overflows.
+  MemoryRequest Increase(size_t amount) const {
+    return MemoryRequest(min_ + amount, max_ + amount);
+  }
+
+  size_t min() const { return min_; }
+  size_t max() const { return max_; }
+
+ private:
+  size_t min_;
+  size_t max_;
+};
+
+}  // namespace experimental
+}  // namespace grpc_event_engine
+
+#endif  // GRPC_EVENT_ENGINE_MEMORY_REQUEST_H

data/include/grpc/grpc.h

@@ -295,15 +295,41 @@ GRPCAPI void grpc_channel_get_info(grpc_channel* channel,
     to non-experimental or remove it. */
 GRPCAPI void grpc_channel_reset_connect_backoff(grpc_channel* channel);
 
-/** Create a client channel to 'target'. Additional channel level configuration
-    MAY be provided by grpc_channel_args, though the expectation is that most
-    clients will want to simply pass NULL. The user data in 'args' need only
-    live through the invocation of this function. However, if any args of the
-    'pointer' type are passed, then the referenced vtable must be maintained
-    by the caller until grpc_channel_destroy terminates. See grpc_channel_args
-    definition for more on this. */
-GRPCAPI grpc_channel* grpc_insecure_channel_create(
-    const char* target, const grpc_channel_args* args, void* reserved);
+/** --- grpc_channel_credentials object. ---
+
+   A channel credentials object represents a way to authenticate a client on a
+   channel. Different types of channel credentials are declared in
+   grpc_security.h. */
+
+typedef struct grpc_channel_credentials grpc_channel_credentials;
+
+/** 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);
+
+/** --- grpc_server_credentials object. ---
+
+   A server credentials object represents a way to authenticate a server.
+   Different types of server credentials are declared in grpc_security.h. */
+
+typedef struct grpc_server_credentials grpc_server_credentials;
+
+/** 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);
+
+/** Creates a secure channel using the passed-in credentials. Additional
+    channel level configuration MAY be provided by grpc_channel_args, though
+    the expectation is that most clients will want to simply pass NULL. The
+    user data in 'args' need only live through the invocation of this function.
+    However, if any args of the 'pointer' type are passed, then the referenced
+    vtable must be maintained by the caller until grpc_channel_destroy
+    terminates. See grpc_channel_args definition for more on this. */
+GRPCAPI grpc_channel* grpc_channel_create(const char* target,
+                                          grpc_channel_credentials* creds,
+                                          const grpc_channel_args* args);
 
 /** Create a lame client: this client fails every operation attempted on it. */
 GRPCAPI grpc_channel* grpc_lame_client_channel_create(
@@ -444,11 +470,11 @@ GRPCAPI void grpc_server_config_fetcher_destroy(
 GRPCAPI void grpc_server_set_config_fetcher(
     grpc_server* server, grpc_server_config_fetcher* config_fetcher);
 
-/** Add a HTTP2 over plaintext over tcp listener.
-    Returns bound port number on success, 0 on failure.
-    REQUIRES: server not started */
-GRPCAPI int grpc_server_add_insecure_http2_port(grpc_server* server,
-                                                const char* addr);
+/** 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_http2_port(grpc_server* server, const char* addr,
+                                       grpc_server_credentials* creds);
 
 /** Start a server - tells all listeners to start listening */
 GRPCAPI void grpc_server_start(grpc_server* server);

data/include/grpc/grpc_posix.h

@@ -23,6 +23,7 @@
 
 #include <stddef.h>
 
+#include <grpc/grpc.h>
 #include <grpc/impl/codegen/grpc_types.h>
 
 #ifdef __cplusplus
@@ -35,25 +36,25 @@ extern "C" {
  * functionality on top of GRPC Core.
  */
 
-/** Create a client channel to 'target' using file descriptor 'fd'. The 'target'
-    argument will be used to indicate the name for this channel. See the comment
-    for grpc_insecure_channel_create for description of 'args' argument. */
-GRPCAPI grpc_channel* grpc_insecure_channel_create_from_fd(
-    const char* target, int fd, const grpc_channel_args* args);
-
-/** Add the connected communication channel based on file descriptor 'fd' to the
-    'server'. The 'fd' must be an open file descriptor corresponding to a
-    connected socket. Events from the file descriptor may come on any of the
-    server completion queues (i.e completion queues registered via the
-    grpc_server_register_completion_queue API).
-
-    The 'reserved' pointer MUST be NULL.
-
-    TODO(hork): add channel_args to this API to allow endpoints and transports
-    created in this function to participate in the resource quota feature.
-    */
-GRPCAPI void grpc_server_add_insecure_channel_from_fd(grpc_server* server,
-                                                      void* reserved, int fd);
+/** Create a secure channel to 'target' using file descriptor 'fd' and passed-in
+    credentials. The 'target' argument will be used to indicate the name for
+    this channel. Note that this API currently only supports insecure channel
+    credentials. Using other types of credentials will result in a failure. */
+GRPCAPI grpc_channel* grpc_channel_create_from_fd(
+    const char* target, int fd, grpc_channel_credentials* creds,
+    const grpc_channel_args* args);
+
+/** Add the connected secure communication channel based on file descriptor 'fd'
+   to the 'server' and server credentials 'creds'. The 'fd' must be an open file
+   descriptor corresponding to a connected socket. Events from the file
+   descriptor may come on any of the server completion queues (i.e completion
+   queues registered via the grpc_server_register_completion_queue API).
+   Note that this API currently only supports inseure server credentials
+   Using other types of credentials will result in a failure.
+   TODO(hork): add channel_args to this API to allow endpoints and transports
+   created in this function to participate in the resource quota feature. */
+GRPCAPI void grpc_server_add_channel_from_fd(grpc_server* server, int fd,
+                                             grpc_server_credentials* creds);
 
 #ifdef __cplusplus
 }