Managed execution frame with async call foundations (#1316)

* Managed execution frame with async call support
* Pare the ExecutionFrame down to just capturing current functionality
* Update the lifecycle expectations for AsyncOp

Author: TristonianJones

common/functions/functions.go

@@ -15,7 +15,11 @@
 // Package functions defines the standard builtin functions supported by the interpreter
 package functions
 
-import "github.com/google/cel-go/common/types/ref"
+import (
+	"context"
+
+	"github.com/google/cel-go/common/types/ref"
+)
 
 // Overload defines a named overload of a function, indicating an operand trait
 // which must be present on the first argument to the overload as well as one
@@ -41,21 +45,37 @@ type Overload struct {
 	// Binary defines the overload with a BinaryOp implementation. May be nil.
 	Binary BinaryOp
 
-	// Function defines the overload with a FunctionOp implementation. May be
-	// nil.
+	// Function defines the overload with a FunctionOp implementation. May be nil.
 	Function FunctionOp
 
+	// Async defines the overload with an AsyncOp implementation. May be nil.
+	Async AsyncOp
+
 	// NonStrict specifies whether the Overload will tolerate arguments that
 	// are types.Err or types.Unknown.
 	NonStrict bool
 }
 
 // UnaryOp is a function that takes a single value and produces an output.
-type UnaryOp func(value ref.Val) ref.Val
+type UnaryOp func(ref.Val) ref.Val
 
 // BinaryOp is a function that takes two values and produces an output.
-type BinaryOp func(lhs ref.Val, rhs ref.Val) ref.Val
+type BinaryOp func(ref.Val, ref.Val) ref.Val
 
 // FunctionOp is a function with accepts zero or more arguments and produces
 // a value or error as a result.
-type FunctionOp func(values ...ref.Val) ref.Val
+type FunctionOp func(...ref.Val) ref.Val
+
+// AsyncOp is a function that accepts zero or more arguments and produces
+// a value or error asynchronously via a channel.
+//
+// AsyncOp is an internal interface intended for use by CEL to manage goroutines and
+// channels associated with async calls. For public API usage, use BlockingAsyncOp.
+// Implementers should listen for context cancellation on the provided context for
+// resource cleanup.
+type AsyncOp func(context.Context, ...ref.Val) <-chan ref.Val
+
+// BlockingAsyncOp is a function that accepts zero or more arguments and blocks until
+// the result is available. When used with AsyncBinding, the framework runs the function
+// in its own goroutine and manages channel lifecycle internally.
+type BlockingAsyncOp func(context.Context, ...ref.Val) ref.Val

common/types/unknown.go

@@ -181,6 +181,20 @@ func (u *Unknown) GetAttributeTrails(id int64) ([]*AttributeTrail, bool) {
 	return trails, found
 }
 
+// HasUnknownFunction returns whether any of the attribute trails contained within the unknown
+// are unspecified. Unspecified attributes typically indicate an unresolved function call
+// or operation, rather than a missing variable.
+func (u *Unknown) HasUnknownFunction() bool {
+	for _, trails := range u.attributeTrails {
+		for _, t := range trails {
+			if t.variable == "" {
+				return true
+			}
+		}
+	}
+	return false
+}
+
 // Contains returns true if the input unknown is a subset of the current unknown.
 func (u *Unknown) Contains(other *Unknown) bool {
 	for id, otherTrails := range other.attributeTrails {

interpreter/frame.go

@@ -0,0 +1,221 @@
+// Copyright 2026 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
+//
+//      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.
+
+package interpreter
+
+import (
+	"context"
+	"sync"
+	"sync/atomic"
+)
+
+// evalContext contains the stateful information needed for a single evaluation.
+//
+// This state is shared across all frames within a single evaluation, including
+// child frames created for comprehension blocks.
+type evalContext struct {
+	// interrupt exposes a callback channel for cancellation.
+	interrupt <-chan struct{}
+
+	// interruptCheckCount is the number of times the interrupt channel has been checked.
+	interruptCheckCount atomic.Uint64
+
+	// interruptCheckFrequency is the frequency at which the interrupt channel is checked.
+	interruptCheckFrequency uint
+
+	// interrupted indicates whether the evaluation has been interrupted.
+	interrupted atomic.Bool
+
+	// state provides the context for tracking the evaluation state.
+	state EvalState
+
+	// costs provides the context for tracking the evaluation costs.
+	costs *CostTracker
+
+	// ctx is the context for async call implementations to use.
+	ctx context.Context
+
+	// cancel cancels the context when the evaluation is finished.
+	cancel context.CancelFunc
+}
+
+// ExecutionFrame provides the context for a single evaluation of an expression.
+//
+// The execution frame must not be stored in any fashion as its lifecycle is completely
+// controlled by the CEL evaluation process.
+type ExecutionFrame struct {
+	// Activation provides the context for resolving variables by name.
+	Activation
+
+	// parent provides the context for parent scopes (used for comprehension iterators).
+	parent *ExecutionFrame
+
+	// ctx provides the shared evaluation state across frames.
+	ctx *evalContext
+}
+
+// NewExecutionFrame creates a new execution frame from the pool.
+func NewExecutionFrame(vars Activation) *ExecutionFrame {
+	f := frameStack.Get().(*ExecutionFrame)
+	f.Activation = vars
+	return f
+}
+
+// SetContext sets the context for the execution frame.
+func (f *ExecutionFrame) SetContext(ctx context.Context, interruptCheckFrequency uint) {
+	if f.ctx == nil {
+		f.ctx = evalContextPool.Get().(*evalContext)
+	}
+	f.ctx.ctx, f.ctx.cancel = context.WithCancel(ctx)
+	f.ctx.interrupt = ctx.Done()
+	f.ctx.interruptCheckFrequency = interruptCheckFrequency
+	f.ctx.interruptCheckCount.Store(0)
+	f.ctx.interrupted.Store(false)
+}
+
+// Close releases the resources held by the execution frame and returns it to the pool.
+func (f *ExecutionFrame) Close() {
+	if f.ctx != nil {
+		if f.ctx.cancel != nil {
+			f.ctx.cancel()
+			f.ctx.cancel = nil
+		}
+		f.ctx.ctx = nil
+		f.ctx.interrupt = nil
+		f.ctx.state = nil
+		f.ctx.costs = nil
+		f.ctx.interrupted.Store(false)
+		f.ctx.interruptCheckCount.Store(0)
+		f.ctx.interruptCheckFrequency = 0
+		evalContextPool.Put(f.ctx)
+		f.ctx = nil
+	}
+	f.parent = nil
+	activationStack.release(f.Activation)
+	f.Activation = nil
+	frameStack.Put(f)
+}
+
+// push pushes the given activation onto the activation stack and returns the new frame.
+//
+// This operation is internal to the interpreter and is used to handle comprehension
+// scoping. The child frame inherits the shared evalContext from the parent.
+func (f *ExecutionFrame) push(activation Activation) *ExecutionFrame {
+	child := frameStack.Get().(*ExecutionFrame)
+	child.parent = f
+	child.ctx = f.ctx
+	child.Activation = activationStack.create(f.Activation, activation)
+	return child
+}
+
+// pop returns the parent frame, releasing the current frame back to the pool.
+func (f *ExecutionFrame) pop() *ExecutionFrame {
+	parent := f.parent
+	activationStack.release(f.Activation)
+	f.Activation = nil
+	f.parent = nil
+	f.ctx = nil
+	frameStack.Put(f)
+	return parent
+}
+
+// ResolveName implements the Activation interface by proxying to the internal activation.
+func (f *ExecutionFrame) ResolveName(name string) (any, bool) {
+	return f.Activation.ResolveName(name)
+}
+
+// Parent implements the Activation interface by proxying to the internal activation.
+func (f *ExecutionFrame) Parent() Activation {
+	return f.Activation.Parent()
+}
+
+// AsPartialActivation implements the PartialActivation interface by proxying to the internal activation.
+func (f *ExecutionFrame) AsPartialActivation() (PartialActivation, bool) {
+	return AsPartialActivation(f.Activation)
+}
+
+// Unwrap returns the internal activation.
+func (f *ExecutionFrame) Unwrap() Activation {
+	return f.Activation
+}
+
+// CheckInterrupt returns whether the evaluation has been interrupted.
+func (f *ExecutionFrame) CheckInterrupt() bool {
+	if f.ctx == nil {
+		return false
+	}
+	if f.ctx.interrupted.Load() {
+		return true
+	}
+	count := f.ctx.interruptCheckCount.Add(1)
+	if f.ctx.interruptCheckFrequency > 0 && count%uint64(f.ctx.interruptCheckFrequency) == 0 {
+		select {
+		case <-f.ctx.interrupt:
+			f.ctx.interrupted.Store(true)
+			return true
+		default:
+			return false
+		}
+	}
+	return false
+}
+
+// frameStack provides a synchronized pool of ExecutionFrames.
+var frameStack = &sync.Pool{
+	New: func() any {
+		return &ExecutionFrame{}
+	},
+}
+
+// evalContextPool provides a synchronized pool of evalContexts.
+var evalContextPool = &sync.Pool{
+	New: func() any {
+		return &evalContext{}
+	},
+}
+
+type activationStackPool struct {
+	sync.Pool
+}
+
+func (pool *activationStackPool) create(parent, child Activation) Activation {
+	h := pool.Get().(*hierarchicalActivation)
+	h.child = child
+	h.parent = parent
+	return h
+}
+
+func (pool *activationStackPool) release(activation Activation) {
+	h, ok := activation.(*hierarchicalActivation)
+	if !ok {
+		return
+	}
+	h.parent = nil
+	h.child = nil
+	pool.Pool.Put(h)
+}
+
+func newActivationPool() *activationStackPool {
+	return &activationStackPool{
+		Pool: sync.Pool{
+			New: func() any {
+				return &hierarchicalActivation{}
+			},
+		},
+	}
+}
+
+var (
+	activationStack           = newActivationPool()
+)