grpc 1.39.0 → 1.41.0

data/include/grpc/event_engine/event_engine.h

@@ -23,9 +23,9 @@
 #include "absl/status/statusor.h"
 #include "absl/time/time.h"
 
-#include "grpc/event_engine/endpoint_config.h"
-#include "grpc/event_engine/port.h"
-#include "grpc/event_engine/slice_allocator.h"
+#include <grpc/event_engine/endpoint_config.h>
+#include <grpc/event_engine/port.h>
+#include <grpc/event_engine/slice_allocator.h>
 
 // TODO(hork): Define the Endpoint::Write metrics collection system
 namespace grpc_event_engine {
@@ -73,16 +73,16 @@ namespace experimental {
 ////////////////////////////////////////////////////////////////////////////////
 class EventEngine {
  public:
-  /// A basic callable function. The first argument to all callbacks is an
+  /// Basic callable function. The first argument to all callbacks is an
   /// absl::Status indicating the status of the operation associated with this
   /// callback. Each EventEngine method that takes a callback parameter, defines
   /// the expected sets and meanings of statuses for that use case.
   using Callback = std::function<void(absl::Status)>;
-  /// A callback handle, used to cancel a callback.
+  /// Callback handle, used to cancel a callback.
   struct TaskHandle {
-    intptr_t key;
+    intptr_t keys[2];
   };
-  /// A thin wrapper around a platform-specific sockaddr type. A sockaddr struct
+  /// Thin wrapper around a platform-specific sockaddr type. A sockaddr struct
   /// exists on all platforms that gRPC supports.
   ///
   /// Platforms are expected to provide definitions for:
@@ -104,9 +104,9 @@ class EventEngine {
     socklen_t size_ = 0;
   };
 
-  /// An Endpoint represents one end of a connection between a gRPC client and
-  /// server. Endpoints are created when connections are established, and
-  /// Endpoint operations are gRPC's primary means of communication.
+  /// One end of a connection between a gRPC client and server. Endpoints are
+  /// created when connections are established, and Endpoint operations are
+  /// gRPC's primary means of communication.
   ///
   /// Endpoints must use the provided SliceAllocator for all data buffer memory
   /// allocations. gRPC allows applications to set memory constraints per
@@ -114,10 +114,10 @@ class EventEngine {
   /// allocation being handled by the quota system.
   class Endpoint {
    public:
-    /// The Endpoint destructor is responsible for shutting down all connections
-    /// and invoking all pending read or write callbacks with an error status.
+    /// Shuts down all connections and invokes all pending read or write
+    /// callbacks with an error status.
     virtual ~Endpoint() = default;
-    /// Read data from the Endpoint.
+    /// Reads data from the Endpoint.
     ///
     /// When data is available on the connection, that data is moved into the
     /// \a buffer, and the \a on_read callback is called. The caller must ensure
@@ -125,30 +125,39 @@ class EventEngine {
     /// Ownership of the buffer is not transferred. Valid slices *may* be placed
     /// into the buffer even if the callback is invoked with a non-OK Status.
     ///
+    /// There can be at most one outstanding read per Endpoint at any given
+    /// time. An outstanding read is one in which the \a on_read callback has
+    /// not yet been executed for some previous call to \a Read.  If an attempt
+    /// is made to call \a Read while a previous read is still outstanding, the
+    /// \a EventEngine must abort.
+    ///
     /// For failed read operations, implementations should pass the appropriate
     /// statuses to \a on_read. For example, callbacks might expect to receive
-    /// DEADLINE_EXCEEDED when the deadline is exceeded, and CANCELLED on
-    /// endpoint shutdown.
-    virtual void Read(Callback on_read, SliceBuffer* buffer,
-                      absl::Time deadline) = 0;
-    /// Write data out on the connection.
+    /// CANCELLED on endpoint shutdown.
+    virtual void Read(Callback on_read, SliceBuffer* buffer) = 0;
+    /// Writes data out on the connection.
     ///
     /// \a on_writable is called when the connection is ready for more data. The
     /// Slices within the \a data buffer may be mutated at will by the Endpoint
     /// until \a on_writable is called. The \a data SliceBuffer will remain
-    /// valid after calling \a Write, but its state is otherwise undefined.
+    /// valid after calling \a Write, but its state is otherwise undefined.  All
+    /// bytes in \a data must have been written before calling \a on_writable
+    /// unless an error has occurred.
+    ///
+    /// There can be at most one outstanding write per Endpoint at any given
+    /// time. An outstanding write is one in which the \a on_writable callback
+    /// has not yet been executed for some previous call to \a Write.  If an
+    /// attempt is made to call \a Write while a previous write is still
+    /// outstanding, the \a EventEngine must abort.
     ///
     /// For failed write operations, implementations should pass the appropriate
     /// statuses to \a on_writable. For example, callbacks might expect to
-    /// receive DEADLINE_EXCEEDED when the deadline is exceeded, and CANCELLED
-    /// on endpoint shutdown.
-    virtual void Write(Callback on_writable, SliceBuffer* data,
-                       absl::Time deadline) = 0;
-    /// These methods return an address in the format described in DNSResolver.
-    /// The returned values are owned by the Endpoint and are expected to remain
-    /// valid for the life of the Endpoint.
-    virtual const ResolvedAddress* GetPeerAddress() const = 0;
-    virtual const ResolvedAddress* GetLocalAddress() const = 0;
+    /// receive CANCELLED on endpoint shutdown.
+    virtual void Write(Callback on_writable, SliceBuffer* data) = 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;
+    virtual const ResolvedAddress& GetLocalAddress() const = 0;
   };
 
   /// Called when a new connection is established.
@@ -160,12 +169,13 @@ class EventEngine {
   using OnConnectCallback =
       std::function<void(absl::StatusOr<std::unique_ptr<Endpoint>>)>;
 
-  /// An EventEngine Listener listens for incoming connection requests from gRPC
-  /// clients and initiates request processing once connections are established.
+  /// 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(std::unique_ptr<Endpoint>)>;
+    using AcceptCallback = std::function<void(
+        std::unique_ptr<Endpoint>, const SliceAllocator& slice_allocator)>;
     virtual ~Listener() = default;
     /// Bind an address/port to this Listener.
     ///
@@ -179,14 +189,10 @@ class EventEngine {
   /// Factory method to create a network listener / server.
   ///
   /// Once a \a Listener is created and started, the \a on_accept callback will
-  /// be called once asynchronously for each established connection. Note that
-  /// unlike other callbacks, there is no status code parameter since the
-  /// callback will only be called in healthy scenarios where connections can be
-  /// accepted.
-  ///
-  /// This method may return a non-OK status immediately if an error was
-  /// encountered in any synchronous steps required to create the Listener. In
-  /// this case, \a on_shutdown will never be called.
+  /// be called once asynchronously for each established connection. This method
+  /// may return a non-OK status immediately if an error was encountered in any
+  /// synchronous steps required to create the Listener. In this case,
+  /// \a on_shutdown will never be called.
   ///
   /// If this method returns a Listener, then \a on_shutdown will be invoked
   /// exactly once, when the Listener is shut down. The status passed to it will
@@ -196,13 +202,13 @@ class EventEngine {
   /// for Endpoint construction.
   virtual absl::StatusOr<std::unique_ptr<Listener>> CreateListener(
       Listener::AcceptCallback on_accept, Callback on_shutdown,
-      const EndpointConfig& args,
-      SliceAllocatorFactory slice_allocator_factory) = 0;
+      const EndpointConfig& config,
+      std::unique_ptr<SliceAllocatorFactory> slice_allocator_factory) = 0;
   /// Creates a client network connection to a remote network listener.
   ///
-  /// \a Connect 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
+  /// 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.
   ///
@@ -214,17 +220,17 @@ class EventEngine {
   virtual absl::Status Connect(OnConnectCallback on_connect,
                                const ResolvedAddress& addr,
                                const EndpointConfig& args,
-                               SliceAllocator slice_allocator,
+                               std::unique_ptr<SliceAllocator> slice_allocator,
                                absl::Time deadline) = 0;
 
-  /// The DNSResolver that provides asynchronous resolution.
+  /// Provides asynchronous resolution.
   class DNSResolver {
    public:
-    /// A task handle for DNS Resolution requests.
+    /// Task handle for DNS Resolution requests.
     struct LookupTaskHandle {
-      intptr_t key;
+      intptr_t key[2];
     };
-    /// A DNS SRV record type.
+    /// DNS SRV record type.
     struct SRVRecord {
       std::string host;
       int port = 0;
@@ -275,35 +281,40 @@ class EventEngine {
     virtual void TryCancelLookup(LookupTaskHandle handle) = 0;
   };
 
+  /// At time of destruction, the EventEngine must have no active
+  /// responsibilities. EventEngine users (applications) are responsible for
+  /// cancelling all tasks and DNS lookups, shutting down listeners and
+  /// endpoints, prior to EventEngine destruction. If there are any outstanding
+  /// tasks, any running listeners, etc. at time of EventEngine destruction,
+  /// that is an invalid use of the API, and it will result in undefined
+  /// behavior.
   virtual ~EventEngine() = default;
 
   // TODO(nnoble): consider whether we can remove this method before we
   // de-experimentalize this API.
   virtual bool IsWorkerThread() = 0;
 
-  // TODO(hork): define return status codes
-  /// Retrieves an instance of a DNSResolver.
-  virtual absl::StatusOr<std::unique_ptr<DNSResolver>> GetDNSResolver() = 0;
+  /// Creates and returns an instance of a DNSResolver.
+  virtual std::unique_ptr<DNSResolver> GetDNSResolver() = 0;
 
-  /// Intended for future expansion of Task run functionality.
-  struct RunOptions {};
-  /// Run a callback as soon as possible.
+  /// Executes a callback as soon as possible.
   ///
   /// The \a fn callback's \a status argument is used to indicate whether it was
-  /// executed normally. For example, the status may be CANCELLED if
-  /// \a TryCancel was called, or if the EventEngine is being shut down.
-  virtual TaskHandle Run(Callback fn, RunOptions opts) = 0;
+  /// executed normally. For example, the status may be CANCELLED if the
+  /// EventEngine is being shut down. \a fn is guaranteed to be called exactly
+  /// once.
+  virtual void Run(Callback fn) = 0;
   /// Synonymous with scheduling an alarm to run at time \a when.
   ///
   /// The callback \a fn will execute when either when time \a when arrives
-  /// (receiving status OK), or when the \a fn is cancelled (reveiving status
+  /// (receiving status OK), or when the \a fn is cancelled (receiving status
   /// CANCELLED). The callback is guaranteed to be called exactly once.
-  virtual TaskHandle RunAt(absl::Time when, Callback fn, RunOptions opts) = 0;
-  /// Immediately tries to cancel a callback.
+  virtual TaskHandle RunAt(absl::Time when, Callback fn) = 0;
+  /// Attempts to cancel a callback.
   /// Note that this is a "best effort" cancellation. No guarantee is made that
   /// the callback will be cancelled, the call could be in any stage.
   ///
-  /// There are three scenarios in which we may cancel a scheduled function:
+  /// There are three scenarios in which we may cancel a scheduled task:
   ///   1. We cancel the execution before it has run.
   ///   2. The callback has already run.
   ///   3. We can't cancel it because it is "in flight".
@@ -312,16 +323,6 @@ class EventEngine {
   /// callback will be run exactly once from either cancellation or from its
   /// activation.
   virtual void TryCancel(TaskHandle handle) = 0;
-  /// Immediately run all callbacks with status indicating the shutdown. Every
-  /// EventEngine is expected to shut down exactly once. No new callbacks/tasks
-  /// should be scheduled after shutdown has begun, no new connections should be
-  /// created.
-  ///
-  /// If the \a on_shutdown_complete callback is given a non-OK status, errors
-  /// are expected to be unrecoverable. For example, an implementation could
-  /// warn callers about leaks if memory cannot be freed within a certain
-  /// timeframe.
-  virtual void Shutdown(Callback on_shutdown_complete) = 0;
 };
 
 // TODO(hork): finalize the API and document it. We need to firm up the story

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/event_engine/slice_allocator.h

@@ -28,27 +28,22 @@ struct grpc_slice_buffer;
 namespace grpc_event_engine {
 namespace experimental {
 
-// TODO(hork): stubbed out here, to be replaced with a real version in next PR.
+// 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_;
 };
 
 class SliceAllocator {
  public:
-  // gRPC-internal constructor
-  explicit SliceAllocator(grpc_resource_user* user);
-  // Not copyable
-  SliceAllocator(SliceAllocator& other) = delete;
-  SliceAllocator& operator=(const SliceAllocator& other) = delete;
-  // Moveable
-  SliceAllocator(SliceAllocator&& other) noexcept;
-  SliceAllocator& operator=(SliceAllocator&& other) noexcept;
-  ~SliceAllocator();
-
-  using AllocateCallback =
-      std::function<void(absl::Status, SliceBuffer* buffer)>;
+  using AllocateCallback = std::function<void(absl::Status)>;
+  virtual ~SliceAllocator() = default;
   /// Requests \a size bytes from gRPC, and populates \a dest with the allocated
   /// slices. Ownership of the \a SliceBuffer is not transferred.
   ///
@@ -57,32 +52,17 @@ class SliceAllocator {
   /// interrupted to attempt to reclaim memory from participating gRPC
   /// internals. When there is sufficient memory available, slice allocation
   /// proceeds as normal.
-  absl::Status Allocate(size_t size, SliceBuffer* dest,
-                        SliceAllocator::AllocateCallback cb);
-
- private:
-  grpc_resource_user* resource_user_;
+  virtual absl::Status Allocate(size_t size, SliceBuffer* dest,
+                                SliceAllocator::AllocateCallback cb) = 0;
 };
 
 class SliceAllocatorFactory {
  public:
-  // gRPC-internal constructor
-  explicit SliceAllocatorFactory(grpc_resource_quota* quota);
-  // Not copyable
-  SliceAllocatorFactory(SliceAllocatorFactory& other) = delete;
-  SliceAllocatorFactory& operator=(const SliceAllocatorFactory& other) = delete;
-  // Moveable
-  SliceAllocatorFactory(SliceAllocatorFactory&& other) noexcept;
-  SliceAllocatorFactory& operator=(SliceAllocatorFactory&& other) noexcept;
-  ~SliceAllocatorFactory();
-
+  virtual ~SliceAllocatorFactory() = default;
   /// On Endpoint creation, call \a CreateSliceAllocator with the name of the
-  /// endpoint peer (a URI string, most likely). Note: \a peer_name must outlive
-  /// the Endpoint.
-  SliceAllocator CreateSliceAllocator(absl::string_view peer_name);
-
- private:
-  grpc_resource_quota* resource_quota_;
+  /// endpoint peer (a URI string, most likely).
+  virtual std::unique_ptr<SliceAllocator> CreateSliceAllocator(
+      absl::string_view peer_name) = 0;
 };
 
 }  // namespace experimental

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" {
@@ -410,12 +410,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;
 

data/include/grpc/grpc_posix.h

@@ -21,10 +21,10 @@
 
 #include <grpc/support/port_platform.h>
 
-#include <grpc/impl/codegen/grpc_types.h>
-
 #include <stddef.h>
 
+#include <grpc/impl/codegen/grpc_types.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -48,6 +48,9 @@ GRPCAPI grpc_channel* grpc_insecure_channel_create_from_fd(
     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);

data/include/grpc/impl/codegen/atm.h

@@ -19,6 +19,8 @@
 #ifndef GRPC_IMPL_CODEGEN_ATM_H
 #define GRPC_IMPL_CODEGEN_ATM_H
 
+// IWYU pragma: private, include <grpc/support/atm.h>
+
 /** This interface provides atomic operations and barriers.
    It is internal to gpr support code and should not be used outside it.
 
@@ -70,11 +72,11 @@
 #include <grpc/impl/codegen/port_platform.h>
 
 #if defined(GPR_GCC_ATOMIC)
-#include <grpc/impl/codegen/atm_gcc_atomic.h>
+#include <grpc/impl/codegen/atm_gcc_atomic.h>  // IWYU pragma: export
 #elif defined(GPR_GCC_SYNC)
-#include <grpc/impl/codegen/atm_gcc_sync.h>
+#include <grpc/impl/codegen/atm_gcc_sync.h>  // IWYU pragma: export
 #elif defined(GPR_WINDOWS_ATOMIC)
-#include <grpc/impl/codegen/atm_windows.h>
+#include <grpc/impl/codegen/atm_windows.h>  // IWYU pragma: export
 #else
 #error could not determine platform for atm
 #endif

data/include/grpc/impl/codegen/atm_gcc_atomic.h

@@ -19,6 +19,8 @@
 #ifndef GRPC_IMPL_CODEGEN_ATM_GCC_ATOMIC_H
 #define GRPC_IMPL_CODEGEN_ATM_GCC_ATOMIC_H
 
+// IWYU pragma: private, include <grpc/support/atm.h>
+
 /* atm_platform.h for gcc and gcc-like compilers with the
    __atomic_* interface.  */
 #include <grpc/impl/codegen/port_platform.h>

data/include/grpc/impl/codegen/atm_gcc_sync.h

@@ -19,6 +19,8 @@
 #ifndef GRPC_IMPL_CODEGEN_ATM_GCC_SYNC_H
 #define GRPC_IMPL_CODEGEN_ATM_GCC_SYNC_H
 
+// IWYU pragma: private, include <grpc/support/atm.h>
+
 /* variant of atm_platform.h for gcc and gcc-like compiers with __sync_*
    interface */
 #include <grpc/impl/codegen/port_platform.h>

data/include/grpc/impl/codegen/atm_windows.h

@@ -19,6 +19,8 @@
 #ifndef GRPC_IMPL_CODEGEN_ATM_WINDOWS_H
 #define GRPC_IMPL_CODEGEN_ATM_WINDOWS_H
 
+// IWYU pragma: private, include <grpc/support/atm.h>
+
 /** Win32 variant of atm_platform.h */
 #include <grpc/impl/codegen/port_platform.h>
 

data/include/grpc/impl/codegen/byte_buffer.h

@@ -19,6 +19,8 @@
 #ifndef GRPC_IMPL_CODEGEN_BYTE_BUFFER_H
 #define GRPC_IMPL_CODEGEN_BYTE_BUFFER_H
 
+// IWYU pragma: private, include <grpc/byte_buffer.h>
+
 #include <grpc/impl/codegen/port_platform.h>
 
 #include <grpc/impl/codegen/grpc_types.h>

data/include/grpc/impl/codegen/byte_buffer_reader.h

@@ -19,6 +19,8 @@
 #ifndef GRPC_IMPL_CODEGEN_BYTE_BUFFER_READER_H
 #define GRPC_IMPL_CODEGEN_BYTE_BUFFER_READER_H
 
+// IWYU pragma: private, include <grpc/byte_buffer_reader.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif

data/include/grpc/impl/codegen/compression_types.h

@@ -19,6 +19,8 @@
 #ifndef GRPC_IMPL_CODEGEN_COMPRESSION_TYPES_H
 #define GRPC_IMPL_CODEGEN_COMPRESSION_TYPES_H
 
+// IWYU pragma: private
+
 #include <grpc/impl/codegen/port_platform.h>
 
 #ifdef __cplusplus

data/include/grpc/impl/codegen/connectivity_state.h

@@ -19,6 +19,8 @@
 #ifndef GRPC_IMPL_CODEGEN_CONNECTIVITY_STATE_H
 #define GRPC_IMPL_CODEGEN_CONNECTIVITY_STATE_H
 
+// IWYU pragma: private
+
 #ifdef __cplusplus
 extern "C" {
 #endif

data/include/grpc/impl/codegen/fork.h

@@ -19,6 +19,8 @@
 #ifndef GRPC_IMPL_CODEGEN_FORK_H
 #define GRPC_IMPL_CODEGEN_FORK_H
 
+// IWYU pragma: private, include <grpc/fork.h>
+
 /**
  * gRPC applications should call this before calling fork().  There should be no
  * active gRPC function calls between calling grpc_prefork() and

data/include/grpc/impl/codegen/gpr_slice.h

@@ -18,6 +18,8 @@
 #ifndef GRPC_IMPL_CODEGEN_GPR_SLICE_H
 #define GRPC_IMPL_CODEGEN_GPR_SLICE_H
 
+// IWYU pragma: private
+
 /** WARNING: Please do not use this header. This was added as a temporary
  * measure to not break some of the external projects that depend on
  * gpr_slice_* functions. We are actively working on moving all the

data/include/grpc/impl/codegen/gpr_types.h

@@ -19,6 +19,8 @@
 #ifndef GRPC_IMPL_CODEGEN_GPR_TYPES_H
 #define GRPC_IMPL_CODEGEN_GPR_TYPES_H
 
+// IWYU pragma: private
+
 #include <grpc/impl/codegen/port_platform.h>
 
 #include <stddef.h>

data/include/grpc/impl/codegen/grpc_types.h

@@ -19,15 +19,17 @@
 #ifndef GRPC_IMPL_CODEGEN_GRPC_TYPES_H
 #define GRPC_IMPL_CODEGEN_GRPC_TYPES_H
 
+// IWYU pragma: private
+
 #include <grpc/impl/codegen/port_platform.h>
 
+#include <stddef.h>
+
 #include <grpc/impl/codegen/compression_types.h>
 #include <grpc/impl/codegen/gpr_types.h>
 #include <grpc/impl/codegen/slice.h>
 #include <grpc/impl/codegen/status.h>
 
-#include <stddef.h>
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -55,9 +57,6 @@ typedef struct grpc_byte_buffer {
  * asynchronous actions. */
 typedef struct grpc_completion_queue grpc_completion_queue;
 
-/** An alarm associated with a completion queue. */
-typedef struct grpc_alarm grpc_alarm;
-
 /** The Channel interface allows creation of Call objects. */
 typedef struct grpc_channel grpc_channel;
 
@@ -384,12 +383,26 @@ typedef struct {
     Defaults to "blend". In the current implementation "blend" is equivalent to
     "latency". */
 #define GRPC_ARG_OPTIMIZATION_TARGET "grpc.optimization_target"
-/** If set to zero, disables retry behavior. Otherwise, transparent retries
-    are enabled for all RPCs, and configurable retries are enabled when they
-    are configured via the service config. For details, see:
+/** Enables retry functionality.  Defaults to true.  When enabled,
+    configurable retries are enabled when they are configured via the
+    service config.  For details, see:
       https://github.com/grpc/proposal/blob/master/A6-client-retries.md
+    NOTE: Transparent retries are not yet implemented.  When they are
+          implemented, they will also be enabled by this arg.
+    NOTE: Hedging functionality is not yet implemented, so those
+          fields in the service config will currently be ignored.  See
+          also the GRPC_ARG_EXPERIMENTAL_ENABLE_HEDGING arg below.
  */
 #define GRPC_ARG_ENABLE_RETRIES "grpc.enable_retries"
+/** Enables hedging functionality, as described in:
+      https://github.com/grpc/proposal/blob/master/A6-client-retries.md
+    Default is currently false, since this functionality is not yet
+    fully implemented.
+    NOTE: This channel arg is experimental and will eventually be removed.
+          Once hedging functionality has been implemented and proves stable,
+          this arg will be removed, and the hedging functionality will
+          be enabled via the GRPC_ARG_ENABLE_RETRIES arg above. */
+#define GRPC_ARG_EXPERIMENTAL_ENABLE_HEDGING "grpc.experimental.enable_hedging"
 /** Per-RPC retry buffer size, in bytes. Default is 256 KiB. */
 #define GRPC_ARG_PER_RPC_RETRY_BUFFER_SIZE "grpc.per_rpc_retry_buffer_size"
 /** Channel arg that carries the bridged objective c object for custom metrics
@@ -495,6 +508,7 @@ typedef enum grpc_call_error {
   (GRPC_WRITE_BUFFER_HINT | GRPC_WRITE_NO_COMPRESS | GRPC_WRITE_THROUGH)
 
 /** Initial metadata flags */
+/** These flags are to be passed to the `grpc_op::flags` field */
 /** Signal that the call is idempotent */
 #define GRPC_INITIAL_METADATA_IDEMPOTENT_REQUEST (0x00000010u)
 /** Signal that the call should not return UNAVAILABLE before it has started */
@@ -522,8 +536,6 @@ typedef struct grpc_metadata {
   grpc_slice key;
   grpc_slice value;
 
-  uint32_t flags;
-
   /** The following fields are reserved for grpc internal use.
       There is no need to initialize them, and they will be set to garbage
       during calls to grpc. */
@@ -770,9 +782,6 @@ typedef struct grpc_completion_queue_functor {
   struct grpc_completion_queue_functor* internal_next;
 } grpc_completion_queue_functor;
 
-typedef grpc_completion_queue_functor
-    grpc_experimental_completion_queue_functor;
-
 #define GRPC_CQ_CURRENT_VERSION 2
 #define GRPC_CQ_VERSION_MINIMUM_FOR_CALLBACKABLE 2
 typedef struct grpc_completion_queue_attributes {

data/include/grpc/impl/codegen/log.h

@@ -19,6 +19,8 @@
 #ifndef GRPC_IMPL_CODEGEN_LOG_H
 #define GRPC_IMPL_CODEGEN_LOG_H
 
+// IWYU pragma: private, include <grpc/support/log.h>
+
 #include <grpc/impl/codegen/port_platform.h>
 
 #include <stdarg.h>