[Concurrency] Improve new TaskLocal macro documentation

Author: ktoso

CHANGELOG.md

@@ -5,6 +5,35 @@
 
 ## Swift 6.0
 
+* Since its introduction in Swift 5.1 the @TaskLocal property wrapper was used to   
+  create and access task-local value bindings. Property wrappers introduce mutable storage,
+  which was now properly flagged as potential source of concurrency unsafety.
+ 
+  In order for Swift 6 language mode to not flag task-locals as potentially thread-unsafe,
+  task locals are now implemented using a macro. The macro has the same general semantics 
+  and usage patterns, however there are two source-break situations which the Swift 6 
+  task locals cannot handle:
+
+  Using an implicit default `nil` value for task local initialization, when combined with a type alias:
+  ```swift
+  // allowed in Swift 5.x, not allowed in Swift 6.x
+  
+  typealias MyValue = Optional<Int> 
+  
+  @TaskLocal
+  static var number: MyValue // Swift 6: error, please specify default value explicitl
+  
+  // Solution 1: Specify the default value
+  @TaskLocal
+  static var number: MyValue = nil
+  
+  // Solution 2: Avoid the type-alias
+  @TaskLocal
+  static var number: Optional<Int>
+  ```
+
+  At the same time, task locals can now be declared as global properties, which wasn't possible before.
+
 * Swift 5.10 missed a semantic check from [SE-0309][]. In type context, a reference to a
   protocol `P` that has associated types or `Self` requirements should use
   the `any` keyword, but this was not enforced in nested generic argument positions.

lib/Macros/Sources/SwiftMacros/TaskLocalMacro.swift

@@ -33,6 +33,11 @@ extension TaskLocalMacro: PeerMacro {
       return []
     }
 
+    guard varDecl.bindings.count == 1 else {
+      throw DiagnosticsError(
+        syntax: declaration,
+        message: "'@TaskLocal' property must have exactly one binding", id: .incompatibleDecl)
+    }
     guard let firstBinding = varDecl.bindings.first else {
       throw DiagnosticsError(
         syntax: declaration,
@@ -46,18 +51,18 @@ extension TaskLocalMacro: PeerMacro {
     }
 
     let type = firstBinding.typeAnnotation?.type
-    let explicitType: String
+    let explicitTypeAnnotation: TypeAnnotationSyntax?
     if let type {
-      explicitType = ": TaskLocal<\(type.trimmed)>"
+      explicitTypeAnnotation = TypeAnnotationSyntax(type: TypeSyntax("TaskLocal<\(type.trimmed)>"))
     } else {
-      explicitType = ""
+      explicitTypeAnnotation = nil
     }
 
-    let initialValue: Any
+    let initialValue: ExprSyntax
     if let initializerValue = firstBinding.initializer?.value {
-      initialValue = initializerValue
+      initialValue = ExprSyntax(initializerValue)
     } else if let type, type.isOptional {
-      initialValue = "nil"
+      initialValue = ExprSyntax(NilLiteralExprSyntax())
     } else {
       throw DiagnosticsError(
         syntax: declaration,
@@ -66,16 +71,16 @@ extension TaskLocalMacro: PeerMacro {
 
     // If the property is global, do not prefix the synthesised decl with 'static'
     let isGlobal = context.lexicalContext.isEmpty
-    let staticKeyword: String
+    let staticKeyword: TokenSyntax?
     if isGlobal {
-      staticKeyword = ""
+      staticKeyword = nil
     } else {
-      staticKeyword = "static "
+      staticKeyword = TokenSyntax.keyword(.static, trailingTrivia: .space)
     }
 
     return [
       """
-      \(raw: staticKeyword)let $\(name)\(raw: explicitType) = TaskLocal(wrappedValue: \(raw: initialValue))
+      \(staticKeyword)let $\(name)\(explicitTypeAnnotation) = TaskLocal(wrappedValue: \(initialValue))
       """
     ]
   }
@@ -96,11 +101,11 @@ extension TaskLocalMacro: AccessorMacro {
     try requireStaticContext(varDecl, in: context)
 
     guard let firstBinding = varDecl.bindings.first else {
-      return [] // TODO: make error
+      return []
     }
 
     guard let name = firstBinding.pattern.as(IdentifierPatternSyntax.self)?.identifier else {
-      return [] // TODO: make error
+      return []
     }
 
     return ["get { $\(name).get() }"]
@@ -142,7 +147,7 @@ private func requireStaticContext(_ decl: VariableDeclSyntax,
   if diagnose {
     throw DiagnosticsError(
       syntax: decl,
-      message: "'@TaskLocal' can only be applied to 'static' property", id: .mustBeStatic)
+      message: "'@TaskLocal' can only be applied to 'static' property, or global variables", id: .mustBeStatic)
   }
 
   return false
@@ -153,10 +158,19 @@ extension TypeSyntax {
   // has no type information, but at least for the common case for Optional<T>
   // and T? we can detect the optional.
   fileprivate var isOptional: Bool {
-    let strRepr = "\(self)"
-    return strRepr.last == "?" ||
-      strRepr.starts(with: "Optional<") ||
-      strRepr.starts(with: "Swift.Optional<")
+    switch self.as(TypeSyntaxEnum.self) {
+    case .optionalType:
+      return true
+    case .identifierType(let identifierType):
+      return identifierType.name.text == "Optional"
+    case .memberType(let memberType):
+      guard let baseIdentifier = memberType.baseType.as(IdentifierTypeSyntax.self),
+            baseIdentifier.name.text == "Swift" else {
+        return false
+      }
+      return memberType.name.text == "Optional"
+    default: return false
+    }
   }
 }
 
@@ -185,8 +199,8 @@ struct TaskLocalMacroDiagnostic: DiagnosticMessage {
 }
 
 extension DiagnosticsError {
-  init<S: SyntaxProtocol>(
-    syntax: S,
+  init(
+    syntax: some SyntaxProtocol,
     message: String,
     domain: String = "Swift",
     id: TaskLocalMacroDiagnostic.ID,

stdlib/public/Concurrency/TaskLocal.swift

@@ -17,7 +17,11 @@ import Swift
 // Macros are disabled when Swift is built without swift-syntax.
 #if $Macros && hasAttribute(attached)
 
-// TODO: docs
+/// Macro that introduces a ``TaskLocal-class`` binding.
+///
+/// For information about task-local bindings, see ``TaskLocal-class``.
+///
+/// - SeeAlso: ``TaskLocal-class``
 @available(SwiftStdlib 5.1, *)
 @attached(accessor)
 @attached(peer, names: prefixed(`$`))
@@ -26,22 +30,25 @@ public macro TaskLocal() =
 
 #endif
 
-/// Wrapper that defines a task-local value key.
+/// Wrapper type that defines a task-local value key.
 ///
 /// A task-local value is a value that can be bound and read in the context of a
-/// `Task`. It is implicitly carried with the task, and is accessible by any
-/// child tasks the task creates (such as TaskGroup or `async let` created tasks).
+/// ``Task``. It is implicitly carried with the task, and is accessible by any
+/// child tasks it creates (such as TaskGroup or `async let` created tasks).
 ///
 /// ### Task-local declarations
 ///
-/// Task locals must be declared as static properties (or global properties,
-/// once property wrappers support these), like this:
+/// Task locals must be declared as static properties or global properties, like this:
 ///
 ///     enum Example {
 ///         @TaskLocal
 ///         static let traceID: TraceID?
 ///     }
 ///
+///     // Global task local properties are supported since Swift 6.0:
+///     @TaskLocal
+///     var contextualNumber: Int = 12
+///
 /// ### Default values
 /// Reading a task local value when no value was bound to it results in returning
 /// its default value. For a task local declared as optional (such as e.g. `TraceID?`),
@@ -150,6 +157,8 @@ public macro TaskLocal() =
 ///         read() // traceID: nil
 ///       }
 ///     }
+///
+/// - SeeAlso: ``TaskLocal-macro``
 @available(SwiftStdlib 5.1, *)
 public final class TaskLocal<Value: Sendable>: Sendable, CustomStringConvertible {
   let defaultValue: Value