grpc 1.40.0 → 1.46.3

data/include/grpc/event_engine/memory_allocator.h

@@ -0,0 +1,226 @@
+// 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_ALLOCATOR_H
+#define GRPC_EVENT_ENGINE_MEMORY_ALLOCATOR_H
+
+#include <grpc/impl/codegen/port_platform.h>
+
+#include <stdlib.h>  // for abort()
+
+#include <algorithm>
+#include <memory>
+#include <type_traits>
+#include <vector>
+
+#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
+  /// implementation. The constructed MemoryAllocator will call
+  /// MemoryAllocatorImpl::Shutdown() upon destruction.
+  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();
+  }
+
+  MemoryAllocator(const MemoryAllocator&) = delete;
+  MemoryAllocator& operator=(const MemoryAllocator&) = delete;
+
+  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.
+  size_t Reserve(MemoryRequest request) { return allocator_->Reserve(request); }
+
+  /// Release some bytes that were previously reserved.
+  void Release(size_t n) { return allocator_->Release(n); }
+
+  //
+  // The remainder of this type are helper functions implemented in terms of
+  // Reserve/Release.
+  //
+
+  /// An automatic releasing reservation of memory.
+  class Reservation {
+   public:
+    Reservation() = default;
+    Reservation(const Reservation&) = delete;
+    Reservation& operator=(const Reservation&) = delete;
+    Reservation(Reservation&&) = default;
+    Reservation& operator=(Reservation&&) = default;
+    ~Reservation() {
+      if (allocator_ != nullptr) allocator_->Release(size_);
+    }
+
+   private:
+    friend class MemoryAllocator;
+    Reservation(std::shared_ptr<internal::MemoryAllocatorImpl> allocator,
+                size_t size)
+        : allocator_(std::move(allocator)), size_(size) {}
+
+    std::shared_ptr<internal::MemoryAllocatorImpl> allocator_;
+    size_t size_ = 0;
+  };
+
+  /// Reserve bytes from the quota and automatically release them when
+  /// Reservation is destroyed.
+  Reservation MakeReservation(MemoryRequest request) {
+    return Reservation(allocator_, Reserve(request));
+  }
+
+  /// Allocate a new object of type T, with constructor arguments.
+  /// The returned type is wrapped, and upon destruction the reserved memory
+  /// will be released to the allocator automatically. As such, T must have a
+  /// virtual destructor so we can insert the necessary hook.
+  template <typename T, typename... Args>
+  typename std::enable_if<std::has_virtual_destructor<T>::value, T*>::type New(
+      Args&&... args) {
+    // Wrap T such that when it's destroyed, we can release memory back to the
+    // allocator.
+    class Wrapper final : public T {
+     public:
+      explicit Wrapper(std::shared_ptr<internal::MemoryAllocatorImpl> allocator,
+                       Args&&... args)
+          : T(std::forward<Args>(args)...), allocator_(std::move(allocator)) {}
+      ~Wrapper() override { allocator_->Release(sizeof(*this)); }
+
+     private:
+      const std::shared_ptr<internal::MemoryAllocatorImpl> allocator_;
+    };
+    Reserve(sizeof(Wrapper));
+    return new Wrapper(allocator_, std::forward<Args>(args)...);
+  }
+
+  /// Construct a unique_ptr immediately.
+  template <typename T, typename... Args>
+  std::unique_ptr<T> MakeUnique(Args&&... args) {
+    return std::unique_ptr<T>(New<T>(std::forward<Args>(args)...));
+  }
+
+  /// Allocate a slice, using MemoryRequest to size the number of returned
+  /// bytes. For a variable length request, check the returned slice length to
+  /// verify how much memory was allocated. Takes care of reserving memory for
+  /// any relevant control structures also.
+  grpc_slice MakeSlice(MemoryRequest request);
+
+  /// A C++ allocator for containers of T.
+  template <typename T>
+  class Container {
+   public:
+    using value_type = T;
+
+    /// Construct the allocator: \a underlying_allocator is borrowed, and must
+    /// outlive this object.
+    explicit Container(MemoryAllocator* underlying_allocator)
+        : underlying_allocator_(underlying_allocator) {}
+    template <typename U>
+    explicit Container(const Container<U>& other)
+        : underlying_allocator_(other.underlying_allocator()) {}
+
+    MemoryAllocator* underlying_allocator() const {
+      return underlying_allocator_;
+    }
+
+    T* allocate(size_t n) {
+      underlying_allocator_->Reserve(n * sizeof(T));
+      return static_cast<T*>(::operator new(n * sizeof(T)));
+    }
+    void deallocate(T* p, size_t n) {
+      ::operator delete(p);
+      underlying_allocator_->Release(n * sizeof(T));
+    }
+
+   private:
+    MemoryAllocator* underlying_allocator_;
+  };
+
+ protected:
+  /// 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:
+  std::shared_ptr<internal::MemoryAllocatorImpl> allocator_;
+};
+
+// Wrapper type around std::vector to make initialization against a
+// MemoryAllocator based container allocator easy.
+template <typename T>
+class Vector : public std::vector<T, MemoryAllocator::Container<T>> {
+ public:
+  explicit Vector(MemoryAllocator* allocator)
+      : std::vector<T, MemoryAllocator::Container<T>>(
+            MemoryAllocator::Container<T>(allocator)) {}
+};
+
+class MemoryAllocatorFactory {
+ public:
+  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(peer_address_string);
+  ///    auto* endpoint = allocator->New<MyEndpoint>(std::move(allocator), ...);
+  virtual MemoryAllocator CreateMemoryAllocator(absl::string_view name) = 0;
+};
+
+}  // namespace experimental
+}  // namespace grpc_event_engine
+
+#endif  // GRPC_EVENT_ENGINE_MEMORY_ALLOCATOR_H

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

@@ -17,9 +17,7 @@
 #include <grpc/support/port_platform.h>
 
 // Platform-specific sockaddr includes
-#ifdef GRPC_UV
-#include <uv.h>
-#elif defined(GPR_ANDROID) || defined(GPR_LINUX) || defined(GPR_APPLE) ||   \
+#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)

data/include/grpc/fork.h

@@ -21,6 +21,6 @@
 
 #include <grpc/support/port_platform.h>
 
-#include <grpc/impl/codegen/fork.h>
+#include <grpc/impl/codegen/fork.h>  // IWYU pragma: export
 
 #endif /* GRPC_FORK_H */

data/include/grpc/grpc.h

@@ -21,15 +21,15 @@
 
 #include <grpc/support/port_platform.h>
 
-#include <grpc/status.h>
+#include <stddef.h>
 
 #include <grpc/byte_buffer.h>
 #include <grpc/impl/codegen/connectivity_state.h>
 #include <grpc/impl/codegen/grpc_types.h>
 #include <grpc/impl/codegen/propagation_bits.h>
 #include <grpc/slice.h>
+#include <grpc/status.h>
 #include <grpc/support/time.h>
-#include <stddef.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -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(
@@ -340,6 +366,10 @@ GRPCAPI grpc_call_error grpc_call_cancel_with_status(grpc_call* call,
                                                      const char* description,
                                                      void* reserved);
 
+/* Returns whether or not the call's receive message operation failed because of
+ * an error (as opposed to a graceful end-of-stream) */
+GRPCAPI int grpc_call_failed_before_recv_message(const grpc_call* c);
+
 /** Ref a call.
     THREAD SAFETY: grpc_call_ref is thread-compatible */
 GRPCAPI void grpc_call_ref(grpc_call* call);
@@ -410,12 +440,18 @@ GRPCAPI void grpc_server_register_completion_queue(grpc_server* server,
                                                    grpc_completion_queue* cq,
                                                    void* reserved);
 
+// More members might be added in later, so users should take care to memset
+// this to 0 before using it.
+typedef struct {
+  grpc_status_code code;
+  const char* error_message;
+} grpc_serving_status_update;
+
 // There might be more methods added later, so users should take care to memset
 // this to 0 before using it.
 typedef struct {
   void (*on_serving_status_update)(void* user_data, const char* uri,
-                                   grpc_status_code code,
-                                   const char* error_message);
+                                   grpc_serving_status_update update);
   void* user_data;
 } grpc_server_xds_status_notifier;
 
@@ -434,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

@@ -21,10 +21,11 @@
 
 #include <grpc/support/port_platform.h>
 
-#include <grpc/impl/codegen/grpc_types.h>
-
 #include <stddef.h>
 
+#include <grpc/grpc.h>
+#include <grpc/impl/codegen/grpc_types.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -35,22 +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.
-    */
-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
 }