grpc 1.42.0 → 1.49.1

data/include/grpc/compression.h

@@ -23,7 +23,7 @@
 
 #include <stdlib.h>
 
-#include <grpc/impl/codegen/compression_types.h>
+#include <grpc/impl/codegen/compression_types.h>  // IWYU pragma: export
 #include <grpc/slice.h>
 
 #ifdef __cplusplus

data/include/grpc/event_engine/event_engine.h

@@ -19,15 +19,16 @@
 #include <functional>
 #include <vector>
 
+#include "absl/functional/any_invocable.h"
 #include "absl/status/status.h"
 #include "absl/status/statusor.h"
-#include "absl/time/time.h"
 
 #include <grpc/event_engine/endpoint_config.h>
 #include <grpc/event_engine/memory_allocator.h>
 #include <grpc/event_engine/port.h>
+#include <grpc/event_engine/slice_buffer.h>
 
-// TODO(hork): Define the Endpoint::Write metrics collection system
+// TODO(vigneshbabu): Define the Endpoint::Write metrics collection system
 namespace grpc_event_engine {
 namespace experimental {
 
@@ -73,6 +74,11 @@ namespace experimental {
 ////////////////////////////////////////////////////////////////////////////////
 class EventEngine {
  public:
+  /// A duration between two events.
+  ///
+  /// Throughout the EventEngine API durations are used to express how long
+  /// until an action should be performed.
+  using Duration = std::chrono::duration<int64_t, std::nano>;
   /// A custom closure type for EventEngine task execution.
   ///
   /// Throughout the EventEngine API, \a Closure ownership is retained by the
@@ -97,6 +103,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.
   ///
@@ -132,6 +144,18 @@ class EventEngine {
     /// Shuts down all connections and invokes all pending read or write
     /// callbacks with an error status.
     virtual ~Endpoint() = default;
+    /// A struct representing optional arguments that may be provided to an
+    /// EventEngine Endpoint Read API  call.
+    ///
+    /// Passed as argument to an Endpoint \a Read
+    struct ReadArgs {
+      // A suggestion to the endpoint implementation to read at-least the
+      // specified number of bytes over the network connection before marking
+      // the endpoint read operation as complete. gRPC may use this argument
+      // to minimize the number of endpoint read API calls over the lifetime
+      // of a connection.
+      int64_t read_hint_bytes;
+    };
     /// Reads data from the Endpoint.
     ///
     /// When data is available on the connection, that data is moved into the
@@ -149,8 +173,22 @@ class EventEngine {
     /// For failed read operations, implementations should pass the appropriate
     /// statuses to \a on_read. For example, callbacks might expect to receive
     /// CANCELLED on endpoint shutdown.
-    virtual void Read(std::function<void(absl::Status)> on_read,
-                      SliceBuffer* buffer) = 0;
+    virtual void Read(absl::AnyInvocable<void(absl::Status)> on_read,
+                      SliceBuffer* buffer, const ReadArgs* args) = 0;
+    /// A struct representing optional arguments that may be provided to an
+    /// EventEngine Endpoint Write API call.
+    ///
+    /// Passed as argument to an Endpoint \a Write
+    struct WriteArgs {
+      // Represents private information that may be passed by gRPC for
+      // select endpoints expected to be used only within google.
+      void* google_specific = nullptr;
+      // A suggestion to the endpoint implementation to group data to be written
+      // into frames of the specified max_frame_size. gRPC may use this
+      // argument to dynamically control the max sizes of frames sent to a
+      // receiver in response to high receiver memory pressure.
+      int64_t max_frame_size;
+    };
     /// Writes data out on the connection.
     ///
     /// \a on_writable is called when the connection is ready for more data. The
@@ -169,8 +207,8 @@ class EventEngine {
     /// For failed write operations, implementations should pass the appropriate
     /// statuses to \a on_writable. For example, callbacks might expect to
     /// receive CANCELLED on endpoint shutdown.
-    virtual void Write(std::function<void(absl::Status)> on_writable,
-                       SliceBuffer* data) = 0;
+    virtual void Write(absl::AnyInvocable<void(absl::Status)> on_writable,
+                       SliceBuffer* data, const WriteArgs* args) = 0;
     /// Returns an address in the format described in DNSResolver. The returned
     /// values are expected to remain valid for the life of the Endpoint.
     virtual const ResolvedAddress& GetPeerAddress() const = 0;
@@ -184,14 +222,14 @@ class EventEngine {
   /// expect to receive DEADLINE_EXCEEDED statuses when appropriate, or
   /// CANCELLED statuses on EventEngine shutdown.
   using OnConnectCallback =
-      std::function<void(absl::StatusOr<std::unique_ptr<Endpoint>>)>;
+      absl::AnyInvocable<void(absl::StatusOr<std::unique_ptr<Endpoint>>)>;
 
   /// Listens for incoming connection requests from gRPC clients and initiates
   /// request processing once connections are established.
   class Listener {
    public:
     /// Called when the listener has accepted a new client connection.
-    using AcceptCallback = std::function<void(
+    using AcceptCallback = absl::AnyInvocable<void(
         std::unique_ptr<Endpoint>, MemoryAllocator memory_allocator)>;
     virtual ~Listener() = default;
     /// Bind an address/port to this Listener.
@@ -219,34 +257,47 @@ class EventEngine {
   /// MemoryAllocators for Endpoint construction.
   virtual absl::StatusOr<std::unique_ptr<Listener>> CreateListener(
       Listener::AcceptCallback on_accept,
-      std::function<void(absl::Status)> on_shutdown,
+      absl::AnyInvocable<void(absl::Status)> on_shutdown,
       const EndpointConfig& config,
       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,
+                                   Duration timeout) = 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:
     /// Task handle for DNS Resolution requests.
     struct LookupTaskHandle {
-      intptr_t key[2];
+      intptr_t keys[2];
+    };
+    /// Optional configuration for DNSResolvers.
+    struct ResolverOptions {
+      /// If empty, default DNS servers will be used.
+      /// Must be in the "IP:port" format as described in naming.md.
+      std::string dns_server;
     };
     /// DNS SRV record type.
     struct SRVRecord {
@@ -258,12 +309,13 @@ class EventEngine {
     /// Called with the collection of sockaddrs that were resolved from a given
     /// target address.
     using LookupHostnameCallback =
-        std::function<void(absl::StatusOr<std::vector<ResolvedAddress>>)>;
+        absl::AnyInvocable<void(absl::StatusOr<std::vector<ResolvedAddress>>)>;
     /// Called with a collection of SRV records.
     using LookupSRVCallback =
-        std::function<void(absl::StatusOr<std::vector<SRVRecord>>)>;
+        absl::AnyInvocable<void(absl::StatusOr<std::vector<SRVRecord>>)>;
     /// Called with the result of a TXT record lookup
-    using LookupTXTCallback = std::function<void(absl::StatusOr<std::string>)>;
+    using LookupTXTCallback =
+        absl::AnyInvocable<void(absl::StatusOr<std::string>)>;
 
     virtual ~DNSResolver() = default;
 
@@ -280,23 +332,23 @@ class EventEngine {
     ///
     /// If cancelled, \a on_resolve will not be executed.
     virtual LookupTaskHandle LookupHostname(LookupHostnameCallback on_resolve,
-                                            absl::string_view address,
+                                            absl::string_view name,
                                             absl::string_view default_port,
-                                            absl::Time deadline) = 0;
+                                            Duration timeout) = 0;
     /// Asynchronously perform an SRV record lookup.
     ///
     /// \a on_resolve has the same meaning and expectations as \a
     /// LookupHostname's \a on_resolve callback.
     virtual LookupTaskHandle LookupSRV(LookupSRVCallback on_resolve,
                                        absl::string_view name,
-                                       absl::Time deadline) = 0;
+                                       Duration timeout) = 0;
     /// Asynchronously perform a TXT record lookup.
     ///
     /// \a on_resolve has the same meaning and expectations as \a
     /// LookupHostname's \a on_resolve callback.
     virtual LookupTaskHandle LookupTXT(LookupTXTCallback on_resolve,
                                        absl::string_view name,
-                                       absl::Time deadline) = 0;
+                                       Duration timeout) = 0;
     /// Cancel an asynchronous lookup operation.
     ///
     /// This shares the same semantics with \a EventEngine::Cancel: successfully
@@ -318,8 +370,10 @@ class EventEngine {
   // de-experimentalize this API.
   virtual bool IsWorkerThread() = 0;
 
-  /// Creates and returns an instance of a DNSResolver.
-  virtual std::unique_ptr<DNSResolver> GetDNSResolver() = 0;
+  /// Creates and returns an instance of a DNSResolver, optionally configured by
+  /// the \a options struct.
+  virtual std::unique_ptr<DNSResolver> GetDNSResolver(
+      const DNSResolver::ResolverOptions& options) = 0;
 
   /// Asynchronously executes a task as soon as possible.
   ///
@@ -329,45 +383,62 @@ class EventEngine {
   /// Asynchronously executes a task as soon as possible.
   ///
   /// \a Closures scheduled with \a Run cannot be cancelled. Unlike the
-  /// overloaded \a Closure alternative, the std::function version's \a closure
-  /// will be deleted by the EventEngine after the closure has been run.
+  /// overloaded \a Closure alternative, the absl::AnyInvocable version's \a
+  /// closure will be deleted by the EventEngine after the closure has been run.
   ///
   /// This version of \a Run may be less performant than the \a Closure version
   /// in some scenarios. This overload is useful in situations where performance
   /// is not a critical concern.
-  virtual void Run(std::function<void()> closure) = 0;
-  /// Synonymous with scheduling an alarm to run at time \a when.
+  virtual void Run(absl::AnyInvocable<void()> closure) = 0;
+  /// Synonymous with scheduling an alarm to run after duration \a when.
   ///
   /// The \a closure will execute when time \a when arrives unless it has been
   /// cancelled via the \a Cancel method. If cancelled, the closure will not be
   /// run, nor will it be deleted. Ownership remains with the caller.
-  virtual TaskHandle RunAt(absl::Time when, Closure* closure) = 0;
-  /// Synonymous with scheduling an alarm to run at time \a when.
+  virtual TaskHandle RunAfter(Duration when, Closure* closure) = 0;
+  /// Synonymous with scheduling an alarm to run after duration \a when.
   ///
   /// The \a closure will execute when time \a when arrives unless it has been
   /// cancelled via the \a Cancel method. If cancelled, the closure will not be
-  /// run. Unilke the overloaded \a Closure alternative, the std::function
+  /// run. Unilke the overloaded \a Closure alternative, the absl::AnyInvocable
   /// version's \a closure will be deleted by the EventEngine after the closure
   /// has been run, or upon cancellation.
   ///
-  /// This version of \a RunAt may be less performant than the \a Closure
+  /// This version of \a RunAfter may be less performant than the \a Closure
   /// version in some scenarios. This overload is useful in situations where
   /// performance is not a critical concern.
-  virtual TaskHandle RunAt(absl::Time when, std::function<void()> closure) = 0;
+  virtual TaskHandle RunAfter(Duration when,
+                              absl::AnyInvocable<void()> closure) = 0;
   /// Request cancellation of a task.
   ///
   /// If the associated closure has already been scheduled to run, it will not
   /// be cancelled, and this function will return false.
   ///
   /// If the associated callback has not been scheduled to run, it will be
-  /// cancelled, and the associated std::function or \a Closure* will not be
-  /// executed. In this case, Cancel will return true.
+  /// cancelled, and the associated absl::AnyInvocable or \a Closure* will not
+  /// be executed. In this case, Cancel will return true.
+  ///
+  /// Implementation note: closures should be destroyed in a timely manner after
+  /// execution or cancelliation (milliseconds), since any state bound to the
+  /// closure may need to be destroyed for things to progress (e.g., if a
+  /// closure holds a ref to some ref-counted object).
   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(
+    absl::AnyInvocable<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>
@@ -24,24 +26,12 @@
 #include <grpc/event_engine/internal/memory_allocator_impl.h>
 #include <grpc/slice.h>
 
-// forward-declaring an internal struct, not used publicly.
-struct grpc_slice_buffer;
-
 namespace grpc_event_engine {
 namespace experimental {
 
-// TODO(nnoble): needs implementation
-class SliceBuffer {
- public:
-  SliceBuffer() { abort(); }
-  explicit SliceBuffer(grpc_slice_buffer*) { abort(); }
-
-  grpc_slice_buffer* RawSliceBuffer() { return slice_buffer_; }
-
- private:
-  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 +40,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 +52,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 +68,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 +168,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 +198,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/event_engine/port.h

@@ -20,7 +20,7 @@
 #if defined(GPR_ANDROID) || defined(GPR_LINUX) || defined(GPR_APPLE) ||     \
     defined(GPR_FREEBSD) || defined(GPR_OPENBSD) || defined(GPR_SOLARIS) || \
     defined(GPR_AIX) || defined(GPR_NACL) || defined(GPR_FUCHSIA) ||        \
-    defined(GRPC_POSIX_SOCKET)
+    defined(GRPC_POSIX_SOCKET) || defined(GPR_NETBSD)
 #define GRPC_EVENT_ENGINE_POSIX
 #include <arpa/inet.h>
 #include <netdb.h>