Trait CppSource 

pub trait CppSource:
    CodeUnitIndex
    + TypeAliasProvider
    + TypeHierarchyProvider
    + CppWorkspaceSource {
    // Required methods
    fn stored_callable_unit_role(
        &self,
        callable: &CodeUnit,
    ) -> CppCallableUnitRole;
    fn include_target_index(&self) -> &IncludeTargetIndex;
    fn visible_type_units(&self, file: &ProjectFile) -> Arc<Vec<CodeUnit>> ;
    fn visible_type_units_while(
        &self,
        file: &ProjectFile,
        keep_going: &dyn Fn() -> bool,
    ) -> Option<Arc<Vec<CodeUnit>>>;
    fn source_using_index(
        &self,
        token: QueryToken<'_>,
        file: &ProjectFile,
    ) -> Arc<SourceUsingIndex> ;
    fn file_source(&self, file: &ProjectFile) -> Option<String>;
    fn prepared_syntax(
        &self,
        token: QueryToken<'_>,
        file: &ProjectFile,
    ) -> Option<Arc<PreparedSyntaxTree>>;
    fn cpp_field_linkage(&self, code_unit: &CodeUnit) -> Option<CppFieldLinkage>;
    fn cached_unconditional_include_reachability(
        &self,
        first: &ProjectFile,
        donor_source: &ProjectFile,
        reference_is_c: bool,
    ) -> Option<bool>;
    fn cache_unconditional_include_reachability(
        &self,
        first: &ProjectFile,
        donor_source: &ProjectFile,
        reference_is_c: bool,
        reaches: bool,
    );
    fn recovered_export_class_index(
        &self,
        token: QueryToken<'_>,
        file: &ProjectFile,
    ) -> Arc<CppRecoveredExportClassIndex> ;
    fn orphaned_namespace_scopes(
        &self,
        token: QueryToken<'_>,
        file: &ProjectFile,
    ) -> Arc<OrphanedNamespaceScopeIndex> ;
    fn cached_class_declaration_strength(
        &self,
        candidate: &CodeUnit,
    ) -> Option<CppClassDeclarationStrength>;
    fn cache_class_declaration_strength(
        &self,
        candidate: &CodeUnit,
        strength: CppClassDeclarationStrength,
    );
    fn structural_parent_of(&self, code_unit: &CodeUnit) -> Option<CodeUnit>;
    fn template_metadata(
        &self,
        code_unit: &CodeUnit,
    ) -> Option<CppTemplateMetadata>;
    fn header_uses_c_semantics(&self, file: &ProjectFile) -> bool;
    fn declarations_in_reading(
        &self,
        file: &ProjectFile,
        c_semantics: bool,
    ) -> BTreeSet<CodeUnit>;
    fn site_equivalent_units(&self, code_unit: &CodeUnit) -> Vec<CodeUnit>;
    fn compile_contexts_for(&self, file: &ProjectFile) -> &[CppCompileContext];

    // Provided methods
    fn declaration_source_facts(
        &self,
        _token: QueryToken<'_>,
        _file: &ProjectFile,
    ) -> Option<Arc<CppFileSourceFacts>> { ... }
    fn canonical_include_facts(
        &self,
        token: QueryToken<'_>,
        file: &ProjectFile,
    ) -> Option<Vec<CppIncludeFact>> { ... }
    fn canonical_include_paths(
        &self,
        token: QueryToken<'_>,
        file: &ProjectFile,
    ) -> Option<Vec<String>> { ... }
    fn declaration_source_properties(
        &self,
        token: QueryToken<'_>,
        unit: &CodeUnit,
    ) -> Option<Vec<CppDeclarationSourceFact>> { ... }
    fn declaration_source_occurrences(
        &self,
        token: QueryToken<'_>,
        unit: &CodeUnit,
    ) -> Option<Vec<CppDeclarationOccurrence>> { ... }
    fn declaration_navigation_occurrences(
        &self,
        token: QueryToken<'_>,
        unit: &CodeUnit,
    ) -> Option<Vec<CppNavigationOccurrence>> { ... }
    fn visibility_import_statements(
        &self,
        token: QueryToken<'_>,
        file: &ProjectFile,
    ) -> Vec<String> { ... }
    fn visibility_identifier_candidates(
        &self,
        identifier: &str,
    ) -> BTreeSet<CodeUnit> { ... }
    fn visibility_identifier_candidates_batch(
        &self,
        identifiers: &HashSet<String>,
        cancellation: Option<&CancellationToken>,
    ) -> HashMap<String, BTreeSet<CodeUnit>> { ... }
    fn reaching_translation_units(
        &self,
        _file: &ProjectFile,
    ) -> Vec<ProjectFile> { ... }
}

Required Methods

fn stored_callable_unit_role(&self, callable: &CodeUnit) -> CppCallableUnitRole

The callable role recorded for a physical stored declaration, without consulting reconciliation fallbacks that may themselves be building.

fn include_target_index(&self) -> &IncludeTargetIndex

The workspace-wide #include resolution table, built once per analyzer generation from IncludeTargetIndex::build.

fn visible_type_units(&self, file: &ProjectFile) -> Arc<Vec<CodeUnit>>

Every class-like or alias declaration reachable from file through its #include closure, memoized per file. See this module’s note.

fn visible_type_units_while( &self, file: &ProjectFile, keep_going: &dyn Fn() -> bool, ) -> Option<Arc<Vec<CodeUnit>>>

Self::visible_type_units under a caller’s deadline.

None means the include-closure walk stopped short. Nothing is memoized in that case: a truncated class table is indistinguishable from a file that simply sees fewer types, so every later base-specifier resolution reading it would silently lose ancestors.

This is the shape issue #1748 needed. The closure walk is individually cheap – a fraction of a millisecond to about 180 ms – but the descendant-index build above it runs one per class in the workspace, which on a large tree is tens of thousands of them inside a single request that asked for thirty seconds.

fn source_using_index( &self, token: QueryToken<'_>, file: &ProjectFile, ) -> Arc<SourceUsingIndex>

The per-file structured using index (ordinary using declarations and using-directives with their guard environments), memoized per file. Built by crate::graph::extractor::build_source_using_index, which is a pure function of the file’s parsed content.

Memoized on the analyzer rather than on VisibilityIndex because a fresh visibility index is built per usage query: rebuilding the index per query re-walked a 9.5 MB amalgamation’s AST once per candidate (issue #1927).

fn file_source(&self, file: &ProjectFile) -> Option<String>

The indexed source of file (TreeSitterAnalyzer::file_source).

fn prepared_syntax( &self, token: QueryToken<'_>, file: &ProjectFile, ) -> Option<Arc<PreparedSyntaxTree>>

The parsed tree and its source backing for file, from the analyzer’s query read cache.

The single hottest member of this trait: the usage graph reaches it at 27 call sites. The cache is not rebuilt per call – VisibilityIndex borrows the analyzer rather than cloning it precisely so this stays warm across a scan (#1175), so an implementor must forward to the same analyzer the query is running against.

The QueryToken is proof that a request scope is open, so the cache this reads is live (issue #2414 step 3).

fn cpp_field_linkage(&self, code_unit: &CodeUnit) -> Option<CppFieldLinkage>

The persisted linkage fact for one C++ field, when the parser recorded it. A missing fact is unavailable linkage evidence.

fn cached_unconditional_include_reachability( &self, first: &ProjectFile, donor_source: &ProjectFile, reference_is_c: bool, ) -> Option<bool>

The cached result of a preprocessor-visible include-reachability walk.

The reference language affects only __cplusplus guards. Callers pass that fact as a Boolean so cache keys do not retain the full reference path.

fn cache_unconditional_include_reachability( &self, first: &ProjectFile, donor_source: &ProjectFile, reference_is_c: bool, reaches: bool, )

Store a completed preprocessor-visible include-reachability walk.

fn recovered_export_class_index( &self, token: QueryToken<'_>, file: &ProjectFile, ) -> Arc<CppRecoveredExportClassIndex>

The file’s embedded export-macro class recovery, resolved once per file.

Built by crate::declarations::CppRecoveredExportClassIndex::build, which is a pure function of the file’s parsed content. Memoized on the analyzer for the same reason as Self::source_using_index: the declaration-strength question asks it once per class-like unit, and re-deriving it walks and sorts every ERROR subtree in the file (#1496).

fn orphaned_namespace_scopes( &self, token: QueryToken<'_>, file: &ProjectFile, ) -> Arc<OrphanedNamespaceScopeIndex>

The namespaces C++ parse recovery dropped from file’s tree, resolved once per file.

Built by OrphanedNamespaceScopeIndex::build, a pure function of the file’s parsed content, and empty for a file without parse errors. Both lookup directions derive every lexical scope in the file through it, so it is memoized on the analyzer like Self::source_using_index rather than rebuilt per query or per reference (issue #1537).

fn cached_class_declaration_strength( &self, candidate: &CodeUnit, ) -> Option<CppClassDeclarationStrength>

The memoized answer of crate::graph::resolver::cpp_class_declaration_strength for one class-like unit, when a previous ask stored it.

The answer is a pure function of the unit’s declaration ranges and its file’s parse tree, so it is stable for an analyzer generation. Memoized on the analyzer for the same reason as Self::source_using_index: the inverse scan asks it once per declaration seed, and on a translation unit the parser could not fully recover each ask re-derives the export-macro recovery shapes from the file’s ERROR subtrees, which is quadratic in the file’s size (#1496).

fn cache_class_declaration_strength( &self, candidate: &CodeUnit, strength: CppClassDeclarationStrength, )

Store a completed declaration-strength answer.

fn structural_parent_of(&self, code_unit: &CodeUnit) -> Option<CodeUnit>

The declaration’s syntactic owner, which unlike CodeUnitIndex::parent_of never falls back to a definition-row lookup.

fn template_metadata(&self, code_unit: &CodeUnit) -> Option<CppTemplateMetadata>

The persisted C++ template metadata side table’s row for code_unit.

fn header_uses_c_semantics(&self, file: &ProjectFile) -> bool

Whether a reference written in the header file reads the declarations it can see with C semantics: every workspace translation unit that provably compiles this header compiles it as C (issue #1970).

Always false for a translation unit – its own extension settles its dialect, which crate::graph::resolver::is_c_source_file answers without asking the analyzer. Both halves are combined by crate::graph::resolver::reference_uses_c_semantics, the one helper resolution asks.

A header both languages provably include reports false: forward resolution from it reports the C++ identity, and the site-equivalence union below is what keeps inverse in agreement.

fn declarations_in_reading( &self, file: &ProjectFile, c_semantics: bool, ) -> BTreeSet<CodeUnit>

The declarations of file as one of its two readings sees them.

c_semantics false is the C++ reading, which is exactly CodeUnitIndex::declarations. True is the C reading: the stored cpp:c row-set when the blob has one, and otherwise the same C++ row-set, because “no C rows” means the two readings agree.

Candidate enumeration selects a reading here and nowhere else: include activation, preprocessor-guard compatibility, block-scope shadowing and ambiguity all run unchanged over whichever set comes back.

fn site_equivalent_units(&self, code_unit: &CodeUnit) -> Vec<CodeUnit>

The identities of the other reading that share code_unit’s declaration site – the same source file and the same declaration byte range – empty when the two readings agree about it.

Keyed on the range, never on a name. Inverse results are unioned across these so a query against either identity of one declaration reports every reference found under both readings.

fn compile_contexts_for(&self, file: &ProjectFile) -> &[CppCompileContext]

Every distinct compile_commands.json configuration governing file, empty when the workspace has no compile database entry naming it. The only analyzer-resident product crate::diagnostics needs.

A file the build compiles in several configurations yields several contexts, because their include closures can disagree about a name.

Provided Methods

fn declaration_source_facts( &self, _token: QueryToken<'_>, _file: &ProjectFile, ) -> Option<Arc<CppFileSourceFacts>>

Canonical declaration syntax for the file’s primary compilation reading.

fn canonical_include_facts( &self, token: QueryToken<'_>, file: &ProjectFile, ) -> Option<Vec<CppIncludeFact>>

Canonical AST-owned include facts for the file’s primary reading. None means source-facts publication is unavailable; an empty vector is an authoritative include-free file.

fn canonical_include_paths( &self, token: QueryToken<'_>, file: &ProjectFile, ) -> Option<Vec<String>>

Canonical include paths for a file’s primary reading.

fn declaration_source_properties( &self, token: QueryToken<'_>, unit: &CodeUnit, ) -> Option<Vec<CppDeclarationSourceFact>>

Exact source alternatives for a mounted declaration. Unavailable source publication stays unknown; consumers must never reparse the candidate.

fn declaration_source_occurrences( &self, token: QueryToken<'_>, unit: &CodeUnit, ) -> Option<Vec<CppDeclarationOccurrence>>

fn declaration_navigation_occurrences( &self, token: QueryToken<'_>, unit: &CodeUnit, ) -> Option<Vec<CppNavigationOccurrence>>

Navigation alternatives come from the same canonical occurrences as declaration properties. An analyzer that selects alternate dialects must override this method to join against the selected dialect’s own arena.

fn visibility_import_statements( &self, token: QueryToken<'_>, file: &ProjectFile, ) -> Vec<String>

Structured includes for a disposable visibility traversal.

fn visibility_identifier_candidates( &self, identifier: &str, ) -> BTreeSet<CodeUnit>

Physical identifier candidates used only to discover source files for a bounded visibility traversal. Re-keyed out-of-line definitions do not add an includable source, so analyzer implementations may answer this from their stored declaration index without global identity reconciliation.

fn visibility_identifier_candidates_batch( &self, identifiers: &HashSet<String>, cancellation: Option<&CancellationToken>, ) -> HashMap<String, BTreeSet<CodeUnit>>

Batched form of Self::visibility_identifier_candidates.

fn reaching_translation_units(&self, _file: &ProjectFile) -> Vec<ProjectFile>

Every workspace translation unit whose #include closure transitively reaches file – the header-to-TU attribution map from #1970’s Milestone 2, which #2011 phase 2 reads for header-sited guard proof. Empty when nothing reaches file or the implementor has no include graph, which conservatively yields no compile-context facts.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors