Merge pull request #39962 from lorentey/concurrency-availability

[stdlib] Introduce availability macros

Author: lorentey

CMakeLists.txt

@@ -525,6 +525,18 @@ if(SWIFT_ENABLE_DISPATCH AND NOT CMAKE_SYSTEM_NAME STREQUAL Darwin)
   endif()
 endif()
 
+set(SWIFT_STDLIB_AVAILABILITY_DEFINITIONS
+  "SwiftStdlib 5.0:macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2"
+  "SwiftStdlib 5.1:macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0"
+  "SwiftStdlib 5.2:macOS 10.15.4, iOS 13.4, watchOS 6.2, tvOS 13.4"
+  "SwiftStdlib 5.3:macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0"
+  "SwiftStdlib 5.4:macOS 11.3, iOS 14.5, watchOS 7.4, tvOS 14.5"
+  "SwiftStdlib 5.5:macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0"
+  "SwiftStdlib 5.6:macOS 9999, iOS 9999, watchOS 9999, tvOS 9999"
+  "SwiftStdlib 9999:macOS 9999, iOS 9999, watchOS 9999, tvOS 9999" # Unknown future release
+  CACHE STRING
+  "Availability macros for stdlib versions")
+
 #
 # Include CMake modules
 #

docs/StandardLibraryProgrammersManual.md

@@ -298,34 +298,63 @@ Just like access control modifiers, we prefer to put `@available` attributes on
 
 ```swift
 // 😢👎
-@available(macOS 10.6, iOS 10, watchOS 3, tvOS 12, *)
+@available(SwiftStdlib 5.2, *)
 extension String {
   public func blanch() { ... }
   public func roast() { ... }
 }
 
 // 🥲👍
 extension String {
-  @available(macOS 10.6, iOS 10, watchOS 3, tvOS 12, *)
+  @available(SwiftStdlib 5.2, *)
   public func blanch() { ... }
 
-  @available(macOS 10.6, iOS 10, watchOS 3, tvOS 12, *)
+  @available(SwiftStdlib 5.2, *)
   public func roast() { ... }
 }
 ```
 
 This coding style is enforced by the ABI checker -- it will complain if an extension member declaration that needs an availability doesn't have it directly attached.
 
-Features under development that haven't been released yet must be marked with the placeholder version number `9999`. This special version is always considered available in custom builds of the Swift toolchain (including development snapshots), but not in any ABI-stable production release.
+This repository defines a set of availability macros (of the form `SwiftStdlib x.y`) that map Swift Stdlib releases to the OS versions that shipped them, for all ABI stable platforms. The following two definitions are equivalent, but the second one is less error-prone, so we prefer that:
 
 ```swift
+extension String {
+  // 😵‍💫👎
+  @available(macOS 10.15.4, iOS 13.4, watchOS 6.2, tvOS 13.4, *)
+  public func fiddle() { ... }
+
+  // 😎👍
+  @available(SwiftStdlib 5.2, *)
+  public func fiddle() { ... }
+}
+```
+
+(Mistakes in the OS version number list are very easy to miss during review, but can have major ABI consequences.)
+
+This is especially important for newly introduced APIs, where the corresponding OS releases may not even be known yet. 
+
+Features under development that haven't shipped yet must be marked as available in the placeholder OS version `9999`. This special version is always considered available in custom builds of the Swift toolchain (including development snapshots), but not in any ABI-stable production release. 
+
+Never explicitly spell out such placeholder availability -- instead, use the `SwiftStdlib` macro corresponding to the Swift version we're currently working on:
+
+```swift
+// 😵‍💫👎
 @available(macOS 9999, iOS 9999, watchOS 9999, tvOS 9999, *)
 public struct FutureFeature {
   ...
 }
+
+// 😎👍
+@available(SwiftStdlib 6.3, *) // Or whatever
+public struct FutureFeature {
+  ...
+}
 ```
 
-On these platforms, the Swift Standard Library ships as an integrated part of the operating system; as such, it is the platform owners' responsibility to update these placeholder version numbers to actual versions as part of their release process.
+This way, platform owners can easily update declarations to the correct set of version numbers by simply changing the definition of the macro, rather than having to update each individual declaration.
+
+If we haven't defined a version number for the "next" Swift release yet, please use the special placeholder version `SwiftStdlib 9999`, which always expands to 9999 versions. Declarations that use this version will need to be manually updated once we decide on the corresponding Swift version number.
 
 ## Internals
 

lib/SILGen/SILGenFunction.cpp

@@ -927,7 +927,7 @@ void SILGenFunction::emitAsyncMainThreadStart(SILDeclRef entryPoint) {
   if (!getMainExecutorFuncDecl) {
     // If it doesn't exist due to an SDK-compiler mismatch, we can conjure one
     // up instead of crashing:
-    // @available(SwiftStdlib 5.5, *)
+    // @available(SwiftStdlib 5.1, *)
     // @_silgen_name("swift_task_getMainExecutor")
     // internal func _getMainExecutor() -> Builtin.Executor
 

stdlib/cmake/modules/AddSwiftStdlib.cmake

@@ -1722,6 +1722,11 @@ function(add_swift_target_library name)
         "Either SHARED, STATIC, or OBJECT_LIBRARY must be specified")
   endif()
 
+  # Define availability macros.
+  foreach(def ${SWIFT_STDLIB_AVAILABILITY_DEFINITIONS})
+    list(APPEND SWIFTLIB_SWIFT_COMPILE_FLAGS "-Xfrontend" "-define-availability" "-Xfrontend" "${def}") 
+  endforeach()
+  
   # In the standard library and overlays, warn about implicit overrides
   # as a reminder to consider when inherited protocols need different
   # behavior for their requirements.

stdlib/private/StdlibUnittest/CMakeLists.txt

@@ -55,8 +55,6 @@ add_swift_target_library(swiftStdlibUnittest ${SWIFT_STDLIB_LIBRARY_BUILD_TYPES}
   SWIFT_MODULE_DEPENDS_HAIKU Glibc
   SWIFT_MODULE_DEPENDS_WINDOWS CRT WinSDK
   SWIFT_COMPILE_FLAGS ${swift_stdlib_unittest_compile_flags} ${SWIFT_STANDARD_LIBRARY_SWIFT_FLAGS}
-    -Xfrontend -define-availability
-    -Xfrontend "SwiftStdlib 5.5:macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0"
   INSTALL_IN_COMPONENT stdlib-experimental
   DARWIN_INSTALL_NAME_DIR "${SWIFT_DARWIN_STDLIB_PRIVATE_INSTALL_NAME_DIR}"
   LINK_LIBRARIES ${swift_stdlib_unittest_link_libraries})

stdlib/private/StdlibUnittest/StdlibUnittest.swift

@@ -880,7 +880,7 @@ func _childProcess() {
 }
 
 #if SWIFT_ENABLE_EXPERIMENTAL_CONCURRENCY
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 @inline(never)
 func _childProcessAsync() async {
   _installTrapInterceptor()
@@ -1375,7 +1375,7 @@ class _ParentProcess {
   }
 
 #if SWIFT_ENABLE_EXPERIMENTAL_CONCURRENCY
-  @available(SwiftStdlib 5.5, *)
+  @available(SwiftStdlib 5.1, *)
   internal func runOneTestAsync(
     fullTestName: String,
     testSuite: TestSuite,
@@ -1542,7 +1542,7 @@ class _ParentProcess {
   }
 
 #if SWIFT_ENABLE_EXPERIMENTAL_CONCURRENCY
-  @available(SwiftStdlib 5.5, *)
+  @available(SwiftStdlib 5.1, *)
   func runAsync() async {
     if let filter = _filter {
       print("StdlibUnittest: using filter: \(filter)")
@@ -1727,7 +1727,7 @@ public func runAllTests() {
 }
 
 #if SWIFT_ENABLE_EXPERIMENTAL_CONCURRENCY
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 public func runAllTestsAsync() async {
   if PersistentState.runNoTestsWasCalled {
     print("runAllTests() called after runNoTests(). Aborting.")
@@ -1915,7 +1915,7 @@ public final class TestSuite {
   }
 
 #if SWIFT_ENABLE_EXPERIMENTAL_CONCURRENCY
-  @available(SwiftStdlib 5.5, *)
+  @available(SwiftStdlib 5.1, *)
   func _runTestAsync(name testName: String, parameter: Int?) async {
     PersistentState.ranSomething = true
     for r in _allResettables {

stdlib/public/Concurrency/Actor.swift

@@ -17,7 +17,7 @@ import Swift
 ///
 /// The `Actor` protocol generalizes over all actor types. Actor types
 /// implicitly conform to this protocol.
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 public protocol Actor: AnyObject, Sendable {
 
   /// Retrieve the executor for this actor as an optimized, unowned
@@ -37,17 +37,17 @@ public protocol Actor: AnyObject, Sendable {
 
 /// Called to initialize the default actor instance in an actor.
 /// The implementation will call this within the actor's initializer.
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 @_silgen_name("swift_defaultActor_initialize")
 public func _defaultActorInitialize(_ actor: AnyObject)
 
 /// Called to destroy the default actor instance in an actor.
 /// The implementation will call this within the actor's deinit.
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 @_silgen_name("swift_defaultActor_destroy")
 public func _defaultActorDestroy(_ actor: AnyObject)
 
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 @_silgen_name("swift_task_enqueueMainExecutor")
 @usableFromInline
 internal func _enqueueOnMain(_ job: UnownedJob)

stdlib/public/Concurrency/AsyncCompactMapSequence.swift

@@ -12,7 +12,7 @@
 
 import Swift
 
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 extension AsyncSequence {
   /// Creates an asynchronous sequence that maps the given closure over the
   /// asynchronous sequence’s elements, omitting results that don't return a
@@ -55,7 +55,7 @@ extension AsyncSequence {
 
 /// An asynchronous sequence that maps a given closure over the asynchronous
 /// sequence’s elements, omitting results that don't return a value.
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 public struct AsyncCompactMapSequence<Base: AsyncSequence, ElementOfResult> {
   @usableFromInline
   let base: Base
@@ -73,7 +73,7 @@ public struct AsyncCompactMapSequence<Base: AsyncSequence, ElementOfResult> {
   }
 }
 
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 extension AsyncCompactMapSequence: AsyncSequence {
   /// The type of element produced by this asynchronous sequence.
   ///

stdlib/public/Concurrency/AsyncDropFirstSequence.swift

@@ -12,7 +12,7 @@
 
 import Swift
 
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 extension AsyncSequence {
   /// Omits a specified number of elements from the base asynchronous sequence,
   /// then passes through all remaining elements.
@@ -48,7 +48,7 @@ extension AsyncSequence {
 
 /// An asynchronous sequence which omits a specified number of elements from the
 /// base asynchronous sequence, then passes through all remaining elements.
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 public struct AsyncDropFirstSequence<Base: AsyncSequence> {
   @usableFromInline
   let base: Base
@@ -63,7 +63,7 @@ public struct AsyncDropFirstSequence<Base: AsyncSequence> {
   }
 }
 
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 extension AsyncDropFirstSequence: AsyncSequence {
   /// The type of element produced by this asynchronous sequence.
   ///
@@ -116,7 +116,7 @@ extension AsyncDropFirstSequence: AsyncSequence {
   }
 }
 
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 extension AsyncDropFirstSequence {
   /// Omits a specified number of elements from the base asynchronous sequence,
   /// then passes through all remaining elements.

stdlib/public/Concurrency/AsyncDropWhileSequence.swift

@@ -12,7 +12,7 @@
 
 import Swift
 
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 extension AsyncSequence {
   /// Omits elements from the base asynchronous sequence until a given closure
   /// returns false, after which it passes through all remaining elements.
@@ -52,7 +52,7 @@ extension AsyncSequence {
 /// An asynchronous sequence which omits elements from the base sequence until a
 /// given closure returns false, after which it passes through all remaining
 /// elements.
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 public struct AsyncDropWhileSequence<Base: AsyncSequence> {
   @usableFromInline
   let base: Base
@@ -70,7 +70,7 @@ public struct AsyncDropWhileSequence<Base: AsyncSequence> {
   }
 }
 
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 extension AsyncDropWhileSequence: AsyncSequence {
 
   /// The type of element produced by this asynchronous sequence.

stdlib/public/Concurrency/AsyncFilterSequence.swift

@@ -12,7 +12,7 @@
 
 import Swift
 
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 extension AsyncSequence {
   /// Creates an asynchronous sequence that contains, in order, the elements of
   /// the base sequence that satisfy the given predicate.
@@ -43,7 +43,7 @@ extension AsyncSequence {
 
 /// An asynchronous sequence that contains, in order, the elements of
 /// the base sequence that satisfy a given predicate.
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 public struct AsyncFilterSequence<Base: AsyncSequence> {
   @usableFromInline
   let base: Base
@@ -61,7 +61,7 @@ public struct AsyncFilterSequence<Base: AsyncSequence> {
   }
 }
 
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 extension AsyncFilterSequence: AsyncSequence {
   /// The type of element produced by this asynchronous sequence.
   ///

stdlib/public/Concurrency/AsyncFlatMapSequence.swift

@@ -12,7 +12,7 @@
 
 import Swift
 
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 extension AsyncSequence {
   /// Creates an asynchronous sequence that concatenates the results of calling
   /// the given transformation with each element of this sequence.
@@ -49,7 +49,7 @@ extension AsyncSequence {
 
 /// An asynchronous sequence that concatenates the results of calling a given
 /// transformation with each element of this sequence.
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 public struct AsyncFlatMapSequence<Base: AsyncSequence, SegmentOfResult: AsyncSequence> {
   @usableFromInline
   let base: Base
@@ -67,7 +67,7 @@ public struct AsyncFlatMapSequence<Base: AsyncSequence, SegmentOfResult: AsyncSe
   }
 }
 
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 extension AsyncFlatMapSequence: AsyncSequence {
   /// The type of element produced by this asynchronous sequence.
   ///

stdlib/public/Concurrency/AsyncIteratorProtocol.swift

@@ -84,7 +84,7 @@ import Swift
 /// If the iterator needs to clean up on cancellation, it can do so after
 /// checking for cancellation as described above, or in `deinit` if it's
 /// a reference type.
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 @rethrows
 public protocol AsyncIteratorProtocol {
   associatedtype Element

stdlib/public/Concurrency/AsyncLet.swift

@@ -16,7 +16,7 @@ import Swift
 // ==== Async Let -------------------------------------------------------------
 // Only has internal / builtin functions as it is not really accessible directly
 
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 @_silgen_name("swift_asyncLet_start")
 public func _asyncLetStart<T>(
   asyncLet: Builtin.RawPointer,
@@ -25,34 +25,34 @@ public func _asyncLetStart<T>(
 )
 
 /// DEPRECATED. use _asyncLet_get instead
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 @_silgen_name("swift_asyncLet_wait")
 public func _asyncLetGet<T>(asyncLet: Builtin.RawPointer) async -> T
 
 /// DEPRECATED. use _asyncLet_get_throwing instead
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 @_silgen_name("swift_asyncLet_wait_throwing")
 public func _asyncLetGetThrowing<T>(asyncLet: Builtin.RawPointer) async throws -> T
 
 /// DEPRECATED. use _asyncLet_finish instead
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 @_silgen_name("swift_asyncLet_end")
 public func _asyncLetEnd(
   asyncLet: Builtin.RawPointer // TODO: should this take __owned?
 )
 
 /// Wait if necessary and then project the result value of an async let
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 @_silgen_name("swift_asyncLet_get")
 public func _asyncLet_get(_ asyncLet: Builtin.RawPointer, _ resultBuffer: Builtin.RawPointer) async -> Builtin.RawPointer
 
 /// Wait if necessary and then project the result value of an async let that throws
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 @_silgen_name("swift_asyncLet_get_throwing")
 public func _asyncLet_get_throwing(_ asyncLet: Builtin.RawPointer, _ resultBuffer: Builtin.RawPointer) async throws -> Builtin.RawPointer
 
 /// Wait if necessary and then tear down the async let task
-@available(SwiftStdlib 5.5, *)
+@available(SwiftStdlib 5.1, *)
 @_silgen_name("swift_asyncLet_finish")
 public func _asyncLet_finish(_ asyncLet: Builtin.RawPointer, _ resultBuffer: Builtin.RawPointer) async