1 # Symbols and Symbol Tables
17 constant values as well as `Symbol` accesses for global values and variables.
18 This document details the design of `Symbol`s, what they are and how they fit
21 The `Symbol` infrastructure essentially provides a non-SSA mechanism in which to
27 ## Symbol  section in Symbols and Symbol Tables
29 A `Symbol` is a named operation that resides immediately within a region that
30 defines a [`SymbolTable`](#symbol-table). The name of a symbol *must* be unique
33 link, or use, to the symbol. An example of a `Symbol` operation is
34 [`func`](LangRef.md#functions). `func` defines a symbol name, which is
35 [referred to](#referencing-a-symbol) by operations like
38 ### Defining or declaring a Symbol  argument
40 A `Symbol` operation should use the `SymbolOpInterface` interface to provide the
42 operations, such as `module`, that conditionally define a symbol. `Symbol`s must
50     -   This attribute defines the [visibility](#symbol-visibility) of the
51         symbol, or more specifically in-which scopes it may be accessed.
56     -   Declarations do not define a new symbol but reference a symbol defined
59 ## Symbol Table
61 Described above are `Symbol`s, which reside within a region of an operation
63 the [`Symbol`](#symbol) operations. It verifies that all `Symbol` operations
67 ### Referencing a Symbol
69 `Symbol`s are referenced symbolically by name via the
70 [`SymbolRefAttr`](LangRef.md#symbol-reference-attribute) attribute. A symbol
72 within a symbol table. It may optionally contain a set of nested references that
73 further resolve to a symbol nested within a different symbol table. When
74 resolving a nested reference, each non-leaf reference must refer to a symbol
75 operation that is also a [symbol table](#symbol-table).
77 Below is an example of how an operation can reference a symbol operation:
80 // This `func` operation defines a symbol named `symbol`.
81 func @symbol()
84 // `symbol` func.
85 "foo.user"() {uses = [@symbol]} : () -> ()
87 // Symbol references resolve to the nearest parent operation that defines a
88 // symbol table, so we can have references with arbitrary nesting levels.
91     // Our `foo.user` operation resolves to the same `symbol` func as defined
93     "foo.user"() {uses = [@symbol]} : () -> ()
98 // Here we define a nested symbol table. References within this operation will
102   // that defines a symbol table, so this reference can't be resolved.
103   "foo.user"() {uses = [@symbol]} : () -> ()
106 // Here we define another nested symbol table, except this time it also defines
107 // a symbol.
109   // This `func` operation defines a symbol named `nested_symbol`.
113 // Our `foo.user` operation may refer to the nested symbol, by resolving through
130     -   Attributes simplify referencing operations within nested symbol tables,
136 operations that materialize SSA values from a symbol reference. Each has
145 [`SymbolRefAttr`](LangRef.md#symbol-reference-attribute) for more information
148 Operations that reference a `Symbol` and want to perform verification and
149 general mutation of the symbol should implement the `SymbolUserOpInterface` to
150 ensure that symbol accesses are legal and efficient.
152 ### Manipulating a Symbol
166     -   Check if a particular symbol is known to be unused within a specific
171     -   Replace all of the uses of one symbol with a new one within a specific
176     -   Lookup the definition of a symbol in the nearest symbol table from some
179 ## Symbol Visibility
181 Along with a name, a `Symbol` also has a `visibility` attached to it. The
182 `visibility` of a symbol defines its structural reachability within the IR. A
183 symbol has one of the following visibilities:
187     -   The symbol may be referenced from outside of the visible IR. We cannot
188         assume that all of the uses of this symbol are observable. If the
189         operation declares a symbol (as opposed to defining it), public
190         visibility is not allowed because symbol declarations are not intended
195     -   The symbol may only be referenced from within the current symbol table.
199     -   The symbol may be referenced by operations outside of the current symbol
200         table, but not outside of the visible IR, as long as each symbol table
201         parent also defines a non-private symbol.