|
7 | 7 | // static single-assignment (SSA) form intermediate representation |
8 | 8 | // (IR) for the bodies of functions. |
9 | 9 | // |
10 | | -// THIS INTERFACE IS EXPERIMENTAL AND IS LIKELY TO CHANGE. |
11 | | -// |
12 | 10 | // For an introduction to SSA form, see |
13 | 11 | // http://en.wikipedia.org/wiki/Static_single_assignment_form. |
14 | 12 | // This page provides a broader reading list: |
|
21 | 19 | // All looping, branching and switching constructs are replaced with |
22 | 20 | // unstructured control flow. Higher-level control flow constructs |
23 | 21 | // such as multi-way branch can be reconstructed as needed; see |
24 | | -// ssautil.Switches() for an example. |
| 22 | +// [golang.org/x/tools/go/ssa/ssautil.Switches] for an example. |
25 | 23 | // |
26 | 24 | // The simplest way to create the SSA representation of a package is |
27 | | -// to load typed syntax trees using golang.org/x/tools/go/packages, then |
28 | | -// invoke the ssautil.Packages helper function. See Example_loadPackages |
29 | | -// and Example_loadWholeProgram for examples. |
30 | | -// The resulting ssa.Program contains all the packages and their |
| 25 | +// to load typed syntax trees using [golang.org/x/tools/go/packages], then |
| 26 | +// invoke the [golang.org/x/tools/go/ssa/ssautil.Packages] helper function. |
| 27 | +// (See the package-level Examples named LoadPackages and LoadWholeProgram.) |
| 28 | +// The resulting [ssa.Program] contains all the packages and their |
31 | 29 | // members, but SSA code is not created for function bodies until a |
32 | | -// subsequent call to (*Package).Build or (*Program).Build. |
| 30 | +// subsequent call to [Package.Build] or [Program.Build]. |
33 | 31 | // |
34 | 32 | // The builder initially builds a naive SSA form in which all local |
35 | 33 | // variables are addresses of stack locations with explicit loads and |
|
41 | 39 | // |
42 | 40 | // The primary interfaces of this package are: |
43 | 41 | // |
44 | | -// - Member: a named member of a Go package. |
45 | | -// - Value: an expression that yields a value. |
46 | | -// - Instruction: a statement that consumes values and performs computation. |
47 | | -// - Node: a Value or Instruction (emphasizing its membership in the SSA value graph) |
| 42 | +// - [Member]: a named member of a Go package. |
| 43 | +// - [Value]: an expression that yields a value. |
| 44 | +// - [Instruction]: a statement that consumes values and performs computation. |
| 45 | +// - [Node]: a [Value] or [Instruction] (emphasizing its membership in the SSA value graph) |
48 | 46 | // |
49 | | -// A computation that yields a result implements both the Value and |
50 | | -// Instruction interfaces. The following table shows for each |
| 47 | +// A computation that yields a result implements both the [Value] and |
| 48 | +// [Instruction] interfaces. The following table shows for each |
51 | 49 | // concrete type which of these interfaces it implements. |
52 | 50 | // |
53 | 51 | // Value? Instruction? Member? |
|
97 | 95 | // *TypeAssert ✔ ✔ |
98 | 96 | // *UnOp ✔ ✔ |
99 | 97 | // |
100 | | -// Other key types in this package include: Program, Package, Function |
101 | | -// and BasicBlock. |
| 98 | +// Other key types in this package include: [Program], [Package], [Function] |
| 99 | +// and [BasicBlock]. |
102 | 100 | // |
103 | 101 | // The program representation constructed by this package is fully |
104 | 102 | // resolved internally, i.e. it does not rely on the names of Values, |
105 | 103 | // Packages, Functions, Types or BasicBlocks for the correct |
106 | 104 | // interpretation of the program. Only the identities of objects and |
107 | 105 | // the topology of the SSA and type graphs are semantically |
108 | | -// significant. (There is one exception: Ids, used to identify field |
| 106 | +// significant. (There is one exception: [types.Id] values, which identify field |
109 | 107 | // and method names, contain strings.) Avoidance of name-based |
110 | 108 | // operations simplifies the implementation of subsequent passes and |
111 | 109 | // can make them very efficient. Many objects are nonetheless named |
112 | 110 | // to aid in debugging, but it is not essential that the names be |
113 | 111 | // either accurate or unambiguous. The public API exposes a number of |
114 | 112 | // name-based maps for client convenience. |
115 | 113 | // |
116 | | -// The ssa/ssautil package provides various utilities that depend only |
117 | | -// on the public API of this package. |
| 114 | +// The [golang.org/x/tools/go/ssa/ssautil] package provides various |
| 115 | +// helper functions, for example to simplify loading a Go program into |
| 116 | +// SSA form. |
118 | 117 | // |
119 | 118 | // TODO(adonovan): write a how-to document for all the various cases |
120 | 119 | // of trying to determine corresponding elements across the four |
|
0 commit comments