[Educational Notes] Add an explanation for sending closure arguments.

Author: hborla

include/swift/AST/EducationalNotes.def

@@ -87,6 +87,8 @@ EDUCATIONAL_NOTES(regionbasedisolation_named_send_yields_race,
                   "sending-risks-data-race.md")
 EDUCATIONAL_NOTES(regionbasedisolation_type_send_yields_race,
                   "sending-risks-data-race.md")
+EDUCATIONAL_NOTES(regionbasedisolation_typed_tns_passed_sending_closure,
+                  "sending-closure-risks-data-race.md")
 EDUCATIONAL_NOTES(shared_mutable_state_decl,
                   "mutable-global-variable.md")
 EDUCATIONAL_NOTES(shared_immutable_state_decl,

userdocs/diagnostics/sending-closure-risks-data-race.md

@@ -0,0 +1,65 @@
+# Sending closure risks causing data races
+
+If a type does not conform to `Sendable` the compiler will enforce that each instance of that type is only accessed by one concurrency domain at a time. The compiler will also prevent you from capturing values in closures that are sent to another concurrency domain if the value can be accessed from the original concurrency domain too.
+
+For example:
+
+```swift
+class MyModel {
+  func perform() {
+    Task {
+      self.update()
+    }
+  }
+
+  func update() { ... }
+}
+```
+
+Building with complete concurrency checking will diagnose the capture of `self` in the task closure:
+
+```
+| class MyModel {
+|   func perform() {
+|     Task {
+|     `- error: passing closure as a 'sending' parameter risks causing data races between code in the current task and concurrent execution of the closure
+|       self.update()
+|            `- note: closure captures 'self' which is accessible to code in the current task
+|     }
+|   }
+```
+
+This code is invalid because the task that calls `perform()` runs concurrently with the task that calls `update()`. The `MyModel` type does not conform to `Sendable`, so this means the concurrent tasks can access mutable state simultaneously.
+
+To eliminate the risk of data races, all tasks that can access the `MyModel` instance must be serialized. The easiest way to accomplish this is to isolate `MyModel` to a global actor:
+
+```swift
+@MainActor
+class MyModel {
+  func perform() {
+    Task {
+      self.update()
+    }
+  }
+
+  func update() { ... }
+}
+```
+
+This resolves the data race because the two tasks that can access the `MyModel` value must switch to the main actor to access its state and methods.
+
+The other approach to resolving the error is to ensure that only one task has access to the `MyModel` value at a time. For example:
+
+```swift
+class MyModel {
+  static func perform(model: sending MyModel) {
+    Task {
+      model.update()
+    }
+  }
+
+  func update() { ... }
+}
+```
+
+This code is safe from data races because the caller of `perform` cannot access the `model` parameter again after the call. The `sending` parameter modifier indicates that the implementation of the function will send the value to a difference concurrency domain, so it's no longer safe to access the value in the caller. This ensures that only one task has access to the value at a time.