Merge pull request swiftlang#83963 from owenv/exclusivity-docs

Add documentation to static exclusivity diagnostics

Author: owenv

include/swift/AST/DiagnosticGroups.def

@@ -47,6 +47,7 @@ GROUP(ConformanceIsolation, "conformance-isolation")
 GROUP(DeprecatedDeclaration, "deprecated-declaration")
 GROUP(DynamicCallable, "dynamic-callable-requirements")
 GROUP(ErrorInFutureSwiftVersion, "error-in-future-swift-version")
+GROUP(ExclusivityViolation, "exclusivity-violation")
 GROUP(ExistentialAny, "existential-any")
 GROUP(ExistentialMemberAccess, "existential-member-access-limitations")
 GROUP(ImplementationOnlyDeprecated, "implementation-only-deprecated")

include/swift/AST/DiagnosticsSIL.def

@@ -84,26 +84,26 @@ ERROR(unimplemented_generator_witnesses,none,
       "protocol conformance emission for generator coroutines is unimplemented",
       ())
 
-ERROR(exclusivity_access_required,none,
+GROUPED_ERROR(exclusivity_access_required,ExclusivityViolation,none,
       "overlapping accesses to %0, but "
       "%select{initialization|read|modification|deinitialization}1 requires "
       "exclusive access; "
       "%select{consider copying to a local variable|"
               "consider calling MutableCollection.swapAt(_:_:)}2",
       (StringRef, unsigned, bool))
 
-ERROR(exclusivity_access_required_unknown_decl,none,
+GROUPED_ERROR(exclusivity_access_required_unknown_decl,ExclusivityViolation,none,
         "overlapping accesses, but "
         "%select{initialization|read|modification|deinitialization}0 requires "
         "exclusive access; consider copying to a local variable", (unsigned))
 
-ERROR(exclusivity_access_required_moveonly,none,
+GROUPED_ERROR(exclusivity_access_required_moveonly,ExclusivityViolation,none,
       "overlapping accesses to %0, but "
       "%select{initialization|read|modification|deinitialization}1 requires "
       "exclusive access",
       (StringRef, unsigned))
 
-ERROR(exclusivity_access_required_unknown_decl_moveonly,none,
+GROUPED_ERROR(exclusivity_access_required_unknown_decl_moveonly,ExclusivityViolation,none,
         "overlapping accesses, but "
         "%select{initialization|read|modification|deinitialization}0 requires "
         "exclusive access", (unsigned))

userdocs/diagnostics/diagnostic-descriptions.md

@@ -29,6 +29,7 @@ presented specially within your IDE of choice. See below for the full list of th
 - <doc:nominal-types>
 - <doc:property-wrapper-requirements>
 - <doc:protocol-type-non-conformance>
+- <doc:exclusivity-violation>
 - <doc:conformance-isolation>
 - <doc:result-builder-methods>
 - <doc:sendable-metatypes>

userdocs/diagnostics/exclusivity-violation.md

@@ -0,0 +1,61 @@
+# Overlapping accesses, but operation requires exclusive access
+
+Swift requires exclusive access to a variable in order to modify that variable. An error is reported if a program attempts to access a variable while it is already in the process of being accessed via another name. These issues can often be resolved by making a local copy of a variable before modifying it.
+
+In the following example, `count` is accessed for modification by passing it as an `inout` argument to `modifyTwice`. This `inout` access to `count` lasts for the entire duration of the `modifyTwice` function call. The exclusivity violation occurs because the `modifier` closure also accesses `count` via the name `$0` while the first access is in progress.
+
+```swift
+func modifyTwice(_ value: inout Int, by modifier: (inout Int) -> ()) {
+  modifier(&value)
+  modifier(&value)
+}
+
+func testCount() {
+  var count = 1
+  modifyTwice(&count) { $0 += count } // error: overlapping accesses to 'count', but modification requires exclusive access; consider copying to a local variable
+  print(count)
+}
+```
+
+This exclusivity violation can be fixed by introducing a local variable to track the value the `modifier` closure should add to its argument.
+
+```swift
+func modifyTwice(_ value: inout Int, by modifier: (inout Int) -> ()) {
+  modifier(&value)
+  modifier(&value)
+}
+
+func testCount() {
+  var count = 1
+  let incrementBy = count
+  modifyTwice(&count) { $0 += incrementBy }
+  print(count)
+}
+```
+
+In this updated program, `count` and `$0` no longer refer to the same variable, so accessing them at the same time does not violate exclusivity.
+
+Another common source of exclusivity violations occurs when a `mutating` method modifies `self`:
+
+```swift
+extension Array {
+    mutating func append(removingFrom other: inout Array<Element>) {
+        while !other.isEmpty {
+            self.append(other.removeLast())
+        }
+    }
+}
+
+var numbers = [1, 2, 3]
+numbers.append(removingFrom: &numbers) // error: overlapping accesses to 'x', but modification requires exclusive access; consider copying to a local variable
+```
+
+A `mutating` method accesses `self` for the duration of the method call, so in this example `numbers` has two conflicting long-lived accesses, one as `self` and one as an `inout` argument to the method. Again, a local variable can be introduced to eliminate the conflict:
+
+```swift
+var numbers = [1, 2, 3]
+var toAppend = numbers
+numbers.append(removingFrom: &toAppend)
+```
+
+Exclusivity checks play an important role in enforcing memory safety and enabling compiler optimizations. To learn more, see [Swift 5 Exclusivity Enforcement](https://www.swift.org/blog/swift-5-exclusivity/) on the Swift.org blog.