Struct SymbolRegistry 

pub struct SymbolRegistry { /* private fields */ }

Central registry for symbol management

Single Point of Access

All symbol operations must go through SymbolRegistry.

• Get SymbolId: register() or lookup()
• Get/update metadata: kind(), span(), set_span(), etc.
• Graph operations also use SymbolId

Responsibilities

• Bidirectional SymbolPath ↔ SymbolId conversion
• Metadata management (Kind, Span, Visibility, etc.)
• Symbol lifecycle management

Thread Safety

• Read operations are thread-safe
• Write operations require exclusive access (Executor controls this at Tick boundaries)

Implementations

impl SymbolRegistry

pub fn new() -> SymbolRegistry

Create a new empty registry

pub fn with_capacity(capacity: usize) -> SymbolRegistry

Create with pre-allocated capacity

pub fn register( &mut self, path: SymbolPath, kind: SymbolKind, ) -> Result<SymbolId, RegistrationError>

Register a symbol (returns existing ID if already registered)

Returns

• Ok(SymbolId): Registration successful (new or existing)
• Err(RegistrationError): Registration failed

pub fn register_with_metadata( &mut self, path: SymbolPath, kind: SymbolKind, span: Option<FileSpan>, vis: Option<Visibility>, ) -> Result<SymbolId, RegistrationError>

Register with full metadata

pub fn register_var( &mut self, containing_symbol: SymbolId, scope: VarScope, name: &str, kind: SymbolKind, ) -> Result<SymbolId, RegistrationError>

Register a variable (InSymbol)

Creates a path like parent::$scope::name and registers it.

Arguments

• containing_symbol: Parent symbol (function/method/struct)
• scope: Variable scope type
• name: Variable name
• kind: Symbol kind (Variable, Parameter, or Field)

pub fn lookup(&self, path: &SymbolPath) -> Option<SymbolId>

SymbolPath → SymbolId (O(1) hash lookup)

Also resolves re-export aliases to their canonical ID.

pub fn resolve(&self, id: SymbolId) -> Option<&SymbolPath>

SymbolId → SymbolPath (O(1) array access)

pub fn path(&self, id: SymbolId) -> Option<&SymbolPath>

Alias for resolve() - get path from ID

pub fn get_ref(&self, id: SymbolId) -> Option<SymbolRef>

Get SymbolRef (ID + Path) for unified display

Format

Returns SymbolRef which displays as: SymbolId(2v1)@path::to::symbol

Example

let sym_ref = registry.get_ref(id)?;
println!("{}", sym_ref);  // SymbolId(2v1)@my_crate::MyStruct

pub fn contains(&self, id: SymbolId) -> bool

Check if SymbolId is valid (with generation check)

pub fn kind(&self, id: SymbolId) -> Option<SymbolKind>

Get kind

pub fn span(&self, id: SymbolId) -> Option<&FileSpan>

Get span

pub fn visibility(&self, id: SymbolId) -> Option<&Visibility>

Get visibility

pub fn parent(&self, id: SymbolId) -> Option<SymbolId>

Get parent symbol (for InSymbol)

pub fn set_span( &mut self, id: SymbolId, span: FileSpan, ) -> Result<(), InvalidSymbolId>

Set/update span

pub fn set_visibility( &mut self, id: SymbolId, vis: Visibility, ) -> Result<(), InvalidSymbolId>

Set/update visibility

pub fn set_kind( &mut self, id: SymbolId, kind: SymbolKind, ) -> Result<(), InvalidSymbolId>

Set/update kind

pub fn remove(&mut self, id: SymbolId) -> Option<SymbolPath>

Remove a symbol from the registry

Returns the path of the removed symbol, or None if the ID was invalid. Also removes the persistent UUID mapping if present.

pub fn rename( &mut self, id: SymbolId, new_path: SymbolPath, ) -> Result<SymbolPath, RenameError>

Rename a symbol

Returns the old path on success.

pub fn find_by_name(&self, name: &str) -> Vec<SymbolId>

Find all symbols with the given name (last segment of path).

Also includes canonical symbols that have re-export aliases matching the name.

pub fn lookup_by_name(&self, name: &str) -> Option<SymbolId>

Find a single symbol by name (returns first match)

pub fn register_reexport( &mut self, canonical_id: SymbolId, alias_path: SymbolPath, origin_file: WorkspaceFilePath, ) -> Result<(), InvalidSymbolId>

Register a re-export

pub fn unregister_reexport( &mut self, alias_path: &SymbolPath, ) -> Result<(), UnregisterReexportError>

Unregister a re-export

pub fn re_exports(&self, id: SymbolId) -> Option<&[ReExportInfo]>

Get re-exports for a symbol

pub fn register_persistent( &mut self, path: SymbolPath, kind: SymbolKind, uuid: Option<Uuid>, ) -> Result<(SymbolId, Uuid), RegistrationError>

Register a symbol with persistent UUID

This method assigns a stable UUID to the symbol that survives across sessions. Use this for symbols that need to be tracked through renames or serialized.

Arguments

• path: Symbol path
• kind: Symbol kind
• uuid: Some(uuid) when restoring from serialized data, None to generate new

Returns

• Ok((SymbolId, Uuid)): The runtime ID and persistent UUID
• Err(RegistrationError): Registration failed

Example

// New symbol (generates UUID)
let (id, uuid) = registry.register_persistent(path, kind, None)?;

// Restore from serialized data
let (id, uuid) = registry.register_persistent(path, kind, Some(saved_uuid))?;

pub fn assign_uuid( &mut self, id: SymbolId, uuid: Option<Uuid>, ) -> Result<Uuid, InvalidSymbolId>

Assign a persistent UUID to an existing symbol

Use this to add persistence to a symbol that was registered without UUID.

Returns

• Ok(Uuid): The assigned UUID (existing or new)
• Err(InvalidSymbolId): Symbol doesn’t exist

pub fn uuid(&self, id: SymbolId) -> Option<Uuid>

Get persistent UUID for a symbol (O(1))

Returns None if the symbol was not registered with persistence.

pub fn lookup_by_uuid(&self, uuid: Uuid) -> Option<SymbolId>

Lookup symbol by persistent UUID (O(1))

Use this when deserializing references from saved data.

pub fn has_uuid(&self, id: SymbolId) -> bool

Check if a symbol has a persistent UUID

pub fn iter_persistent(&self) -> impl Iterator<Item = (SymbolId, Uuid)>

Get all symbols with persistent UUIDs

pub fn persistent_count(&self) -> usize

Get count of symbols with persistent UUIDs

pub fn preload_uuid_mapping(&mut self, mappings: HashMap<SymbolPath, Uuid>)

Preload UUID mappings from a previous session.

Call this before registering symbols to restore persistent UUIDs. When register() is called, it will use preloaded UUIDs instead of generating new ones.

Arguments

• mappings - HashMap of SymbolPath → UUID from previous session

Example

// Load from file
let mappings: HashMap<SymbolPath, Uuid> = load_from_file(path)?;
registry.preload_uuid_mapping(mappings);

// Now register symbols - they'll get their previous UUIDs
registry.register(path, kind)?;

pub fn export_uuid_mapping(&self) -> HashMap<SymbolPath, Uuid>

Export current UUID mappings for persistence.

Returns a HashMap of SymbolPath → UUID that can be serialized and loaded in a future session via preload_uuid_mapping().

Example

// Save to file
let mappings = registry.export_uuid_mapping();
save_to_file(path, &mappings)?;

pub fn export_uuid_mapping_strings(&self) -> HashMap<String, String>

Export UUID mappings as strings for JSON serialization.

Converts SymbolPath and Uuid to String for easy JSON storage.

pub fn preload_uuid_mapping_strings( &mut self, mappings: HashMap<String, String>, )

Preload UUID mappings from string format (for JSON deserialization).

Parses string keys/values back to SymbolPath/Uuid. Invalid entries are silently skipped.

pub fn iter(&self) -> impl Iterator<Item = (SymbolId, &SymbolPath)>

Iterate over all symbols

pub fn iter_by_kind(&self, kind: SymbolKind) -> impl Iterator<Item = SymbolId>

Iterate over symbols of a specific kind

pub fn iter_in_crate<'a>( &'a self, crate_name: &'a str, ) -> impl Iterator<Item = SymbolId> + 'a

Iterate over symbols in a specific crate

pub fn len(&self) -> usize

Get number of registered symbols

pub fn is_empty(&self) -> bool

Check if registry is empty

pub fn memory_stats(&self) -> MemoryStats

Get memory usage statistics

Trait Implementations

impl Clone for SymbolRegistry

fn clone(&self) -> SymbolRegistry

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for SymbolRegistry

fn default() -> SymbolRegistry

Returns the “default value” for a type.