Add documentation to static exclusivity diagnostics

Based on https://www.swift.org/blog/swift-5-exclusivity/ Co-Authored-By: Andrew Trick <atrick@apple.com>

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.