Merge pull request #64308 from gottesmm/pr-f1b021e0dd1be892eb0dbfba3f403d9823e0c5f7

[move-only] Update the address checker description comment given changes to the algorithm.

Author: gottesmm

lib/SILOptimizer/Mandatory/MoveOnlyAddressCheckerUtils.cpp

@@ -17,21 +17,120 @@
 /// compiler to perform move checking of address only lets, vars, inout args,
 /// and mutating self.
 ///
-/// Algorithm At a High Level
-/// -------------------------
+/// Move Address Checking in Swift
+/// ------------------------------
 ///
-/// At a high level, this algorithm can be conceptualized as attempting to
-/// completely classify the memory behavior of the recursive uses of a move only
-/// marked address and then seek to transform those uses such that they are in
-/// "simple move only address" form. We define "simple move only address" to
-/// mean that along any path from an init of an address to a consume, all uses
-/// are guaranteed to be semantically "borrow uses". If we find that any such
-/// owned uses can not be turned into a "borrow" use, then we emit an error
-/// since we would need to insert a copy there.
+/// In order to not have to rewrite all of SILGen to avoid copies, Swift has
+/// taken an approach where SILGen marks moveonly addresses with a special
+/// marker instruction and emits copies when it attempts to access move only
+/// addresses. Then this algorithm fixed up SILGen's output by analyzing the
+/// memory uses of a marked memory root location recursively using AccessPath
+/// based analyses and then attempting to transform those uses based off of the
+/// marked kind into one of a few variants of "simple move only address form"
+/// (see below for more information). If the pass is unable to reason that it
+/// can safely transform the uses into said form, we emit a diagnostic stating
+/// the error to the user. If we emit said diagnostic, we then bail early. If we
+/// do not emit a diagnostic, we then transform the IR so that the move only
+/// address uses are in said form. This then guarantees that despite SILGen
+/// emitting move only types with copies, in the end, our move only types are
+/// never copied. As an additional check, once the pass has run we emit an extra
+/// diagnostic if we find any copies of move only types so that the user can be
+/// sure that any accepted program does not copy move only types.
+///
+/// Simple Move Only Address Form
+/// -----------------------------
+///
+/// We define a memory location to be in "simple move only address" form (SMOA
+/// form for ease of typing) to mean that along any path from an init of the
+/// address to a consume of the address, all uses are guaranteed to be semantic
+/// "borrow uses" instead of semantic "copy uses". Additionally, SMOA does not
+/// consider destroy_addr to be a true consuming use since it will rewrite
+/// destroy_addr as necessary so the consuming uses are defined by consuming
+/// uses modulo destroy_addr.
+///
+/// An example of a memory location in "simple move only address form" is the
+/// following:
+///
+/// ```
+/// // Memory is defined
+/// %0 = alloc_stack $Type
+///
+/// // Initial initialization.
+/// store %input to [init] %0 : $Type
+///
+/// // Sequence of borrow uses.
+/// %1 = load_borrow %0 : $Type
+/// apply %f(%1) : $@convention(thin) (@guaranteed Type) -> ()
+/// end_borrow %1
+/// apply %f2(%0) : $@convention(thin) (@in_guaranteed Type) -> ()
+///
+/// // Assign is ok since we are just consuming the value.
+/// store %input2 to [assign] %0 : $*Type
+///
+/// // More borrow uses.
+/// %3 = load_borrow %0 : $*Type
+/// apply %f(%3) : $@convention(thin) (@guaranteed Type) -> ()
+/// end_borrow %1
+/// apply %f2(%0) : $@convention(thin) (@in_guaranteed Type) -> ()
+///
+/// // Final destroy
+/// destroy_addr %0 : $Type
+/// ```
+///
+/// An example of an instruction not in SMOA form is:
+///
+/// ```
+/// // Memory is defined
+/// %0 = alloc_stack $Type
+///
+/// // Initial initialization.
+/// store %input to [init] %0 : $*Type
+///
+/// // Perform a load + copy of %0 to pass as an argument to %f.
+/// %1 = load [copy] %0 : $*Type
+/// apply %f(%1) : $@convention(thin) (@guaranteed Type) -> ()
+/// destroy_value %1 : $Type
+///
+/// // Initialize other variable.
+/// %otherVar = alloc_stack $Type
+/// copy_addr %0 to [initialization] %otherVar : $*Type
+/// ...
+///
+/// // Final destroy that is not part of the use set.
+/// destroy_addr %0 : $*Type
+/// ```
+///
+/// The variants of SMOA form can be classified by the specific mark_must_check
+/// kind put on the the checker mark instruction and are as follows:
+///
+/// 1. no_consume_or_assign. This means that the address can only be consumed by
+/// destroy_addr and otherwise is only read from. This simulates guaranteed
+/// semantics.
+///
+/// 2. consumable_and_assignable. This means that the address can be consumed
+/// (e.x.: take/pass to a +1 function) or assigned to. Additionally, the value
+/// is supposed to have its lifetime end along all program paths locally in the
+/// function. This simulates a local var's semantics.
+///
+/// 3. assignable_but_not_consumable. This means that the address can be
+/// assigned over, but cannot be taken from. It additionally must have a valid
+/// value in it and the end of its lifetime. This simulates accesses to class
+/// fields, globals, and escaping mutable captures where we want the user to be
+/// able to update the value, but allowing for escapes of the value would break
+/// memory safety. In all cases where this is used, the mark_must_check is used
+/// as the initial def of the value lifetime. Example:
+///
+/// 4. initable_but_not_consumable. This means that the address can only be
+/// initialized once but cannot be taken from or assigned over. It is assumed
+/// that the initial def will always be the mark_must_check and that the value
+/// will be uninitialized at that point. Example:
+///
+/// Algorithm Stages In Detail
+/// --------------------------
 ///
 /// To implement this, our algorithm works in 4 stages: a use classification
 /// stage, a dataflow stage, and then depending on success/failure one of two
-/// transform stagesWe describe them below.
+/// transform stages.
 ///
 /// Use Classification Stage
 /// ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -75,23 +174,22 @@
 /// Dataflow Stage
 /// ~~~~~~~~~~~~~~
 ///
-/// To perform our dataflow, we do the following:
-///
-/// 1. We walk each block from top to bottom performing the single block version
-/// of the algorithm and preparing field sensitive pruned liveness.
-///
-/// 2. If we need to, we then use field sensitive pruned liveness to perform
-/// global dataflow to determine if any of our takeOrCopies are within the
-/// boundary lifetime implying a violation.
+/// To perform our dataflow, we take our classified uses and initialize field
+/// sensitive pruned liveness with the data. We then use field sensitive pruned
+/// liveness and our check kinds to determine if all of our copy uses that could
+/// not be changed into borrows are on the liveness boundary of the memory. If
+/// they are within the liveness boundary, then we know a copy is needed and we
+/// emit an error to the user. Otherwise, we know that we can change them
+/// semantically into a take.
 ///
 /// Success Transformation
 /// ~~~~~~~~~~~~~~~~~~~~~~
 ///
-/// Upon success Now that we know that we can change our address into "simple
-/// move only address form", we transform the IR in the following way:
+/// Now that we know that we can change our address into "simple move only
+/// address form", we transform the IR in the following way:
 ///
 /// 1. Any load [copy] that are classified as borrows are changed to
-/// load_borrow.
+///    load_borrow.
 /// 2. Any load [copy] that are classified as takes are changed to load [take].
 /// 3. Any copy_addr [init] temporary allocation are eliminated with their
 ///    destroy_addr. All uses are placed on the source address.
@@ -107,6 +205,19 @@
 /// are going to fail anyways at this point, so it is ok to do so since we will
 /// fail before attempting to codegen into LLVM IR.
 ///
+/// Final Black Box Checks on Success
+/// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+///
+/// Finally since we want to be able to guarantee to users 100% that the
+/// compiler will reject programs even if the checker gives a false success for
+/// some reason due to human compiler writer error, we do a last pass over the
+/// IR and emit an error diagnostic on any copies of move only types that we
+/// see. The error states to the user that this is a compiler bug and to file a
+/// bug report. Since it is a completely separate, simple implementation, this
+/// gives the user of our implementation the confidence to know that the
+/// compiler even in the face of complexity in the checker will emit correct
+/// code.
+///
 //===----------------------------------------------------------------------===//
 
 #define DEBUG_TYPE "sil-move-only-checker"