Store test content in a custom metadata section.

This PR uses the experimental symbol linkage margers feature in the Swift
compiler to emit metadata about tests (and exit tests) into a dedicated section
of the test executable being built. At runtime, we discover that section and
read out the tests from it.

This has several benefits over our current model, which involves walking Swift's
type metadata table looking for types that conform to a protocol:

1. We don't need to define that protocol as public API in Swift Testing,
1. We don't need to emit type metadata (much larger than what we really need)
   for every test function,
1. We don't need to duplicate a large chunk of the Swift ABI sources in order to
   walk the type metadata table correctly, and
1. Almost all the new code is written in Swift, whereas the code it is intended
   to replace could not be fully represented in Swift and needed to be written
   in C++.

The change also opens up the possibility of supporting generic types in the
future because we can emit metadata without needing to emit a nested type (which
is not always valid in a generic context.) That's a "future direction" and not
covered by this PR specifically.

I've defined a layout for entries in the new `swift5_tests` section that should
be flexible enough for us in the short-to-medium term and which lets us define
additional arbitrary test content record types. The layout of this section is
covered in depth in the new [TestContent.md](Documentation/ABI/TestContent.md)
article.

This functionality is only available if a test target enables the experimental
`"SymbolLinkageMarkers"` feature. We continue to emit protocol-conforming types
for now—that code will be removed if and when the experimental feature is
properly supported (modulo us adopting relevant changes to the feature's API.)

#735
swiftlang/swift#76698
swiftlang/swift#78411

Author: grynspan

Documentation/ABI/TestContent.md

@@ -75,16 +75,16 @@ struct SWTTestContentRecord {
 };
 ```
 
-Do not use the `__TestContentRecord` or `__TestContentRecordAccessor` typealias
-defined in the testing library. These types exist to support the testing
+Do not use the `__TestContentRecord` or `__TestContentRecordAccessor` type
+aliases defined in the testing library. These types exist to support the testing
 library's macros and may change in the future (e.g. to accomodate a generic
 argument or to make use of a reserved field.)
 
 Instead, define your own copy of these types where needed—you can copy the
 definitions above _verbatim_. If your test record type's `context` field (as
 described below) is a pointer type, make sure to change its type in your version
 of `TestContentRecord` accordingly so that, on systems with pointer
-authentication enabled, the pointer is correctly resigned at load time.
+authentication enabled, the pointer is correctly re-signed at load time.
 
 ### Record content
 

Documentation/Porting.md

@@ -145,8 +145,10 @@ to load that information:
 +  let resourceName: Str255 = switch kind {
 +  case .testContent:
 +    "__swift5_tests"
++#if !SWT_NO_LEGACY_TEST_DISCOVERY
 +  case .typeMetadata:
 +    "__swift5_types"
++#endif
 +  }
 +
 +  let oldRefNum = CurResFile()
@@ -219,15 +221,19 @@ diff --git a/Sources/_TestingInternals/Discovery.cpp b/Sources/_TestingInternals
 +#elif defined(macintosh)
 +extern "C" const char testContentSectionBegin __asm__("...");
 +extern "C" const char testContentSectionEnd __asm__("...");
++#if !defined(SWT_NO_LEGACY_TEST_DISCOVERY)
 +extern "C" const char typeMetadataSectionBegin __asm__("...");
 +extern "C" const char typeMetadataSectionEnd __asm__("...");
++#endif
  #else
  #warning Platform-specific implementation missing: Runtime test discovery unavailable (static)
  static const char testContentSectionBegin = 0;
  static const char& testContentSectionEnd = testContentSectionBegin;
+ #if !defined(SWT_NO_LEGACY_TEST_DISCOVERY)
  static const char typeMetadataSectionBegin = 0;
  static const char& typeMetadataSectionEnd = testContentSectionBegin;
  #endif
+ #endif
 ```
 
 These symbols must have unique addresses corresponding to the first byte of the

Package.swift

@@ -165,6 +165,8 @@ extension Array where Element == PackageDescription.SwiftSetting {
       .enableExperimentalFeature("AccessLevelOnImport"),
       .enableUpcomingFeature("InternalImportsByDefault"),
 
+      .enableExperimentalFeature("SymbolLinkageMarkers"),
+
       .define("SWT_TARGET_OS_APPLE", .when(platforms: [.macOS, .iOS, .macCatalyst, .watchOS, .tvOS, .visionOS])),
 
       .define("SWT_NO_EXIT_TESTS", .when(platforms: [.iOS, .watchOS, .tvOS, .visionOS, .wasi, .android])),

Sources/Testing/Discovery+Platform.swift

@@ -27,8 +27,10 @@ struct SectionBounds: Sendable {
     /// The test content metadata section.
     case testContent
 
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
     /// The type metadata section.
     case typeMetadata
+#endif
   }
 
   /// All section bounds of the given kind found in the current process.
@@ -60,8 +62,10 @@ extension SectionBounds.Kind {
     switch self {
     case .testContent:
       ("__DATA_CONST", "__swift5_tests")
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
     case .typeMetadata:
       ("__TEXT", "__swift5_types")
+#endif
     }
   }
 }
@@ -101,9 +105,8 @@ private let _startCollectingSectionBounds: Void = {
       var size = CUnsignedLong(0)
       if let start = getsectiondata(mh, segmentName.utf8Start, sectionName.utf8Start, &size), size > 0 {
         let buffer = UnsafeRawBufferPointer(start: start, count: Int(clamping: size))
-        let sb = SectionBounds(imageAddress: mh, buffer: buffer)
         _sectionBounds.withLock { sectionBounds in
-          sectionBounds[kind]!.append(sb)
+          sectionBounds[kind]!.append(SectionBounds(imageAddress: mh, buffer: buffer))
         }
       }
     }
@@ -165,8 +168,10 @@ private func _sectionBounds(_ kind: SectionBounds.Kind) -> [SectionBounds] {
       let range = switch context.pointee.kind {
       case .testContent:
         sections.swift5_tests
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
       case .typeMetadata:
         sections.swift5_type_metadata
+#endif
       }
       let start = UnsafeRawPointer(bitPattern: range.start)
       let size = Int(clamping: range.length)
@@ -255,8 +260,10 @@ private func _sectionBounds(_ kind: SectionBounds.Kind) -> some Sequence<Section
   let sectionName = switch kind {
   case .testContent:
     ".sw5test"
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
   case .typeMetadata:
     ".sw5tymd"
+#endif
   }
   return HMODULE.all.lazy.compactMap { _findSection(named: sectionName, in: $0) }
 }

Sources/Testing/Discovery.swift

@@ -49,6 +49,23 @@ public typealias __TestContentRecord = (
   reserved2: UInt
 )
 
+/// Check if the type at the given address is equal to a given Swift type.
+///
+/// - Parameters:
+///   - typeAddress: A pointer to a Swift type, as in the `type` argument to a
+///     test content record accessor function.
+///   - type: The type expected to be at `typeAddress`.
+///
+/// - Returns: Whether or not the type at `typeAddress` equals `type`.
+///
+/// - Warning: This function is used to implement the `@Test`, `@Suite`, and
+///   `#expect(exitsWith:)` macros. Do not use it directly.
+public func __type(at typeAddress: UnsafeRawPointer, is type: (some ~Copyable).Type) -> Bool {
+  // `typeAddress` may actually point to a move-only type, but attempting to
+  // load it as such leads to a crash. SEE: rdar://134277439
+  TypeInfo(describing: typeAddress.load(as: Any.Type.self)) == TypeInfo(describing: type)
+}
+
 // MARK: -
 
 /// A protocol describing a type that can be stored as test content at compile
@@ -73,21 +90,14 @@ protocol TestContent: ~Copyable {
   ///
   /// By default, this type equals `Never`, indicating that this type of test
   /// content does not support hinting during discovery.
-  associatedtype TestContentAccessorHint: Sendable = Never
+  associatedtype TestContentAccessorHintArgument: Sendable = Never
 
   /// The type to pass (by address) as the accessor function's `type` argument.
   ///
-  /// The default value of this property is `Self.self`. A conforming type can
-  /// override the default implementation to substitute another type (e.g. if
-  /// the conforming type is not public but records are created during macro
-  /// expansion and can only reference public types.)
-  static var testContentAccessorTypeArgument: any ~Copyable.Type { get }
-}
-
-extension TestContent where Self: ~Copyable {
-  static var testContentAccessorTypeArgument: any ~Copyable.Type {
-    self
-  }
+  /// By default, this type equals `Self`. A conforming type can substitute
+  /// another type (e.g. if the conforming type is not public but records are
+  /// created during macro expansion and can only reference public types.)
+  associatedtype TestContentAccessorTypeArgument: ~Copyable = Self
 }
 
 // MARK: - Individual test content records
@@ -113,16 +123,16 @@ struct TestContentRecord<T>: Sendable where T: TestContent & ~Copyable {
   nonisolated(unsafe) var imageAddress: UnsafeRawPointer?
 
   /// The underlying test content record loaded from a metadata section.
-  private var _record: __TestContentRecord
+  private nonisolated(unsafe) var _record: UnsafePointer<__TestContentRecord>
 
-  fileprivate init(imageAddress: UnsafeRawPointer?, record: __TestContentRecord) {
+  fileprivate init(imageAddress: UnsafeRawPointer?, record: UnsafePointer<__TestContentRecord>) {
     self.imageAddress = imageAddress
     self._record = record
   }
 
   /// The context value for this test content record.
   var context: UInt {
-    _record.context
+    _record.pointee.context
   }
 
   /// Load the value represented by this record.
@@ -137,12 +147,12 @@ struct TestContentRecord<T>: Sendable where T: TestContent & ~Copyable {
   ///
   /// If this function is called more than once on the same instance, a new
   /// value is created on each call.
-  func load(withHint hint: T.TestContentAccessorHint? = nil) -> T? {
-    guard let accessor = _record.accessor else {
+  func load(withHint hint: T.TestContentAccessorHintArgument? = nil) -> T? {
+    guard let accessor = _record.pointee.accessor else {
       return nil
     }
 
-    return withUnsafePointer(to: T.testContentAccessorTypeArgument) { type in
+    return withUnsafePointer(to: T.TestContentAccessorTypeArgument.self) { type in
       withUnsafeTemporaryAllocation(of: T.self, capacity: 1) { buffer in
         let initialized = if let hint {
           withUnsafePointer(to: hint) { hint in
@@ -175,8 +185,9 @@ extension TestContent where Self: ~Copyable {
   static func allTestContentRecords() -> AnySequence<TestContentRecord<Self>> {
     let result = SectionBounds.all(.testContent).lazy.flatMap { sb in
       sb.buffer.withMemoryRebound(to: __TestContentRecord.self) { records in
-        records.lazy
-          .filter { $0.kind == testContentKind }
+        (0 ..< records.count).lazy
+          .map { records.baseAddress! + $0 }
+          .filter { $0.pointee.kind == testContentKind }
           .map { TestContentRecord<Self>(imageAddress: sb.imageAddress, record: $0) }
       }
     }

Sources/Testing/ExitTests/ExitTest.swift

@@ -59,11 +59,7 @@ public struct __ExitTest: Sendable, ~Copyable {
     private var _lo: UInt64
     private var _hi: UInt64
 
-    /// Initialize an instance of this type.
-    ///
-    /// - Warning: This member is used to implement the `#expect(exitsWith:)`
-    ///   macro. Do not use it directly.
-    public init(__uuid uuid: (UInt64, UInt64)) {
+    init(_ uuid: (UInt64, UInt64)) {
       self._lo = uuid.0
       self._hi = uuid.1
     }
@@ -77,7 +73,7 @@ public struct __ExitTest: Sendable, ~Copyable {
   /// Do not invoke this closure directly. Instead, invoke ``callAsFunction()``
   /// to run the exit test. Running the exit test will always terminate the
   /// current process.
-  fileprivate var body: @Sendable () async throws -> Void
+  fileprivate var body: @Sendable () async throws -> Void = {}
 
   /// Storage for ``observedValues``.
   ///
@@ -113,18 +109,6 @@ public struct __ExitTest: Sendable, ~Copyable {
       _observedValues = newValue
     }
   }
-
-  /// Initialize an exit test at runtime.
-  ///
-  /// - Warning: This initializer is used to implement the `#expect(exitsWith:)`
-  ///   macro. Do not use it directly.
-  public init(
-    __identifiedBy id: ID,
-    body: @escaping @Sendable () async throws -> Void = {}
-  ) {
-    self.id = id
-    self.body = body
-  }
 }
 
 #if !SWT_NO_EXIT_TESTS
@@ -228,7 +212,41 @@ extension ExitTest: TestContent {
     0x65786974
   }
 
-  typealias TestContentAccessorHint = ID
+  typealias TestContentAccessorHintArgument = ID
+
+  /// Store the test generator function into the given memory.
+  ///
+  /// - Parameters:
+  ///   - outValue: The uninitialized memory to store the exit test into.
+  ///   - id: The unique identifier of the exit test to store.
+  ///   - body: The body closure of the exit test to store.
+  ///   - typeAddress: A pointer to the expected type of the exit test as passed
+  ///     to the test content record calling this function.
+  ///   - hintAddress: A pointer to an instance of ``ID`` to use as a hint.
+  ///
+  /// - Returns: Whether or not an exit test was stored into `outValue`.
+  ///
+  /// - Warning: This function is used to implement the `#expect(exitsWith:)`
+  ///   macro. Do not use it directly.
+  public static func __store(
+    _ id: (UInt64, UInt64),
+    _ body: @escaping @Sendable () async throws -> Void,
+    into outValue: UnsafeMutableRawPointer,
+    asTypeAt typeAddress: UnsafeRawPointer,
+    withHintAt hintAddress: UnsafeRawPointer? = nil
+  ) -> CBool {
+    let callerExpectedType = TypeInfo(describing: typeAddress.load(as: Any.Type.self))
+    let selfType = TypeInfo(describing: Self.self)
+    guard callerExpectedType == selfType else {
+      return false
+    }
+    let id = ID(id)
+    if let hintedID = hintAddress?.load(as: ID.self), hintedID != id {
+      return false
+    }
+    outValue.initializeMemory(as: Self.self, to: Self(id: id, body: body))
+    return true
+  }
 }
 
 @_spi(Experimental) @_spi(ForToolsIntegrationOnly)
@@ -247,11 +265,15 @@ extension ExitTest {
       }
     }
 
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
     // Call the legacy lookup function that discovers tests embedded in types.
     return types(withNamesContaining: exitTestContainerTypeNameMagic).lazy
       .compactMap { $0 as? any __ExitTestContainer.Type }
-      .first { $0.__id == id }
-      .map { ExitTest(__identifiedBy: $0.__id, body: $0.__body) }
+      .first { ID($0.__id) == id }
+      .map { ExitTest(id: ID($0.__id), body: $0.__body) }
+#else
+    return nil
+#endif
   }
 }
 
@@ -280,7 +302,7 @@ extension ExitTest {
 /// `await #expect(exitsWith:) { }` invocations regardless of calling
 /// convention.
 func callExitTest(
-  identifiedBy exitTestID: ExitTest.ID,
+  identifiedBy exitTestID: (UInt64, UInt64),
   exitsWith expectedExitCondition: ExitCondition,
   observing observedValues: [any PartialKeyPath<ExitTestArtifacts> & Sendable],
   expression: __Expression,
@@ -295,7 +317,7 @@ func callExitTest(
 
   var result: ExitTestArtifacts
   do {
-    var exitTest = ExitTest(__identifiedBy: exitTestID)
+    var exitTest = ExitTest(id: ExitTest.ID(exitTestID))
     exitTest.observedValues = observedValues
     result = try await configuration.exitTestHandler(exitTest)
 

Sources/Testing/Expectations/ExpectationChecking+Macro.swift

@@ -1147,7 +1147,7 @@ public func __checkClosureCall<R>(
 ///   `#require()` macros. Do not call it directly.
 @_spi(Experimental)
 public func __checkClosureCall(
-  identifiedBy exitTestID: __ExitTest.ID,
+  identifiedBy exitTestID: (UInt64, UInt64),
   exitsWith expectedExitCondition: ExitCondition,
   observing observedValues: [any PartialKeyPath<ExitTestArtifacts> & Sendable],
   performing body: @convention(thin) () -> Void,

Sources/Testing/Test+Discovery+Legacy.swift

@@ -10,6 +10,7 @@
 
 private import _TestingInternals
 
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
 /// A protocol describing a type that contains tests.
 ///
 /// - Warning: This protocol is used to implement the `@Test` macro. Do not use
@@ -33,7 +34,7 @@ let testContainerTypeNameMagic = "__🟠$test_container__"
 @_spi(Experimental)
 public protocol __ExitTestContainer {
   /// The unique identifier of the exit test.
-  static var __id: __ExitTest.ID { get }
+  static var __id: (UInt64, UInt64) { get }
 
   /// The body function of the exit test.
   static var __body: @Sendable () async throws -> Void { get }
@@ -60,3 +61,4 @@ func types(withNamesContaining nameSubstring: String) -> some Sequence<Any.Type>
       .map { unsafeBitCast($0, to: Any.Type.self) }
   }
 }
+#endif