grpc 1.42.0 → 1.52.0

data/include/grpc/byte_buffer.h

@@ -21,7 +21,82 @@
 
 #include <grpc/support/port_platform.h>
 
-#include <grpc/impl/codegen/byte_buffer.h>  // IWYU pragma: export
+#include <grpc/impl/grpc_types.h>
 #include <grpc/slice_buffer.h>
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Returns a RAW byte buffer instance over the given slices (up to \a nslices).
+ *
+ * Increases the reference count for all \a slices processed. The user is
+ * responsible for invoking grpc_byte_buffer_destroy on the returned instance.*/
+GRPCAPI grpc_byte_buffer* grpc_raw_byte_buffer_create(grpc_slice* slices,
+                                                      size_t nslices);
+
+/** Returns a *compressed* RAW byte buffer instance over the given slices (up to
+ * \a nslices). The \a compression argument defines the compression algorithm
+ * used to generate the data in \a slices.
+ *
+ * Increases the reference count for all \a slices processed. The user is
+ * responsible for invoking grpc_byte_buffer_destroy on the returned instance.*/
+GRPCAPI grpc_byte_buffer* grpc_raw_compressed_byte_buffer_create(
+    grpc_slice* slices, size_t nslices, grpc_compression_algorithm compression);
+
+/** Copies input byte buffer \a bb.
+ *
+ * Increases the reference count of all the source slices. The user is
+ * responsible for calling grpc_byte_buffer_destroy over the returned copy. */
+GRPCAPI grpc_byte_buffer* grpc_byte_buffer_copy(grpc_byte_buffer* bb);
+
+/** Returns the size of the given byte buffer, in bytes. */
+GRPCAPI size_t grpc_byte_buffer_length(grpc_byte_buffer* bb);
+
+/** Destroys \a byte_buffer deallocating all its memory. */
+GRPCAPI void grpc_byte_buffer_destroy(grpc_byte_buffer* bb);
+
+/** Reader for byte buffers. Iterates over slices in the byte buffer */
+struct grpc_byte_buffer_reader;
+typedef struct grpc_byte_buffer_reader grpc_byte_buffer_reader;
+
+/** Initialize \a reader to read over \a buffer.
+ * Returns 1 upon success, 0 otherwise. */
+GRPCAPI int grpc_byte_buffer_reader_init(grpc_byte_buffer_reader* reader,
+                                         grpc_byte_buffer* buffer);
+
+/** Cleanup and destroy \a reader */
+GRPCAPI void grpc_byte_buffer_reader_destroy(grpc_byte_buffer_reader* reader);
+
+/** Updates \a slice with the next piece of data from from \a reader and returns
+ * 1. Returns 0 at the end of the stream. Caller is responsible for calling
+ * grpc_slice_unref on the result. */
+GRPCAPI int grpc_byte_buffer_reader_next(grpc_byte_buffer_reader* reader,
+                                         grpc_slice* slice);
+
+/** EXPERIMENTAL API - This function may be removed and changed, in the future.
+ *
+ * Updates \a slice with the next piece of data from from \a reader and returns
+ * 1. Returns 0 at the end of the stream. Caller is responsible for making sure
+ * the slice pointer remains valid when accessed.
+ *
+ * NOTE: Do not use this function unless the caller can guarantee that the
+ *       underlying grpc_byte_buffer outlasts the use of the slice. This is only
+ *       safe when the underlying grpc_byte_buffer remains immutable while slice
+ *       is being accessed. */
+GRPCAPI int grpc_byte_buffer_reader_peek(grpc_byte_buffer_reader* reader,
+                                         grpc_slice** slice);
+
+/** Merge all data from \a reader into single slice */
+GRPCAPI grpc_slice
+grpc_byte_buffer_reader_readall(grpc_byte_buffer_reader* reader);
+
+/** Returns a RAW byte buffer instance from the output of \a reader. */
+GRPCAPI grpc_byte_buffer* grpc_raw_byte_buffer_from_reader(
+    grpc_byte_buffer_reader* reader);
+
+#ifdef __cplusplus
+}
+#endif
+
 #endif /* GRPC_BYTE_BUFFER_H */

data/include/grpc/byte_buffer_reader.h

@@ -21,6 +21,24 @@
 
 #include <grpc/support/port_platform.h>
 
-#include <grpc/impl/codegen/byte_buffer_reader.h>  // IWYU pragma: export
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct grpc_byte_buffer;
+
+struct grpc_byte_buffer_reader {
+  struct grpc_byte_buffer* buffer_in;
+  struct grpc_byte_buffer* buffer_out;
+  /** Different current objects correspond to different types of byte buffers */
+  union grpc_byte_buffer_reader_current {
+    /** Index into a slice buffer's array of slices */
+    unsigned index;
+  } current;
+};
+
+#ifdef __cplusplus
+}
+#endif
 
 #endif /* GRPC_BYTE_BUFFER_READER_H */

data/include/grpc/compression.h

@@ -19,11 +19,11 @@
 #ifndef GRPC_COMPRESSION_H
 #define GRPC_COMPRESSION_H
 
-#include <grpc/impl/codegen/port_platform.h>
+#include <grpc/support/port_platform.h>
 
 #include <stdlib.h>
 
-#include <grpc/impl/codegen/compression_types.h>
+#include <grpc/impl/compression_types.h>  // IWYU pragma: export
 #include <grpc/slice.h>
 
 #ifdef __cplusplus

data/include/grpc/event_engine/endpoint_config.h

@@ -19,7 +19,7 @@
 #include <string>
 
 #include "absl/strings/string_view.h"
-#include "absl/types/variant.h"
+#include "absl/types/optional.h"
 
 namespace grpc_event_engine {
 namespace experimental {
@@ -31,10 +31,16 @@ namespace experimental {
 class EndpointConfig {
  public:
   virtual ~EndpointConfig() = default;
-  using Setting = absl::variant<absl::monostate, int, absl::string_view, void*>;
-  /// Returns the Setting for a specified key, or \a absl::monostate if there is
-  /// no such entry. Caller does not take ownership of the resulting value.
-  virtual Setting Get(absl::string_view key) const = 0;
+  // If the key points to an integer config, an integer value gets returned.
+  // Otherwise it returns an absl::nullopt_t
+  virtual absl::optional<int> GetInt(absl::string_view key) const = 0;
+  // If the key points to an string config, an string value gets returned.
+  // Otherwise it returns an absl::nullopt_t
+  virtual absl::optional<absl::string_view> GetString(
+      absl::string_view key) const = 0;
+  // If the key points to an void* config, a void* pointer value gets returned.
+  // Otherwise it returns nullptr
+  virtual void* GetVoidPointer(absl::string_view key) const = 0;
 };
 
 }  // namespace experimental

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 {
 
@@ -71,8 +72,13 @@ namespace experimental {
 ///    server->Wait();
 ///
 ////////////////////////////////////////////////////////////////////////////////
-class EventEngine {
+class EventEngine : public std::enable_shared_from_this<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,56 +370,96 @@ 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.
   ///
   /// \a Closures scheduled with \a Run cannot be cancelled. The \a closure will
   /// not be deleted after it has been run, ownership remains with the caller.
+  ///
+  /// Implementations must not execute the closure in the calling thread before
+  /// \a Run returns. For example, if the caller must release a lock before the
+  /// closure can proceed, running the closure immediately would cause a
+  /// deadlock.
   virtual void Run(Closure* closure) = 0;
   /// 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.
+  ///
+  /// Implementations must not execute the closure in the calling thread before
+  /// \a Run returns.
+  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.
+  ///
+  /// Implementations must not execute the closure in the calling thread before
+  /// \a RunAfter returns.
+  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. Unlike 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;
+  ///
+  /// Implementations must not execute the closure in the calling thread before
+  /// \a RunAfter returns.
+  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.
+  /// If the associated closure has not been scheduled to run, it will be
+  /// 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 cancellation (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 SetEventEngineFactory 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 SetEventEngineFactory(
+    absl::AnyInvocable<std::unique_ptr<EventEngine>()> factory);
+
+/// Reset gRPC's EventEngine factory to the built-in default.
+///
+/// Applications that have called \a SetEventEngineFactory can remove their
+/// custom factory using this method. The built-in EventEngine factories will be
+/// used going forward. This has no affect on any EventEngines that were created
+/// using the previous factories.
+void EventEngineFactoryReset();
+/// 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

@@ -14,49 +14,19 @@
 #ifndef GRPC_EVENT_ENGINE_INTERNAL_MEMORY_ALLOCATOR_IMPL_H
 #define GRPC_EVENT_ENGINE_INTERNAL_MEMORY_ALLOCATOR_IMPL_H
 
-#include <grpc/impl/codegen/port_platform.h>
+#include <grpc/support/port_platform.h>
 
 #include <algorithm>
 #include <memory>
 #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/internal/slice_cast.h

@@ -0,0 +1,67 @@
+// 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_SLICE_CAST_H
+#define GRPC_EVENT_ENGINE_INTERNAL_SLICE_CAST_H
+
+namespace grpc_event_engine {
+namespace experimental {
+namespace internal {
+
+// Opt-in trait class for slice conversions.
+// Declare a specialization of this class for any types that are compatible
+// with `SliceCast`. Both ways need to be declared (i.e. if
+// SliceCastable<A,B> exists, you should declare
+// SliceCastable<B,A> too).
+// The type has no members, it's just the existance of the specialization that
+// unlocks SliceCast usage for a type pair.
+template <typename Result, typename T>
+struct SliceCastable;
+
+// This is strictly too wide, but consider all types to be SliceCast-able to
+// themselves.
+// Unfortunately this allows `const int& x = SliceCast<int>(x);` which is kind
+// of bogus.
+template <typename A>
+struct SliceCastable<A, A> {};
+
+// Cast to `const Result&` from `const T&` without any runtime checks.
+// This is only valid if `sizeof(Result) == sizeof(T)`, and if `Result`, `T` are
+// opted in as compatible via `SliceCastable`.
+template <typename Result, typename T>
+const Result& SliceCast(const T& value, SliceCastable<Result, T> = {}) {
+  // Insist upon sizes being equal to catch mismatches.
+  // We assume if sizes are opted in and sizes are equal then yes, these two
+  // types are expected to be layout compatible and actually appear to be.
+  static_assert(sizeof(Result) == sizeof(T), "size mismatch");
+  return reinterpret_cast<const Result&>(value);
+}
+
+// Cast to `Result&` from `T&` without any runtime checks.
+// This is only valid if `sizeof(Result) == sizeof(T)`, and if `Result`, `T` are
+// opted in as compatible via `SliceCastable`.
+template <typename Result, typename T>
+Result& SliceCast(T& value, SliceCastable<Result, T> = {}) {
+  // Insist upon sizes being equal to catch mismatches.
+  // We assume if sizes are opted in and sizes are equal then yes, these two
+  // types are expected to be layout compatible and actually appear to be.
+  static_assert(sizeof(Result) == sizeof(T), "size mismatch");
+  return reinterpret_cast<Result&>(value);
+}
+
+}  // namespace internal
+}  // namespace experimental
+}  // namespace grpc_event_engine
+
+#endif  // GRPC_EVENT_ENGINE_INTERNAL_SLICE_CAST_H