35 Symbol Table
A symbol table is a scoped mapping from symbol names to operations. It is provided by operations with the SymbolTable trait, most notably modules. The table is the authoritative mechanism for resolving names such as @function or @global in MLIR IR.
35.1 Lookup Is Scoped, Not Textual
A symbol reference is resolved relative to the nearest appropriate enclosing symbol table. Nested symbol tables introduce additional scope, and a nested reference can name a path through them. This is why a printed name is not enough to identify an operation globally.
Use SymbolTable and SymbolTableCollection APIs for lookup, insertion, erasure, and unique-name generation. They understand the IR’s ownership and scoping rules. A rewrite that renames an operation by changing its attribute directly can leave references dangling or create a collision that is only discovered much later in lowering.
35.2 Mutation Requires Use Awareness
Inserting a symbol must avoid name collisions in the destination table. Erasing one requires proving that no reachable uses remain, or deliberately updating them. Moving a symbol across tables changes the resolution context of every reference it contains and every reference to it.
Consider moving a private helper from a module into a nested device module. A flat reference from the old module may no longer find it; calls may need nested references, an import-like bridge, or duplication. Symbol-table correctness is therefore part of the transformation, not cleanup after it.
35.3 Symbol Tables And Parallelism
Symbols are a key reason isolated regions can be processed independently. A pass can resolve local symbol references without depending on arbitrary SSA values outside the scope. Interprocedural analyses still need to model edges between symbols, but the representation is explicit and serializable.