Skip to content

Commit 413dfb2

Browse files
committed
Update SSABuilder doc
1 parent c101a96 commit 413dfb2

File tree

1 file changed

+14
-18
lines changed

1 file changed

+14
-18
lines changed

cranelift/frontend/src/ssa.rs

Lines changed: 14 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,7 @@ use smallvec::SmallVec;
2424
/// The parameter struct `Variable` corresponds to the way variables are represented in the
2525
/// non-SSA language you're translating from.
2626
///
27-
/// The SSA building relies on information about the variables used and defined, as well as
28-
/// their position relative to basic blocks which are stricter tha basic blocks since
29-
/// they don't allow branching in the middle of them.
27+
/// The SSA building relies on information about the variables used and defined.
3028
///
3129
/// This SSA building module allows you to def and use variables on the fly while you are
3230
/// constructing the CFG, no need for a separate SSA pass after the CFG is completed.
@@ -53,7 +51,7 @@ pub struct SSABuilder {
5351
side_effects: SideEffects,
5452
}
5553

56-
/// Side effects of a `use_var` or a `seal_block_header_block` method call.
54+
/// Side effects of a `use_var` or a `seal_block` method call.
5755
pub struct SideEffects {
5856
/// When we want to append jump arguments to a `br_table` instruction, the critical edge is
5957
/// splitted and the newly created `Block`s are signaled here.
@@ -94,9 +92,9 @@ type PredBlockSmallVec = SmallVec<[PredBlock; 4]>;
9492

9593
#[derive(Clone, Default)]
9694
struct SSABlockData {
97-
// The predecessors of the Block header block, with the block and branch instruction.
95+
// The predecessors of the Block with the block and branch instruction.
9896
predecessors: PredBlockSmallVec,
99-
// A block header block is sealed if all of its predecessors have been declared.
97+
// A block is sealed if all of its predecessors have been declared.
10098
sealed: bool,
10199
// List of current Block arguments for which an earlier def has not been found yet.
102100
undef_variables: Vec<(Variable, Value)>,
@@ -208,9 +206,7 @@ fn emit_zero(ty: Type, mut cur: FuncCursor) -> Value {
208206
/// The following methods are the API of the SSA builder. Here is how it should be used when
209207
/// translating to Cranelift IR:
210208
///
211-
/// - for each sequence of contiguous instructions (with no branches), create a corresponding
212-
/// basic block with `declare_block_body_block` or `declare_block_header_block` depending on the
213-
/// position of the basic block;
209+
/// - for each basic block, create a corresponding data for SSA construction with `declare_block`;
214210
///
215211
/// - while traversing a basic block and translating instruction, use `def_var` and `use_var`
216212
/// to record definitions and uses of variables, these methods will give you the corresponding
@@ -219,11 +215,11 @@ fn emit_zero(ty: Type, mut cur: FuncCursor) -> Value {
219215
/// - when all the instructions in a basic block have translated, the block is said _filled_ and
220216
/// only then you can add it as a predecessor to other blocks with `declare_block_predecessor`;
221217
///
222-
/// - when you have constructed all the predecessor to a basic block at the beginning of a `Block`,
223-
/// call `seal_block_header_block` on it with the `Function` that you are building.
218+
/// - when you have constructed all the predecessor to a basic block,
219+
/// call `seal_block` on it with the `Function` that you are building.
224220
///
225221
/// This API will give you the correct SSA values to use as arguments of your instructions,
226-
/// as well as modify the jump instruction and `Block` headers parameters to account for the SSA
222+
/// as well as modify the jump instruction and `Block` parameters to account for the SSA
227223
/// Phi functions.
228224
///
229225
impl SSABuilder {
@@ -326,8 +322,8 @@ impl SSABuilder {
326322
self.def_var(var, val, block);
327323
}
328324

329-
/// Declares a new basic block at the beginning of a `Block`. No predecessors are declared
330-
/// here and the block is not sealed.
325+
/// Declares a new basic block to construct corresponding data for SSA construction.
326+
/// No predecessors are declared here and the block is not sealed.
331327
/// Predecessors have to be added with `declare_block_predecessor`.
332328
pub fn declare_block(&mut self, block: Block) {
333329
self.ssa_blocks[block] = SSABlockData {
@@ -337,11 +333,11 @@ impl SSABuilder {
337333
};
338334
}
339335

340-
/// Declares a new predecessor for a `Block` header block and record the branch instruction
336+
/// Declares a new predecessor for a `Block` and record the branch instruction
341337
/// of the predecessor that leads to it.
342338
///
343-
/// Note that the predecessor is a `SSABlock` and not a `Block`. This `SSABlock` must be filled
344-
/// before added as predecessor. Note that you must provide no jump arguments to the branch
339+
/// The precedent `Block` must be filled before added as predecessor.
340+
/// Note that you must provide no jump arguments to the branch
345341
/// instruction when you create it since `SSABuilder` will fill them for you.
346342
///
347343
/// Callers are expected to avoid adding the same predecessor more than once in the case
@@ -661,7 +657,7 @@ impl SSABuilder {
661657
&mut self.ssa_blocks[block].predecessors
662658
}
663659

664-
/// Returns `true` if and only if `seal_block_header_block` has been called on the argument.
660+
/// Returns `true` if and only if `seal_block` has been called on the argument.
665661
pub fn is_sealed(&self, block: Block) -> bool {
666662
self.ssa_blocks[block].sealed
667663
}

0 commit comments

Comments
 (0)