Add an EmbedderContext type for passing opaque state from the

calling application to extension functions.

PiperOrigin-RevId: 846796365

Author: jnthntatum

common/typeinfo.h

@@ -15,6 +15,7 @@
 #ifndef THIRD_PARTY_CEL_CPP_COMMON_TYPEINFO_H_
 #define THIRD_PARTY_CEL_CPP_COMMON_TYPEINFO_H_
 
+#include <atomic>
 #include <cstddef>
 #include <ostream>
 #include <string>
@@ -175,7 +176,6 @@ struct TypeTag final {
 
 template <typename T>
 TypeInfo TypeId() {
-  static_assert(!std::is_pointer_v<T>);
   static_assert(std::is_same_v<T, std::decay_t<T>>);
   static_assert(!std::is_same_v<TypeInfo, std::decay_t<T>>);
 #ifdef CEL_INTERNAL_HAVE_RTTI
@@ -193,6 +193,29 @@ inline std::ostream& operator<<(std::ostream& out, TypeInfo id) {
   return out << id.DebugString();
 }
 
+// Helper class for adapting a type to an index in a tuple or array.
+// Scope is an arbitrary type used as a namespace for the index.
+template <typename Scope>
+class TypeIdInSet {
+ public:
+  template <typename T>
+  static size_t IndexFor() {
+    static size_t index =
+        type_id_set_index_.fetch_add(1, std::memory_order_relaxed);
+    return index;
+  }
+
+  static size_t Size() {
+    return type_id_set_index_.load(std::memory_order_relaxed);
+  }
+
+ private:
+  static std::atomic<size_t> type_id_set_index_;
+};
+
+template <typename Scope>
+std::atomic<size_t> TypeIdInSet<Scope>::type_id_set_index_ = 0;
+
 }  // namespace cel
 
 #endif  // THIRD_PARTY_CEL_CPP_COMMON_TYPEINFO_H_

common/values/custom_value.h

@@ -70,6 +70,11 @@ class CustomValueContent final {
     return value;
   }
 
+  bool IsZero() const {
+    static const CustomValueContent kZero = Zero();
+    return std::memcmp(raw_, kZero.raw_, sizeof(raw_)) == 0;
+  }
+
  private:
   alignas(void*) std::byte raw_[16];
 };

runtime/BUILD

@@ -650,3 +650,26 @@ cc_test(
         "@com_google_protobuf//:protobuf",
     ],
 )
+
+cc_library(
+    name = "embedder_context",
+    hdrs = ["embedder_context.h"],
+    deps = [
+        "//common:typeinfo",
+        "//common:value",
+        "@com_google_absl//absl/container:inlined_vector",
+        "@com_google_absl//absl/log:absl_check",
+        "@com_google_absl//absl/types:optional",
+    ],
+)
+
+cc_test(
+    name = "embedder_context_test",
+    srcs = ["embedder_context_test.cc"],
+    deps = [
+        ":embedder_context",
+        "//common:typeinfo",
+        "//internal:testing",
+        "@com_google_absl//absl/types:optional",
+    ],
+)

runtime/embedder_context.h

@@ -0,0 +1,147 @@
+// Copyright 2025 Google LLC
+//
+// 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
+//
+//     https://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 THIRD_PARTY_CEL_CPP_RUNTIME_EMBEDDER_CONTEXT_H_
+#define THIRD_PARTY_CEL_CPP_RUNTIME_EMBEDDER_CONTEXT_H_
+
+#include <cstddef>
+#include <type_traits>
+
+#include "absl/container/inlined_vector.h"
+#include "absl/log/absl_check.h"
+#include "absl/types/optional.h"
+#include "common/typeinfo.h"
+#include "common/value.h"
+
+namespace cel {
+
+// EmbedderContext is used to package custom content defined by the embedder
+// during CEL evaluation. The custom content is indexed by type. Value types
+// are returned as absl::optional<T> where T is the value type. Pointer types
+// are returned as T*.
+//
+// The content values must be trivially copyable and have a size <= 16 bytes.
+// These are typically pointers or small value types (e.g. primitives, enums).
+//
+// An all zero memory value is used to represent an empty value. The caller
+// must provide some way to disambiguate if that is a meaningfully distinct
+// value from nullopt / nullptr.
+//
+// Scope is used to provide a distinction between multiple usages of CEL in the
+// same binary.
+class EmbedderContext {
+ public:
+  template <typename Scope, typename... Args>
+  static EmbedderContext From(Args... args);
+
+  // Convenience using a default scope.
+  template <typename... Args>
+  static EmbedderContext From(Args... args) {
+    return From<EmbedderContext, Args...>(args...);
+  }
+
+  template <typename Scope, typename T>
+  std::enable_if_t<!std::is_pointer_v<T>, absl::optional<T>> Get() const;
+
+  template <typename Scope, typename T>
+  std::enable_if_t<std::is_pointer_v<T>, T> Get() const;
+
+  template <typename T>
+  std::enable_if_t<!std::is_pointer_v<T>, absl::optional<T>> Get() const {
+    return Get<EmbedderContext, T>();
+  }
+
+  template <typename T>
+  std::enable_if_t<std::is_pointer_v<T>, T> Get() const {
+    return Get<EmbedderContext, T>();
+  }
+
+ private:
+  template <typename Scope, typename T, typename... Ts>
+  void Set(T arg, Ts... args);
+
+  template <typename Scope>
+  void Set() {}
+
+  absl::InlinedVector<cel::CustomValueContent, 2> values_;
+  // These are included to check for bad accesses in debug mode.
+  absl::InlinedVector<TypeInfo, 2> type_ids_;
+  TypeInfo scope_;
+};
+
+template <typename Scope, typename Arg, typename... Args>
+void EmbedderContext::Set(Arg arg, Args... args) {
+  using IndexType = std::decay_t<Arg>;
+  size_t index = TypeIdInSet<Scope>::template IndexFor<IndexType>();
+  if (index >= values_.size()) {
+    values_.resize(index + 1, cel::CustomValueContent::Zero());
+    type_ids_.resize(index + 1);
+  }
+  values_[index] = cel::CustomValueContent::From(arg);
+  type_ids_[index] = cel::TypeId<IndexType>();
+  Set<Scope>(args...);
+}
+
+template <typename Scope, typename T>
+std::enable_if_t<!std::is_pointer_v<T>, absl::optional<T>>
+EmbedderContext::Get() const {
+  ABSL_DCHECK_EQ(cel::TypeId<Scope>(), scope_)
+      << "EmbedderContext::Get wrong scope";
+  using IndexType = std::decay_t<T>;
+  size_t index = TypeIdInSet<Scope>::template IndexFor<IndexType>();
+  if (index >= values_.size()) {
+    return absl::nullopt;
+  }
+
+  const auto& content = values_[index];
+  if (content.IsZero()) return absl::nullopt;
+
+  ABSL_DCHECK_EQ(type_ids_.size(), values_.size());
+  ABSL_DCHECK_EQ(type_ids_[index], cel::TypeId<IndexType>())
+      << "EmbedderContext::Get wrong type id";
+
+  return content.To<T>();
+}
+
+template <typename Scope, typename T>
+std::enable_if_t<std::is_pointer_v<T>, T> EmbedderContext::Get() const {
+  ABSL_DCHECK_EQ(cel::TypeId<Scope>(), scope_)
+      << "EmbedderContext::Get wrong scope";
+  using IndexType = std::decay_t<T>;
+  size_t index = TypeIdInSet<Scope>::template IndexFor<IndexType>();
+  if (index >= values_.size()) {
+    return nullptr;
+  }
+
+  const auto& content = values_[index];
+  if (content.IsZero()) return nullptr;
+
+  ABSL_DCHECK_EQ(type_ids_.size(), values_.size());
+  ABSL_DCHECK_EQ(type_ids_[index], cel::TypeId<IndexType>())
+      << "EmbedderContext::Get wrong type id";
+
+  return content.To<T>();
+}
+
+template <typename Scope, typename... Args>
+EmbedderContext EmbedderContext::From(Args... args) {
+  EmbedderContext context;
+  context.scope_ = TypeId<Scope>();
+  context.Set<Scope>(args...);
+  return context;
+}
+
+}  // namespace cel
+
+#endif  // THIRD_PARTY_CEL_CPP_RUNTIME_EMBEDDER_CONTEXT_H_

runtime/embedder_context_test.cc

@@ -0,0 +1,93 @@
+// Copyright 2025 Google LLC
+//
+// 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
+//
+//     https://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.
+
+#include "runtime/embedder_context.h"
+
+#include <cstdint>
+
+#include "absl/types/optional.h"
+#include "common/typeinfo.h"
+#include "internal/testing.h"
+
+namespace cel {
+namespace {
+
+using ::testing::Optional;
+
+TEST(EmbedderContextTest, From) {
+  struct TestScope {};
+  EmbedderContext context = EmbedderContext::From<TestScope>(int64_t{42});
+  EXPECT_THAT((context.Get<TestScope, int64_t>()), Optional(42));
+  EXPECT_EQ((context.Get<TestScope, uint64_t>()), absl::nullopt);
+
+  EmbedderContext context2 = EmbedderContext::From<TestScope>(uint64_t{42});
+  EXPECT_THAT((context2.Get<TestScope, uint64_t>()), Optional(42));
+  EXPECT_EQ((context2.Get<TestScope, int64_t>()), absl::nullopt);
+
+  // Side effect, but checking that we keep a dense range.
+  EXPECT_EQ(cel::TypeIdInSet<TestScope>::Size(), 2);
+}
+
+TEST(EmbedderContextTest, FromOutOfLine) {
+  struct TestScope {};
+  EmbedderContext context =
+      EmbedderContext::From<TestScope>(int64_t{42}, uint64_t{43}, double{44});
+
+  EXPECT_THAT((context.Get<TestScope, int64_t>()), Optional(42));
+  EXPECT_THAT((context.Get<TestScope, uint64_t>()), Optional(43));
+  EXPECT_THAT((context.Get<TestScope, double>()), Optional(44));
+  EXPECT_EQ((context.Get<TestScope, bool>()), absl::nullopt);
+
+  // Note: Referencing a type not intended to be stored will still reserve a
+  // slot in the TypeIdInSet.
+  EXPECT_EQ(cel::TypeIdInSet<TestScope>::Size(), 4);
+}
+
+TEST(EmbedderContextTest, FromPtrs) {
+  struct TestScope {};
+  struct TestPointee {
+  } foo;
+  int64_t pointee2;
+
+  EmbedderContext context = EmbedderContext::From<TestScope>(
+      &foo, const_cast<const int64_t*>(&pointee2));
+  EXPECT_EQ((context.Get<TestScope, const int64_t*>()), &pointee2);
+  EXPECT_EQ((context.Get<TestScope, TestPointee*>()), &foo);
+
+  EmbedderContext context2 = EmbedderContext::From<TestScope>(&foo);
+  EXPECT_EQ((context2.Get<TestScope, int64_t*>()), nullptr);
+  EXPECT_EQ((context2.Get<TestScope, TestPointee*>()), &foo);
+
+  // Note: const int* not the same as int*.
+  EXPECT_EQ(cel::TypeIdInSet<TestScope>::Size(), 3);
+}
+
+TEST(EmbedderContextTest, FromDefaultScope) {
+  EmbedderContext context = EmbedderContext::From(int64_t{42});
+  EXPECT_THAT((context.Get<int64_t>()), Optional(42));
+  EXPECT_EQ((context.Get<uint64_t>()), absl::nullopt);
+}
+
+// These death assertions are only enabled when compiled in debug mode.
+// Caller is responsible for adequately testing since we're limited in what
+// we can statically check due to the type-erasure.
+TEST(EmbedderContextDeathTest, GetWithWrongScope) {
+  struct TestScope {};
+  EmbedderContext context = EmbedderContext::From<TestScope>(int64_t{42});
+  EXPECT_DEBUG_DEATH(
+      { context.Get<int64_t>(); }, "EmbedderContext::Get wrong scope");
+}
+
+}  // namespace
+}  // namespace cel