grpc 1.71.0 → 1.74.0

data/include/grpc/event_engine/event_engine.h

@@ -16,16 +16,24 @@
 
 #include <grpc/event_engine/endpoint_config.h>
 #include <grpc/event_engine/extensible.h>
+#include <grpc/event_engine/internal/write_event.h>
 #include <grpc/event_engine/memory_allocator.h>
 #include <grpc/event_engine/port.h>
 #include <grpc/event_engine/slice_buffer.h>
 #include <grpc/support/port_platform.h>
 
+#include <bitset>
+#include <cstddef>
+#include <initializer_list>
+#include <memory>
+#include <optional>
+#include <utility>
 #include <vector>
 
 #include "absl/functional/any_invocable.h"
 #include "absl/status/status.h"
 #include "absl/status/statusor.h"
+#include "absl/types/span.h"
 
 // TODO(vigneshbabu): Define the Endpoint::Write metrics collection system
 // TODO(hork): remove all references to the factory methods.
@@ -180,13 +188,26 @@ class EventEngine : public std::enable_shared_from_this<EventEngine>,
     /// EventEngine Endpoint Read API  call.
     ///
     /// Passed as argument to an Endpoint \a Read
-    struct ReadArgs {
+    class ReadArgs final {
+     public:
+      ReadArgs() = default;
+      ReadArgs(const ReadArgs&) = delete;
+      ReadArgs& operator=(const ReadArgs&) = delete;
+      ReadArgs(ReadArgs&&) = default;
+      ReadArgs& operator=(ReadArgs&&) = default;
+
       // 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;
+      void set_read_hint_bytes(int64_t read_hint_bytes) {
+        read_hint_bytes_ = read_hint_bytes;
+      }
+      int64_t read_hint_bytes() const { return read_hint_bytes_; }
+
+     private:
+      int64_t read_hint_bytes_ = 1;
     };
     /// Reads data from the Endpoint.
     ///
@@ -212,21 +233,172 @@ class EventEngine : public std::enable_shared_from_this<EventEngine>,
     /// statuses to \a on_read. For example, callbacks might expect to receive
     /// CANCELLED on endpoint shutdown.
     virtual bool Read(absl::AnyInvocable<void(absl::Status)> on_read,
-                      SliceBuffer* buffer, const ReadArgs* args) = 0;
+                      SliceBuffer* buffer, ReadArgs args) = 0;
+    //// The set of write events that can be reported by an Endpoint.
+    using WriteEvent = ::grpc_event_engine::experimental::internal::WriteEvent;
+    /// An output WriteMetric consists of a key and a value.
+    /// The space of keys can be queried from the endpoint via the
+    /// \a AllWriteMetrics, \a GetMetricName and \a GetMetricKey APIs.
+    /// The value is an int64_t that is implementation-defined. Check with the
+    /// endpoint implementation documentation for the semantics of each metric.
+    struct WriteMetric {
+      size_t key;
+      int64_t value;
+    };
+    // It is the responsibility of the caller of WriteEventCallback to make sure
+    // that the corresponding endpoint is still valid. HINT: Do NOT offload
+    // callbacks onto the EventEngine or other threads.
+    using WriteEventCallback = absl::AnyInvocable<void(
+        WriteEvent, absl::Time, std::vector<WriteMetric>) const>;
+    // A bitmask of the events that the caller is interested in.
+    // Each bit corresponds to an entry in WriteEvent.
+    using WriteEventSet = std::bitset<static_cast<int>(WriteEvent::kCount)>;
+
+    // A set of metrics that the caller is interested in.
+    class MetricsSet {
+     public:
+      virtual ~MetricsSet() = default;
+
+      virtual bool IsSet(size_t key) const = 0;
+    };
+
+    // A sink to receive write events.
+    // The requested metrics are the keys of the metrics that the caller is
+    // interested in. The on_event callback will be called on each event
+    // requested.
+    class WriteEventSink final {
+     public:
+      WriteEventSink(std::shared_ptr<MetricsSet> requested_metrics,
+                     std::initializer_list<WriteEvent> requested_events,
+                     WriteEventCallback on_event)
+          : requested_metrics_(std::move(requested_metrics)),
+            on_event_(std::move(on_event)) {
+        for (auto event : requested_events) {
+          requested_events_mask_.set(static_cast<int>(event));
+        }
+      }
+
+      const std::shared_ptr<MetricsSet>& requested_metrics() const {
+        return requested_metrics_;
+      }
+
+      bool requested_event(WriteEvent event) const {
+        return requested_events_mask_.test(static_cast<int>(event));
+      }
+
+      WriteEventSet requested_events_mask() const {
+        return requested_events_mask_;
+      }
+
+      /// Takes the callback. Ownership is transferred. It is illegal to destroy
+      /// the endpoint before this callback is invoked.
+      WriteEventCallback TakeEventCallback() { return std::move(on_event_); }
+
+     private:
+      std::shared_ptr<MetricsSet> requested_metrics_;
+      WriteEventSet requested_events_mask_;
+      // The callback to be called on each event.
+      WriteEventCallback on_event_;
+    };
     /// 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 {
+    class WriteArgs final {
+     public:
+      WriteArgs() = default;
+
+      ~WriteArgs();
+
+      WriteArgs(const WriteArgs&) = delete;
+      WriteArgs& operator=(const WriteArgs&) = delete;
+
+      WriteArgs(WriteArgs&& other) noexcept
+          : metrics_sink_(std::move(other.metrics_sink_)),
+            google_specific_(other.google_specific_),
+            max_frame_size_(other.max_frame_size_) {
+        other.google_specific_ = nullptr;
+      }
+
+      WriteArgs& operator=(WriteArgs&& other) noexcept {
+        if (this != &other) {
+          metrics_sink_ = std::move(other.metrics_sink_);
+          google_specific_ = other.google_specific_;
+          other.google_specific_ = nullptr;  // Nullify source
+          max_frame_size_ = other.max_frame_size_;
+        }
+        return *this;
+      }
+
+      // A sink to receive write events.
+      std::optional<WriteEventSink> TakeMetricsSink() {
+        auto sink = std::move(metrics_sink_);
+        metrics_sink_.reset();
+        return sink;
+      }
+
+      bool has_metrics_sink() const { return metrics_sink_.has_value(); }
+
+      void set_metrics_sink(WriteEventSink sink) {
+        metrics_sink_ = std::move(sink);
+      }
+
       // Represents private information that may be passed by gRPC for
       // select endpoints expected to be used only within google.
-      void* google_specific = nullptr;
+      // TODO(ctiller): Remove this method once all callers are migrated to
+      // metrics sink.
+      void* GetDeprecatedAndDiscouragedGoogleSpecificPointer() {
+        return google_specific_;
+      }
+
+      void* TakeDeprecatedAndDiscouragedGoogleSpecificPointer() {
+        return std::exchange(google_specific_, nullptr);
+      }
+
+      void SetDeprecatedAndDiscouragedGoogleSpecificPointer(void* pointer) {
+        google_specific_ = pointer;
+      }
+
       // 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;
+      int64_t max_frame_size() const { return max_frame_size_; }
+
+      void set_max_frame_size(int64_t max_frame_size) {
+        max_frame_size_ = max_frame_size;
+      }
+
+     private:
+      std::optional<WriteEventSink> metrics_sink_;
+      void* google_specific_ = nullptr;
+      int64_t max_frame_size_ = 1024 * 1024;
     };
+
+    class TelemetryInfo {
+     public:
+      virtual ~TelemetryInfo() = default;
+
+      /// Returns the list of write metrics that the endpoint supports.
+      /// The keys are used to identify the metrics in the GetMetricName and
+      /// GetMetricKey APIs. The current value of the metric can be queried by
+      /// adding a WriteEventSink to the WriteArgs of a Write call.
+      virtual std::vector<size_t> AllWriteMetrics() const = 0;
+      /// Returns the name of the write metric with the given key.
+      /// If the key is not found, returns std::nullopt.
+      virtual std::optional<absl::string_view> GetMetricName(
+          size_t key) const = 0;
+      /// Returns the key of the write metric with the given name.
+      /// If the name is not found, returns std::nullopt.
+      virtual std::optional<size_t> GetMetricKey(
+          absl::string_view name) const = 0;
+      /// Returns a MetricsSet with all the keys from \a keys set.
+      virtual std::shared_ptr<MetricsSet> GetMetricsSet(
+          absl::Span<const size_t> keys) const = 0;
+      /// Returns a MetricsSet with all supported keys set.
+      virtual std::shared_ptr<MetricsSet> GetFullMetricsSet() const = 0;
+    };
+
     /// Writes data out on the connection.
     ///
     /// If the write succeeds immediately, it returns true and the
@@ -248,11 +420,13 @@ class EventEngine : public std::enable_shared_from_this<EventEngine>,
     /// statuses to \a on_writable. For example, callbacks might expect to
     /// receive CANCELLED on endpoint shutdown.
     virtual bool Write(absl::AnyInvocable<void(absl::Status)> on_writable,
-                       SliceBuffer* data, const WriteArgs* args) = 0;
+                       SliceBuffer* data, 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;
     virtual const ResolvedAddress& GetLocalAddress() const = 0;
+
+    virtual std::shared_ptr<TelemetryInfo> GetTelemetryInfo() const = 0;
   };
 
   /// Called when a new connection is established.
@@ -334,7 +508,7 @@ class EventEngine : public std::enable_shared_from_this<EventEngine>,
   /// when the object is destroyed and all pending callbacks will be called
   /// shortly. If cancellation races with request completion, implementations
   /// may choose to either cancel or satisfy the request.
-  class DNSResolver {
+  class DNSResolver : public Extensible {
    public:
     /// Optional configuration for DNSResolvers.
     struct ResolverOptions {

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

@@ -0,0 +1,34 @@
+// Copyright 2022 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_INTERNAL_WRITE_EVENT_H
+#define GRPC_EVENT_ENGINE_INTERNAL_WRITE_EVENT_H
+
+namespace grpc_event_engine::experimental::internal {
+
+// Use of this enum via this name is internal to gRPC.
+// API users should get this enumeration via the
+// EventEngine::Endpoint::WriteEvent.
+enum class WriteEvent {
+  kSendMsg,
+  kScheduled,
+  kSent,
+  kAcked,
+  kClosed,
+  kCount  // Must be last.
+};
+
+}  // namespace grpc_event_engine::experimental::internal
+
+#endif  // GRPC_EVENT_ENGINE_INTERNAL_WRITE_EVENT_H

data/include/grpc/event_engine/memory_request.h

@@ -55,11 +55,11 @@ class MemoryRequest {
   template <typename Sink>
   friend void AbslStringify(Sink& s, const MemoryRequest& r) {
     if (r.min_ == r.max_) {
-      s.Append(r.min_);
+      s.Append(std::to_string(r.min_));
     } else {
-      s.Append(r.min_);
+      s.Append(std::to_string(r.min_));
       s.Append("..");
-      s.Append(r.max_);
+      s.Append(std::to_string(r.max_));
     }
   }
 

data/include/grpc/grpc_posix.h

@@ -56,6 +56,25 @@ GRPCAPI void grpc_server_add_channel_from_fd(grpc_server* server, int fd,
 
 #ifdef __cplusplus
 }
-#endif
+
+namespace grpc_core::experimental {
+
+/**
+ * EXPERIMENTAL API - Subject to change
+ *
+ * This function creates a gRPC channel using a raw file descriptor
+ * that represents an open socket. This API supports both secure and insecure
+ * channel credentials.
+ *
+ * \param fd The file descriptor representing the connection.
+ * \param creds The channel credentials used to secure the connection.
+ * \param args Optional channel arguments to configure the channel behavior.
+ */
+grpc_channel* CreateChannelFromFd(int fd, grpc_channel_credentials* creds,
+                                  const grpc_channel_args* args);
+
+}  // namespace grpc_core::experimental
+
+#endif  // __cplusplus
 
 #endif /* GRPC_GRPC_POSIX_H */

data/include/grpc/impl/channel_arg_names.h

@@ -31,13 +31,15 @@
 #define GRPC_ARG_SERVER_CALL_METRIC_RECORDING \
   "grpc.server_call_metric_recording"
 /** Request that optional features default to off (regardless of what they
-    usually default to) - to enable tight control over what gets enabled */
+    usually default to) - to enable tight control over what gets enabled
+    Boolean valued. Defaults to false. */
 #define GRPC_ARG_MINIMAL_STACK "grpc.minimal_stack"
 /** Maximum number of concurrent incoming streams to allow on a http2
-    connection. Int valued. */
+    connection. Int valued. Deafult to -1(indicating no explicit limit).*/
 #define GRPC_ARG_MAX_CONCURRENT_STREAMS "grpc.max_concurrent_streams"
 /** Maximum message length that the channel can receive. Int valued, bytes.
-    -1 means unlimited. */
+    -1 means unlimited. Defaults to 4MB(4*1024*1024 bytes). -1 means unlimited.
+ */
 #define GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH "grpc.max_receive_message_length"
 /** \deprecated For backward compatibility.
  * Use GRPC_ARG_MAX_RECEIVE_MESSAGE_LENGTH instead. */
@@ -47,27 +49,31 @@
 #define GRPC_ARG_MAX_SEND_MESSAGE_LENGTH "grpc.max_send_message_length"
 /** Maximum time that a channel may have no outstanding rpcs, after which the
  * server will close the connection. Int valued, milliseconds. INT_MAX means
- * unlimited. */
+ * unlimited. Defaults to INT_MAX. */
 #define GRPC_ARG_MAX_CONNECTION_IDLE_MS "grpc.max_connection_idle_ms"
-/** Maximum time that a channel may exist. Int valued, milliseconds.
- * INT_MAX means unlimited. */
+/** Maximum amount of time in milliseconds that a connection may exist before it
+ * will be gracefully shut down. Refer
+ * https://github.com/grpc/proposal/blob/master/A9-server-side-conn-mgt.md for
+ * more details. Int valued, defaults to INT_MAX (disabled). */
 #define GRPC_ARG_MAX_CONNECTION_AGE_MS "grpc.max_connection_age_ms"
-/** Grace period after the channel reaches its max age. Int valued,
-   milliseconds. INT_MAX means unlimited. */
+/** Grace period in milliseconds after connection reaches its max age for
+ * outstanding RPCs to complete. Int valued, defaults to INT_MAX (disabled). */
 #define GRPC_ARG_MAX_CONNECTION_AGE_GRACE_MS "grpc.max_connection_age_grace_ms"
 /** Timeout after the last RPC finishes on the client channel at which the
  * channel goes back into IDLE state. Int valued, milliseconds. INT_MAX means
  * unlimited. The default value is 30 minutes and the min value is 1 second. */
 #define GRPC_ARG_CLIENT_IDLE_TIMEOUT_MS "grpc.client_idle_timeout_ms"
-/** Enable/disable support for per-message compression. Defaults to 1, unless
-    GRPC_ARG_MINIMAL_STACK is enabled, in which case it defaults to 0. */
+/** Enable/disable support for per-message compression. Boolean valued. Defaults
+   to true, unless GRPC_ARG_MINIMAL_STACK is enabled, in which case it defaults
+   to false. */
 #define GRPC_ARG_ENABLE_PER_MESSAGE_COMPRESSION "grpc.per_message_compression"
 /** Experimental Arg. Enable/disable support for per-message decompression.
    Defaults to 1. If disabled, decompression will not be performed and the
    application will see the compressed message in the byte buffer. */
 #define GRPC_ARG_ENABLE_PER_MESSAGE_DECOMPRESSION \
   "grpc.per_message_decompression"
-/** Initial stream ID for http2 transports. Int valued. */
+/** Initial stream ID for http2 transports. Int valued. Defaults to -1
+    indicating use of default http2 setting initial stream ID (1). */
 #define GRPC_ARG_HTTP2_INITIAL_SEQUENCE_NUMBER \
   "grpc.http2.initial_sequence_number"
 /** Amount to read ahead on individual streams. Defaults to 64kb, larger
@@ -75,17 +81,22 @@
     NOTE: at some point we'd like to auto-tune this, and this parameter
     will become a no-op. Int valued, bytes. */
 #define GRPC_ARG_HTTP2_STREAM_LOOKAHEAD_BYTES "grpc.http2.lookahead_bytes"
-/** How much memory to use for hpack decoding. Int valued, bytes. */
+/** How much memory to use for hpack decoding. Int valued, bytes. Defaults to -1
+    indicating use of default http2 setting(4096 bytes). */
 #define GRPC_ARG_HTTP2_HPACK_TABLE_SIZE_DECODER \
   "grpc.http2.hpack_table_size.decoder"
-/** How much memory to use for hpack encoding. Int valued, bytes. */
+/** How much memory to use for hpack encoding. Int valued, bytes. Defaults to -1
+    indicating use of default http2 setting(4096 bytes). */
 #define GRPC_ARG_HTTP2_HPACK_TABLE_SIZE_ENCODER \
   "grpc.http2.hpack_table_size.encoder"
 /** How big a frame are we willing to receive via HTTP2.
     Min 16384, max 16777215. Larger values give lower CPU usage for large
-    messages, but more head of line blocking for small messages. */
+    messages, but more head of line blocking for small messages. Defaults to
+   -1(indicating no explicit max frame size), so it will take standard http/2
+   specified max frame size to 16 KB. */
 #define GRPC_ARG_HTTP2_MAX_FRAME_SIZE "grpc.http2.max_frame_size"
-/** Should BDP probing be performed? */
+/** Should BDP probing be performed?
+    Boolean valued. Defaults to true(enabled). */
 #define GRPC_ARG_HTTP2_BDP_PROBE "grpc.http2.bdp_probe"
 /** (DEPRECATED) Does not have any effect.
     Earlier, this arg configured the minimum time between successive ping frames
@@ -109,21 +120,22 @@
     before the request is cancelled */
 #define GRPC_ARG_SERVER_MAX_UNREQUESTED_TIME_IN_SERVER_SECONDS \
   "grpc.server_max_unrequested_time_in_server"
-/** Channel arg to override the http2 :scheme header */
+/** Channel arg to override the http2 :scheme header. String valued. */
 #define GRPC_ARG_HTTP2_SCHEME "grpc.http2_scheme"
 /** How many pings can the client send before needing to send a data/header
-   frame? (0 indicates that an infinite number of pings can be sent without
-   sending a data frame or header frame).
-   If experiment "max_pings_wo_data_throttle" is enabled, instead of pings being
-   completely blocked, they are throttled. */
+   frame, without being throttled? (0 indicates that an infinite number of pings
+  can be sent without sending a data frame or header frame).
+  * Integer valued. Defaults to 2. */
 #define GRPC_ARG_HTTP2_MAX_PINGS_WITHOUT_DATA \
   "grpc.http2.max_pings_without_data"
 /** How many misbehaving pings the server can bear before sending goaway and
     closing the transport? (0 indicates that the server can bear an infinite
-    number of misbehaving pings) */
+    number of misbehaving pings)
+  * Integer valued. Defaults to 2. */
 #define GRPC_ARG_HTTP2_MAX_PING_STRIKES "grpc.http2.max_ping_strikes"
 /** How much data are we willing to queue up per stream if
-    GRPC_WRITE_BUFFER_HINT is set? This is an upper bound */
+    GRPC_WRITE_BUFFER_HINT is set? This is an upper bound
+  * Integer valued, bytes. Defaults to 65535 bytes. */
 #define GRPC_ARG_HTTP2_WRITE_BUFFER_SIZE "grpc.http2.write_buffer_size"
 /** Should we allow receipt of true-binary data on http2 connections?
     Defaults to on (1) */
@@ -136,33 +148,44 @@
 #define GRPC_ARG_EXPERIMENTAL_HTTP2_PREFERRED_CRYPTO_FRAME_SIZE \
   "grpc.experimental.http2.enable_preferred_frame_size"
 /** After a duration of this time the client/server pings its peer to see if the
-    transport is still alive. Int valued, milliseconds. */
+    transport is still alive. Int valued, milliseconds. Defaults to 7200000 (2
+   hours). */
 #define GRPC_ARG_KEEPALIVE_TIME_MS "grpc.keepalive_time_ms"
 /** After waiting for a duration of this time, if the keepalive ping sender does
     not receive the ping ack, it will close the transport. Int valued,
-    milliseconds. */
+    milliseconds. Defaults to 20000 (20 seonds). */
 #define GRPC_ARG_KEEPALIVE_TIMEOUT_MS "grpc.keepalive_timeout_ms"
 /** Is it permissible to send keepalive pings from the client without any
-   outstanding streams. Int valued, 0(false)/1(true). */
+   outstanding streams. Int valued, 0(false)/1(true). Defaults to 0. */
 #define GRPC_ARG_KEEPALIVE_PERMIT_WITHOUT_CALLS \
   "grpc.keepalive_permit_without_calls"
 /** Default authority to pass if none specified on call construction. A string.
  * */
 #define GRPC_ARG_DEFAULT_AUTHORITY "grpc.default_authority"
 /** Primary user agent: goes at the start of the user-agent metadata
-    sent on each request. A string. */
+    sent on each request. A string. Defaults to empty string(""). */
 #define GRPC_ARG_PRIMARY_USER_AGENT_STRING "grpc.primary_user_agent"
 /** Secondary user agent: goes at the end of the user-agent metadata
     sent on each request. A string. */
 #define GRPC_ARG_SECONDARY_USER_AGENT_STRING "grpc.secondary_user_agent"
-/** The minimum time between subsequent connection attempts, in ms */
+/** The minimum time between subsequent connection attempts, in ms. Refer to
+ * MIN_CONNECT_TIMEOUT from
+ * https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md. Defaults
+ * to 20 seconds. */
 #define GRPC_ARG_MIN_RECONNECT_BACKOFF_MS "grpc.min_reconnect_backoff_ms"
-/** The maximum time between subsequent connection attempts, in ms */
+/** The maximum time between subsequent connection attempts, in ms. Refer to
+ * MAX_BACKOFF from
+ * https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md. Defaults
+ * to 120 seconds.  */
 #define GRPC_ARG_MAX_RECONNECT_BACKOFF_MS "grpc.max_reconnect_backoff_ms"
-/** The time between the first and second connection attempts, in ms */
+/** The time between the first and second connection attempts, in ms. Refer to
+ * INITIAL_BACKOFF from
+ * https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md. Defaults
+ * to 1 second. */
 #define GRPC_ARG_INITIAL_RECONNECT_BACKOFF_MS \
   "grpc.initial_reconnect_backoff_ms"
-/** Minimum amount of time between DNS resolutions, in ms */
+/** Minimum amount of time between DNS resolutions, in ms. Defaults to 30
+ * seconds. */
 #define GRPC_ARG_DNS_MIN_TIME_BETWEEN_RESOLUTIONS_MS \
   "grpc.dns_min_time_between_resolutions_ms"
 /** The timeout used on servers for finishing handshaking on an incoming
@@ -178,10 +201,10 @@
 #define GRPC_SSL_TARGET_NAME_OVERRIDE_ARG "grpc.ssl_target_name_override"
 /** If non-zero, a pointer to a session cache (a pointer of type
     grpc_ssl_session_cache*). (use grpc_ssl_session_cache_arg_vtable() to fetch
-    an appropriate pointer arg vtable) */
+    an appropriate pointer arg vtable). */
 #define GRPC_SSL_SESSION_CACHE_ARG "grpc.ssl_session_cache"
 /** If non-zero, it will determine the maximum frame size used by TSI's frame
- *  protector.
+ *  protector. Defaults to zero.
  */
 #define GRPC_ARG_TSI_MAX_FRAME_SIZE "grpc.tsi.max_frame_size"
 /** Maximum metadata size (soft limit), in bytes. Note this limit applies to the
@@ -200,17 +223,20 @@
 #define GRPC_ARG_ALLOW_REUSEPORT "grpc.so_reuseport"
 /** If non-zero, a pointer to a buffer pool (a pointer of type
  * grpc_resource_quota*). (use grpc_resource_quota_arg_vtable() to fetch an
- * appropriate pointer arg vtable) */
+ * appropriate pointer arg vtable). */
 #define GRPC_ARG_RESOURCE_QUOTA "grpc.resource_quota"
-/** If non-zero, expand wildcard addresses to a list of local addresses. */
+/** If non-zero, expand wildcard addresses to a list of local addresses. Boolean
+ * valued. */
 #define GRPC_ARG_EXPAND_WILDCARD_ADDRS "grpc.expand_wildcard_addrs"
 /** Service config data in JSON form.
-    This value will be ignored if the name resolver returns a service config. */
+    This value will be ignored if the name resolver returns a service config. A
+   string value. */
 #define GRPC_ARG_SERVICE_CONFIG "grpc.service_config"
-/** Disable looking up the service config via the name resolver. */
+/** Disable looking up the service config via the name resolver. Boolean valued.
+ * Defaults to true. */
 #define GRPC_ARG_SERVICE_CONFIG_DISABLE_RESOLUTION \
   "grpc.service_config_disable_resolution"
-/** LB policy name. */
+/** LB policy name. A string value.*/
 #define GRPC_ARG_LB_POLICY_NAME "grpc.lb_policy_name"
 /** Cap for ring size in the ring_hash LB policy.  The min and max ring size
     values set in the LB policy config will be capped to this value.
@@ -223,24 +249,23 @@
 /** The maximum amount of memory used by trace events per channel trace node.
  * Once the maximum is reached, subsequent events will evict the oldest events
  * from the buffer. The unit for this knob is bytes. Setting it to zero causes
- * channel tracing to be disabled. */
+ * channel tracing to be disabled. Defaults to (1024 * 4) bytes. */
 #define GRPC_ARG_MAX_CHANNEL_TRACE_EVENT_MEMORY_PER_NODE \
   "grpc.max_channel_trace_event_memory_per_node"
 /** If non-zero, gRPC library will track stats and information at at per channel
  * level. Disabling channelz naturally disables channel tracing. The default
  * is for channelz to be enabled. */
 #define GRPC_ARG_ENABLE_CHANNELZ "grpc.enable_channelz"
-/** If non-zero, Cronet transport will coalesce packets to fewer frames
- * when possible. */
-#define GRPC_ARG_USE_CRONET_PACKET_COALESCING \
-  "grpc.use_cronet_packet_coalescing"
 /** Channel arg (integer) setting how large a slice to try and read from the
-   wire each time recvmsg (or equivalent) is called **/
+   wire each time recvmsg (or equivalent). Range varied from 1
+   to (32 * 1024 * 1024) bytes. Defaults to 8192 bytes. **/
 #define GRPC_ARG_TCP_READ_CHUNK_SIZE "grpc.experimental.tcp_read_chunk_size"
 /** Note this is not a "channel arg" key. This is the default slice size to use
  * when trying to read from the wire if the GRPC_ARG_TCP_READ_CHUNK_SIZE
  * channel arg is unspecified. */
 #define GRPC_TCP_DEFAULT_READ_SLICE_SIZE 8192
+/** Minimum read chunk size defaults to 256 bytes. Range varies from 1 to (32 *
+ * 1024 * 1024) bytes. */
 #define GRPC_ARG_TCP_MIN_READ_CHUNK_SIZE \
   "grpc.experimental.tcp_min_read_chunk_size"
 #define GRPC_ARG_TCP_MAX_READ_CHUNK_SIZE \
@@ -259,10 +284,12 @@
    issued by the tcp_write(). By default, this is set to 4. */
 #define GRPC_ARG_TCP_TX_ZEROCOPY_MAX_SIMULT_SENDS \
   "grpc.experimental.tcp_tx_zerocopy_max_simultaneous_sends"
-/* Overrides the TCP socket receive buffer size, SO_RCVBUF. */
+/* Overrides the TCP socket receive buffer size, SO_RCVBUF.
+    Default value is -1(kReadBufferSizeUnset) indicating that the system will
+    decide the buffer size. Range varies from 0 to INT_MAX. */
 #define GRPC_ARG_TCP_RECEIVE_BUFFER_SIZE "grpc.tcp_receive_buffer_size"
 /* Timeout in milliseconds to use for calls to the grpclb load balancer.
-   If 0 or unset, the balancer calls will have no deadline. */
+   If 0 or unset, the balancer calls will have no deadline. Defaults to 0 ms. */
 #define GRPC_ARG_GRPCLB_CALL_TIMEOUT_MS "grpc.grpclb_call_timeout_ms"
 /* Specifies the xDS bootstrap config as a JSON string.
    FOR TESTING PURPOSES ONLY -- DO NOT USE IN PRODUCTION.
@@ -277,7 +304,7 @@
   "grpc.TEST_ONLY_DO_NOT_USE_IN_PROD.xds_bootstrap_config"
 /* Timeout in milliseconds to wait for the serverlist from the grpclb load
    balancer before using fallback backend addresses from the resolver.
-   If 0, enter fallback mode immediately. Default value is 10000. */
+   If 0, enter fallback mode immediately. Default value is 10000ms. */
 #define GRPC_ARG_GRPCLB_FALLBACK_TIMEOUT_MS "grpc.grpclb_fallback_timeout_ms"
 /* Experimental Arg. Channel args to be used for the control-plane channel
  * created to the grpclb load balancers. This is a pointer arg whose value is a
@@ -290,9 +317,6 @@
    over to the next priority. Default value is 10 seconds. */
 #define GRPC_ARG_PRIORITY_FAILOVER_TIMEOUT_MS \
   "grpc.priority_failover_timeout_ms"
-/** If non-zero, grpc server's cronet compression workaround will be enabled */
-#define GRPC_ARG_WORKAROUND_CRONET_COMPRESSION \
-  "grpc.workaround.cronet_compression"
 /** String defining the optimization target for a channel.
     Can be: "latency"    - attempt to minimize latency at the cost of throughput
             "blend"      - try to balance latency and throughput
@@ -325,13 +349,15 @@
 /** Channel arg that carries the bridged objective c object for custom metrics
  * logging filter. */
 #define GRPC_ARG_MOBILE_LOG_CONTEXT "grpc.mobile_log_context"
-/** If non-zero, client authority filter is disabled for the channel */
+/** If non-zero, client authority filter is disabled for the channel.
+ *  Boolean valued. Defaults to false. */
 #define GRPC_ARG_DISABLE_CLIENT_AUTHORITY_FILTER \
   "grpc.disable_client_authority_filter"
 /** If set to zero, disables use of http proxies. Enabled by default. */
 #define GRPC_ARG_ENABLE_HTTP_PROXY "grpc.enable_http_proxy"
 /** Channel arg to set http proxy per channel. If set, the channel arg
- *  value will be preferred over the environment variable settings. */
+ *  value will be preferred over the environment variable settings. String
+ * value. */
 #define GRPC_ARG_HTTP_PROXY "grpc.http_proxy"
 /** Specifies an HTTP proxy to use for individual addresses.
  *  The proxy must be specified as an IP address, not a DNS name.
@@ -347,7 +373,7 @@
     agent is surfaced by default. */
 #define GRPC_ARG_SURFACE_USER_AGENT "grpc.surface_user_agent"
 /** If set, inhibits health checking (which may be enabled via the
- *  service config.) */
+ *  service config.). Boolean valued. Defaults to false. */
 #define GRPC_ARG_INHIBIT_HEALTH_CHECKING "grpc.inhibit_health_checking"
 /** If enabled, the channel's DNS resolver queries for SRV records.
  *  This is useful only when using the "grpclb" load balancing policy,
@@ -356,17 +382,17 @@
  *   https://github.com/grpc/proposal/blob/master/A24-lb-policy-config.md
  *   https://github.com/grpc/proposal/blob/master/A26-grpclb-selection.md
  *  Note that this works only with the "ares" DNS resolver; it isn't supported
- *  by the "native" DNS resolver. */
+ *  by the "native" DNS resolver. Boolean valued. Defaults to false. */
 #define GRPC_ARG_DNS_ENABLE_SRV_QUERIES "grpc.dns_enable_srv_queries"
 /** If set, determines an upper bound on the number of milliseconds that the
  * c-ares based DNS resolver will wait on queries before cancelling them.
- * The default value is 120,000. Setting this to "0" will disable the
+ * The default value is 120,000ms. Setting this to "0" will disable the
  * overall timeout entirely. Note that this doesn't include internal c-ares
  * timeouts/backoff/retry logic, and so the actual DNS resolution may time out
  * sooner than the value specified here. */
 #define GRPC_ARG_DNS_ARES_QUERY_TIMEOUT_MS "grpc.dns_ares_query_timeout"
 /** If set, uses a local subchannel pool within the channel. Otherwise, uses the
- * global subchannel pool. */
+ * global subchannel pool. Boolean valued. Defaults to false. */
 #define GRPC_ARG_USE_LOCAL_SUBCHANNEL_POOL "grpc.use_local_subchannel_pool"
 /** gRPC Objective-C channel pooling domain string. */
 #define GRPC_ARG_CHANNEL_POOL_DOMAIN "grpc.channel_pooling_domain"

data/include/grpc/impl/compression_types.h

@@ -41,8 +41,9 @@ extern "C" {
  * Its value is an int from the \a grpc_compression_algorithm enum. */
 #define GRPC_COMPRESSION_CHANNEL_DEFAULT_ALGORITHM \
   "grpc.default_compression_algorithm"
-/** Default compression level for the channel.
- * Its value is an int from the \a grpc_compression_level enum. */
+/** Set the default compression level for the channel.
+ * Valid values are defined by the enum type grpc_compression_level, defaults to
+ * GRPC_COMPRESS_LEVEL_NONE. */
 #define GRPC_COMPRESSION_CHANNEL_DEFAULT_LEVEL "grpc.default_compression_level"
 /** Compression algorithms supported by the channel.
  * Its value is a bitset (an int). Bits correspond to algorithms in \a