Skip to content

Commit 5759d42

Browse files
atrickatrick
committed
ForwardingUtils comment formatting.
Format comments so they are readable on github and 80-col tools.
1 parent a756d38 commit 5759d42

File tree

1 file changed

+72
-52
lines changed

1 file changed

+72
-52
lines changed

‎SwiftCompilerSources/Sources/Optimizer/Utilities/ForwardingUtils.swift

Lines changed: 72 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -26,54 +26,71 @@ func findPointerEscapingUse(of value: Value) -> Bool {
2626
value.bridged.findPointerEscape()
2727
}
2828

29-
// Visit the introducers of a forwarded lifetime (Value -> LifetimeIntroducer).
30-
//
31-
// A lifetime introducer produces an initial OSSA lifetime which may be extended by forwarding instructions. The introducer is never itself the result of a ForwardingInstruction. Example:
32-
//
33-
// # lifetime introducer
34-
// %1 = apply -+ -+
35-
// ... | OSSA lifetime |
36-
// # forwarding instruction | |
37-
// %2 = struct $S (%1) -+ -+ | forward-extended lifetime
38-
// | OSSA lifetime |
39-
// # non-forwarding consumer | |
40-
// destroy_value %2 -+ -+
41-
//
42-
// The lifetime of a single owned value ends when it is forwarded, but certain lifetime properties are relevant for the entire forward-extended lifetime. For example, if an owned lifetime has a pointer-escaping use, then all values in the forward-extended lifetime are also considered pointer-escaping. Certain propeties, like lexical lifetimes, only exist on the forward introducer and apply to all forwarded values.
43-
//
44-
// Note: Although move_value conceptually forwards an owned value, it also summarizes lifetime attributes; therefore, it is not formally a ForwardingInstruction.
45-
//
46-
// The lifetime introducer of a guaranteed value is the borrow introducer:
47-
//
48-
// # lifetime introducer / borrow introducer
49-
// %1 = begin_borrow -+
50-
// ... | OSSA lifetime == forwarded lifetime
51-
// # forwarding instruction |
52-
// %2 = struct $S (%1) | - forwarded uses are within the OSSA lifetime
53-
// |
54-
// end_borrow %1 -+
55-
//
56-
// TODO: When a begin_borrow has no lifetime flags, it can be ignored as a lifetime introducer. In that case, an owned value may introduce guaranteed OSSA lifetimes.
57-
//
58-
// Forwarded lifetimes also extend through phis. In this case, however, there is no ForwardingInstruction.
59-
//
60-
// # lifetime introducer
61-
// %1 = apply -+ -+
62-
// ... | OSSA lifetime |
63-
// # phi operand | |
64-
// br bbContinue(%1: $S) -+ | forward-extended lifetime
65-
// |
66-
// bbContinue(%phi : $S): -+ OSSA lifetime |
67-
// ... | |
68-
// destroy_value %phi -+ -+
69-
//
70-
// TODO: when phi lifetime flags are implemented, phis will introduce a lifetime in the same way as move_value.
71-
//
72-
// This walker is used to query basic lifetime attributes on values, such as "escaping" or "lexical". It must be precise for correctness and is performance critical.
29+
/// Visit the introducers of a forwarded lifetime (Value -> LifetimeIntroducer).
30+
///
31+
/// A lifetime introducer produces an initial OSSA lifetime which may
32+
/// be extended by forwarding instructions. The introducer is never
33+
/// itself the result of a ForwardingInstruction. Example:
34+
///
35+
/// # lifetime introducer
36+
/// %1 = apply -+ -+
37+
/// ... | OSSA lifetime |
38+
/// # forwarding instruction | |
39+
/// %2 = struct $S (%1) -+ -+ | forward-extended lifetime
40+
/// | OSSA lifetime |
41+
/// # non-forwarding consumer | |
42+
/// destroy_value %2 -+ -+
43+
///
44+
/// The lifetime of a single owned value ends when it is forwarded,
45+
/// but certain lifetime properties are relevant for the entire
46+
/// forward-extended lifetime. For example, if an owned lifetime has a
47+
/// pointer-escaping use, then all values in the forward-extended
48+
/// lifetime are also considered pointer-escaping. Certain properties,
49+
/// like lexical lifetimes, only exist on the forward introducer and
50+
/// apply to all forwarded values.
51+
///
52+
/// Note: Although move_value conceptually forwards an owned value, it
53+
/// also summarizes lifetime attributes; therefore, it is not formally
54+
/// a ForwardingInstruction.
55+
///
56+
/// The lifetime introducer of a guaranteed value is the borrow introducer:
57+
///
58+
/// # lifetime introducer / borrow introducer
59+
/// %1 = begin_borrow -+
60+
/// ... | OSSA lifetime == forwarded lifetime
61+
/// # forwarding instruction |
62+
/// %2 = struct $S (%1) | - forwarded uses are within the OSSA lifetime
63+
/// |
64+
/// end_borrow %1 -+
65+
///
66+
/// TODO: When a begin_borrow has no lifetime flags, it can be ignored
67+
/// as a lifetime introducer. In that case, an owned value may
68+
/// introduce guaranteed OSSA lifetimes.
69+
///
70+
/// Forwarded lifetimes also extend through phis. In this case,
71+
/// however, there is no ForwardingInstruction.
72+
///
73+
/// # lifetime introducer
74+
/// %1 = apply -+ -+
75+
/// ... | OSSA lifetime |
76+
/// # phi operand | |
77+
/// br bbContinue(%1: $S) -+ | forward-extended lifetime
78+
/// |
79+
/// bbContinue(%phi : $S): -+ OSSA lifetime |
80+
/// ... | |
81+
/// destroy_value %phi -+ -+
82+
///
83+
/// TODO: when phi lifetime flags are implemented, phis will introduce
84+
/// a lifetime in the same way as move_value.
85+
///
86+
/// This walker is used to query basic lifetime attributes on values,
87+
/// such as "escaping" or "lexical". It must be precise for
88+
/// correctness and is performance critical.
7389
protocol ForwardingUseDefWalker {
7490
mutating func introducer(_ value: Value) -> WalkResult
7591

76-
// Minimally, check a ValueSet. This walker may traverse chains of aggregation and destructuring along with phis.
92+
// Minimally, check a ValueSet. This walker may traverse chains of
93+
// aggregation and destructuring along with phis.
7794
mutating func needWalk(for value: Value) -> Bool
7895

7996
mutating func walkUp(value: Value) -> WalkResult
@@ -114,7 +131,8 @@ extension ForwardingUseDefWalker {
114131
}
115132
}
116133

117-
// This conveniently gathers all forward introducers and deinitializes visitedValues before the caller has a chance to recurse.
134+
// This conveniently gathers all forward introducers and deinitializes
135+
// visitedValues before the caller has a chance to recurse.
118136
func gatherLifetimeIntroducers(for value: Value, _ context: Context) -> [Value] {
119137
var gather = GatherLifetimeIntroducers(context)
120138
defer { gather.visitedValues.deinitialize() }
@@ -159,14 +177,16 @@ enum ForwardingUseResult: CustomStringConvertible {
159177
}
160178
}
161179

162-
// Visit all the uses in a forward-extended lifetime (LifetimeIntroducer -> Operand).
180+
/// Visit all the uses in a forward-extended lifetime (LifetimeIntroducer -> Operand).
163181
protocol ForwardingDefUseWalker {
164-
// Minimally, check a ValueSet. This walker may traverse chains of aggregation and destructuring by default. Implementations may handle phis.
182+
// Minimally, check a ValueSet. This walker may traverse chains of
183+
// aggregation and destructuring by default. Implementations may
184+
// handle phis.
165185
mutating func needWalk(for value: Value) -> Bool
166186

167187
mutating func leafUse(_ operand: Operand) -> WalkResult
168188

169-
// Report any initial or forwarded with no uses. Only relevant for
189+
// Report any initial or forwarded value with no uses. Only relevant for
170190
// guaranteed values or incomplete OSSA. This could be a dead
171191
// instruction, a terminator in which the result is dead on one
172192
// path, or a dead phi.
@@ -233,9 +253,9 @@ extension ForwardingDefUseWalker {
233253
}
234254
}
235255

236-
// This conveniently allows a closure to be called for each leaf use of a forward-extended lifetime. It should be called on a forward introducer provided by ForwardingDefUseWalker.introducer() or gatherLifetimeIntroducers().
237-
//
238-
// TODO: make the visitor non-escaping once Swift supports stored non-escaping closues.
256+
/// This conveniently allows a closure to be called for each leaf use of a forward-extended lifetime. It should be called on a forward introducer provided by ForwardingDefUseWalker.introducer() or gatherLifetimeIntroducers().
257+
///
258+
/// TODO: make the visitor non-escaping once Swift supports stored non-escaping closues.
239259
func visitForwardedUses(introducer: Value, _ context: Context,
240260
visitor: @escaping (ForwardingUseResult) -> WalkResult)
241261
-> WalkResult {

0 commit comments

Comments
 (0)