Struct ExecutionContext 

pub struct ExecutionContext { /* private fields */ }

Immutable execution configuration shared by native query execution.

The context owns or shares the cudf::Runtime used for all device work in a query. The runtime determines the CUDA device, stream, and memory resource; the query engine layers its own chunk-planning, reservation, retry, and boundary policies on top of that runtime. Cloning the context is cheap and keeps the same runtime/cache handles.

Implementations

impl ExecutionContext

pub fn validate_admitted_plan_capabilities( &self, plan: &QueryPlan, ) -> Result<()>

Universal pre-GPU gate for service-created execution contexts. Direct contexts remain unrestricted and return success without evidence.

pub fn with_admitted_gpu_inputs( &self, plan: &QueryPlan, gpu_inputs: &GpuResidentInputMap, ) -> Result<Self>

Activates the deferred-resident phase for plan from its exact materialized resident inputs.

Expected producer, occurrence, and schema identities come from the admitted compiled binding. Runtime frame identities are recorded only after those independent facts have matched.

pub fn validate_admitted_composed_attempt( &self, consumer_plan: &QueryPlan, occurrence_ids: &[String], ) -> Result<Option<AttemptComposedScheduleProjection>>

Validates one composed attempt against its admitted capability and resident-input identity contracts. Physical allocation remains owned by the immutable grant and live resident handles.

impl ExecutionContext

pub fn service_stream_pool(&self) -> QueryServiceStreamPool

Returns the service-level CUDA stream pool used by source-read workers.

The pool is wrapped with this context’s service epoch and query anchor, so a lease taken through it is revoked with the attempt and keeps the service from reaching idle. A standalone context wraps neither.

pub fn lakehouse_cache_fill_acquire_timeout(&self) -> Duration

Timeout used by blocking lakehouse cache maintenance resource acquisition.

pub fn lakehouse_cache_fill_budget(&self) -> CacheFillByteBudget

Returns the service-wide background lakehouse cache-fill byte budget.

impl ExecutionContext

pub fn runtime(&self) -> Result<CudfRuntime>

Returns the cudf runtime used for all GPU operations.

pub fn acquire_io_lease( &self, operation: &'static str, ) -> Result<Option<IoLifecycleLease>>

Acquire permission for one file-backed native I/O call.

Standalone library contexts without a server lifecycle remain unrestricted. Server contexts carry one generation gate and reject acquisitions after graceful shutdown begins.

pub fn with_io_lifecycle(self, lifecycle: IoLifecycle) -> Self

Attach a server-generation I/O lifecycle to this context clone.

pub fn shared_runtime(&self) -> Result<Arc<CudfRuntime>>

Returns a shared handle to the runtime.

The caller receives the same runtime object. A new runtime with copied configuration is not created.

pub fn gpu_executor(&self) -> Result<GpuExecutorLease>

Returns an opaque lifecycle-bound executor for synchronous GPU work on this context’s device.

The lease’s query-execution job follows this context’s own claim on the attempt: a root context runs it as root-class work, while an auxiliary fragment context, which is a second native island of the same attempt, runs it as auxiliary work backed by the attempt auxiliary permit that context already holds. Root capacity is one job per admitted attempt, so a second island charging it would fail where it has a reserved auxiliary slot of its own.

pub fn query_id(&self) -> Option<&QueryId>

Returns the query-wide diagnostic correlation id.

pub fn trace_id(&self) -> Option<&TraceId>

Returns the optional parent trace id.

pub fn runtime_observation(&self) -> &RuntimeObservationHandle

Returns the shared recording handle without terminal-seal authority.

pub fn runtime_execution_scope( &self, ) -> Option<&RuntimeExecutionObservationScope>

Returns the active native plan-execution scope.

pub fn with_runtime_gpu_stream_scope( &self, scope: RuntimeStreamLeaseScope, ) -> Self

Returns a clone carrying explicit GPU job/worker correlation.

pub fn with_query_id(&self, query_id: impl Into<QueryId>) -> Result<Self>

Returns a cloned context with a diagnostic query id consistent with observation identity.

pub fn with_trace_id(&self, trace_id: impl Into<TraceId>) -> Result<Self>

Returns a cloned context with a trace id consistent with observation identity.

pub fn is_query_service_admitted(&self) -> bool

Returns whether this context is backed by a QueryService admission slot.

pub fn cancellation(&self) -> &ExecutionCancellation

Returns the cooperative cancellation flag for this execution.

pub fn check_cancellation(&self, operation: &'static str) -> Result<()>

Fails with a structured cancellation error if the execution was cancelled.

The service epoch, the query epoch, and the cancellation token are checked in that order. All three fail with QueryErrorCode::Cancelled; the reason fact names the closed epoch or the elapsed deadline, and a caller cancellation carries none.

pub fn device(&self) -> DeviceId

CUDA device that runs this context’s work.

pub fn memory_control_policy(&self) -> MemoryControlPolicy

Returns the engine-level memory control policy.

pub fn memory_grant(&self) -> Result<Option<MemoryGrant>>

Returns the soft governor grant carried by this context, when present.

The clone is bound to this context’s resource epoch. Resident owner leases derived from it keep only the service generation (see QueryServiceResourceEpoch::service_generation_only), because frozen residents outlive the attempt.

pub fn execution_budget_token( &self, request: ExecutionBudgetRequest, ) -> Result<ExecutionBudgetToken>

Shares this stream’s member for a budgeted execution stage.

The stage request cannot change the immutable query-domain cap.

pub fn attempt_allocation_domain_id(&self) -> Option<u64>

Returns the immutable domain id for this admitted attempt.

pub fn attempt_allocation_domain_usage( &self, ) -> Result<Option<QueryMemoryDomainUsage>>

Samples the allocation-domain current and peak usage.

pub fn device_budget_bytes(&self) -> u64

Returns the device budget used by reservation tracking.

pub fn source_scheduler_policy(&self) -> SourceSchedulerPolicy

Returns source scheduling controls for bounded source execution.

pub fn source_chunk_planning_mode(&self) -> SourceChunkPlanningMode

Returns the source chunk planning mode.

pub fn statistical_aggregate_execution_mode( &self, ) -> StatisticalAggregateExecutionMode

Returns the selected execution contract for floating statistical aggregates.

pub fn datafusion_order_tracking(&self) -> bool

Returns whether this query preserves DataFusion input order for floating statistical aggregates.

Native execution derives this per query from the aggregate execution mode and the plan shape, then carries it on every context clone so source-read workers on spawned threads observe the same scope as the caller thread.

pub fn with_datafusion_order_tracking(self, enabled: bool) -> Self

Attaches the per-query DataFusion exact-order scope to this context clone.

pub fn aggregate_strategy_execution_options( &self, ) -> AggregateStrategyExecutionOptions

Returns grouped aggregate strategy execution policy.

pub fn planning_policy(&self) -> PlanningPolicy

Join and dynamic-filter thresholds a plan executed without an admission artifact is admitted under.

pub fn source_chunk_planning_options(&self) -> SourceChunkPlanningOptions

Returns expert local-throughput source chunk planning policy.

Trait Implementations

impl Clone for ExecutionContext

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ExecutionContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.