Struct CompileContext 

pub struct CompileContext { /* private fields */ }

The main compilation context. Orchestrates the full pipeline: BlockGraph -> Bloq.

Compiled circuit templates live in the context’s cache shard, which new keeps private and with_shared_cache shares with other contexts — see SharedCompileCache.

Implementations

impl CompileContext

pub fn new(config: CompileConfig) -> Self

Creates a context with a private template cache. Templates it compiles are reused by its own later compilations and by nothing else.

pub fn with_shared_cache( config: CompileConfig, cache: &SharedCompileCache, ) -> Self

Creates a context backed by cache, so it reuses (and contributes) templates compiled by every other context sharing that cache at this CompileConfig. Contexts sharing a cache may compile concurrently.

Sharing does not change compiled output: see SharedCompileCache.

pub fn config(&self) -> CompileConfig

The configuration this context compiles at.

Front ends that display or re-derive a context’s settings read them here instead of keeping their own copy of what was passed to new.

pub fn with_progress_observer( self, observer: impl Fn(CompileStage) + Send + Sync + 'static, ) -> Self

Observe stage starts for compilations made with this context. The default context emits no events. Retries may repeat stages; these events are not a completion fraction. The callback runs synchronously and should stay cheap. Concurrent calls on one context may interleave.

pub fn with_cancellation(self, token: CancellationToken) -> Self

Makes this context’s compilations cooperatively cancellable.

Cancellation is scoped to this context’s request, including native module workers. Checks occur at stage, template, and normalization boundaries; no partial artifact is returned. Cached complete templates remain reusable. Use a new token for a later request.

pub fn summarize( &self, program: &BlockGraph, limits: ModuleCertificationLimits, ) -> Result<Arc<ModuleSummary>, ModuleCertificationError>

Certifies and summarizes a module hierarchy, reusing this context’s logical cache independently of physical compile configuration.

Errors

Returns module validation, resource-limit, or certification errors.

pub fn summarize_with_jobs( &self, program: &BlockGraph, limits: ModuleCertificationLimits, jobs: NonZeroUsize, ) -> Result<Arc<ModuleSummary>, ModuleCertificationError>

summarize with an explicit native module-worker limit. WebAssembly remains serial.

Errors

Returns module validation, resource-limit, or certification errors.

pub fn compile_object( &self, program: &BlockGraph, ) -> Result<CompiledObject, CompileError>

Compile a target-specific block-graph object for repeated linking. Both fixed and symbolic inputs cache their finished IR. Exact definition variants remain reusable across different root programs.

Errors

Returns CompileError when module validation, certification, or lowering fails.

pub fn link_object( &self, object: &CompiledObject, ) -> Result<CompileArtifacts, CompileError>

Link a compiled object to an independently editable Bloq snapshot.

Errors

Returns a target mismatch. Compilation errors are reported when building the object.

pub fn compile_and_validate( &self, graph: &BlockGraph, ) -> Result<CompileArtifacts, CompileError>

Compile graph, then explicitly audit the resulting Bloq IR. The audit inherits this context’s Boolean limits; its other resource limits retain the IR validator’s defaults.

Errors

Returns a compilation or full IR validation error.

Examples

use bloq_compile::{CompileConfig, CompileContext};
use bloq_graph::GalleryItem;

let context = CompileContext::new(CompileConfig::default());
let artifacts = context.compile_and_validate(&GalleryItem::CNOT.build())?;
assert!(artifacts.bloq.quantum_node_count() > 0);

pub fn compile( &self, graph: &BlockGraph, ) -> Result<CompileArtifacts, CompileError>

Compile a block graph, including its module hierarchy, into Bloq IR.

Takes &self: the template cache is internally synchronized, so contexts sharing a SharedCompileCache may compile concurrently from &-borrows.

Errors

Any structural, per-block, or lowering failure graph provokes under this context’s CompileConfig.

Trait Implementations

impl Debug for CompileContext

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

Formats the value using the given formatter.