Add an unreachable marker function. (#1150)

This PR adds a wrapper around `__builtin_unreachable()`
(`Builtin.unreachable()` when building the Swift standard library) that
we can use in place of `fatalError()`. The benefit is that the generated
code size for unreachable paths is significantly reduced. For example,
given the following function compiled with `-O`:

```swift
@available(*, unavailable) func f() {
  fatalError("Unreachable")
}
```

The compiler currently produces:

```asm
sub    sp, sp, #0x20
stp    x29, x30, [sp, #0x10]
add    x29, sp, #0x10
mov    w8, #0x1                  ; =1
str    w8, [sp, #0x8]
mov    w8, #0xc                  ; =12
str    x8, [sp]
adrp   x0, 0
add    x0, x0, #0x6a8            ; "Fatal error"
adrp   x5, 0
add    x5, x5, #0x690            ; "UnreachableTest/S.swift"
mov    x3, #0x6e55               ; =28245
movk   x3, #0x6572, lsl #16
movk   x3, #0x6361, lsl #32
movk   x3, #0x6168, lsl #48
mov    x4, #0x6c62               ; =27746
movk   x4, #0x65, lsl #16
movk   x4, #0xeb00, lsl #48
mov    w1, #0xb                  ; =11
mov    w2, #0x2                  ; =2
mov    w6, #0x17                 ; =23
mov    w7, #0x2                  ; =2
bl     0x100000680               ; symbol stub for: Swift._assertionFailure(_: Swift.StaticString, _: Swift.String, file: Swift.StaticString, line: Swift.UInt, flags: Swift.UInt32) -> Swift.Never
brk    #0x1
```

But with this change:
```swift
@available(*, unavailable) func f() {
  swt_unreachable()
}
```

It instead compiles to simply:

```asm
brk    #0x1
```

### Checklist:

- [x] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [x] If public symbols are renamed or modified, DocC references should
be updated.

Author: grynspan

Sources/Testing/ExitTests/ExitTest.CapturedValue.swift

@@ -8,6 +8,8 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
+private import _TestingInternals
+
 @_spi(Experimental) @_spi(ForToolsIntegrationOnly)
 #if SWT_NO_EXIT_TESTS
 @available(*, unavailable, message: "Exit tests are not available on this platform.")
@@ -82,7 +84,7 @@ extension ExitTest {
         }
         return nil
 #else
-        fatalError("Unsupported")
+        swt_unreachable()
 #endif
       }
 
@@ -101,7 +103,7 @@ extension ExitTest {
           _kind = .typeOnly(type)
         }
 #else
-        fatalError("Unsupported")
+        swt_unreachable()
 #endif
       }
     }
@@ -119,7 +121,7 @@ extension ExitTest {
         type
       }
 #else
-      fatalError("Unsupported")
+      swt_unreachable()
 #endif
     }
   }

Sources/Testing/ExitTests/ExitTest.Condition.swift

@@ -136,7 +136,7 @@ extension ExitTest.Condition {
 #if !SWT_NO_EXIT_TESTS
     Self(.exitCode(exitCode))
 #else
-    fatalError("Unsupported")
+    swt_unreachable()
 #endif
   }
 
@@ -169,7 +169,7 @@ extension ExitTest.Condition {
 #if !SWT_NO_EXIT_TESTS
     Self(.signal(signal))
 #else
-    fatalError("Unsupported")
+    swt_unreachable()
 #endif
   }
 }
@@ -192,7 +192,7 @@ extension ExitTest.Condition: CustomStringConvertible {
       String(describing: exitStatus)
     }
 #else
-    fatalError("Unsupported")
+    swt_unreachable()
 #endif
   }
 }

Sources/Testing/Issues/Confirmation.swift

@@ -8,6 +8,8 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
+private import _TestingInternals
+
 /// A type that can be used to confirm that an event occurs zero or more times.
 public struct Confirmation: Sendable {
   /// The number of times ``confirm(count:)`` has been called.
@@ -202,7 +204,7 @@ public func confirmation<R>(
   sourceLocation: SourceLocation = #_sourceLocation,
   _ body: (Confirmation) async throws -> R
 ) async rethrows -> R {
-  fatalError("Unsupported")
+  swt_unreachable()
 }
 
 /// An overload of ``confirmation(_:expectedCount:isolation:sourceLocation:_:)-l3il``
@@ -218,7 +220,7 @@ public func confirmation<R>(
   sourceLocation: SourceLocation = #_sourceLocation,
   _ body: (Confirmation) async throws -> R
 ) async rethrows -> R {
-  fatalError("Unsupported")
+  swt_unreachable()
 }
 
 /// An overload of ``confirmation(_:expectedCount:isolation:sourceLocation:_:)-l3il``
@@ -234,5 +236,5 @@ public func confirmation<R>(
   sourceLocation: SourceLocation = #_sourceLocation,
   _ body: (Confirmation) async throws -> R
 ) async rethrows -> R {
-  fatalError("Unsupported")
+  swt_unreachable()
 }

Sources/Testing/Traits/TimeLimitTrait.swift

@@ -8,6 +8,8 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
+private import _TestingInternals
+
 /// A type that defines a time limit to apply to a test.
 ///
 /// To add this trait to a test, use ``Trait/timeLimit(_:)-4kzjp``.
@@ -126,55 +128,55 @@ extension TimeLimitTrait.Duration {
   /// This function is unavailable and is provided for diagnostic purposes only.
   @available(*, unavailable, message: "Time limit must be specified in minutes")
   public static func seconds(_ seconds: some BinaryInteger) -> Self {
-    fatalError("Unsupported")
+    swt_unreachable()
   }
 
   /// Construct a time limit duration given a number of seconds.
   ///
   /// This function is unavailable and is provided for diagnostic purposes only.
   @available(*, unavailable, message: "Time limit must be specified in minutes")
   public static func seconds(_ seconds: Double) -> Self {
-    fatalError("Unsupported")
+    swt_unreachable()
   }
 
   /// Construct a time limit duration given a number of milliseconds.
   ///
   /// This function is unavailable and is provided for diagnostic purposes only.
   @available(*, unavailable, message: "Time limit must be specified in minutes")
   public static func milliseconds(_ milliseconds: some BinaryInteger) -> Self {
-    fatalError("Unsupported")
+    swt_unreachable()
   }
 
   /// Construct a time limit duration given a number of milliseconds.
   ///
   /// This function is unavailable and is provided for diagnostic purposes only.
   @available(*, unavailable, message: "Time limit must be specified in minutes")
   public static func milliseconds(_ milliseconds: Double) -> Self {
-    fatalError("Unsupported")
+    swt_unreachable()
   }
 
   /// Construct a time limit duration given a number of microseconds.
   ///
   /// This function is unavailable and is provided for diagnostic purposes only.
   @available(*, unavailable, message: "Time limit must be specified in minutes")
   public static func microseconds(_ microseconds: some BinaryInteger) -> Self {
-    fatalError("Unsupported")
+    swt_unreachable()
   }
 
   /// Construct a time limit duration given a number of microseconds.
   ///
   /// This function is unavailable and is provided for diagnostic purposes only.
   @available(*, unavailable, message: "Time limit must be specified in minutes")
   public static func microseconds(_ microseconds: Double) -> Self {
-    fatalError("Unsupported")
+    swt_unreachable()
   }
 
   /// Construct a time limit duration given a number of nanoseconds.
   ///
   /// This function is unavailable and is provided for diagnostic purposes only.
   @available(*, unavailable, message: "Time limit must be specified in minutes")
   public static func nanoseconds(_ nanoseconds: some BinaryInteger) -> Self {
-    fatalError("Unsupported")
+    swt_unreachable()
   }
 }
 

Sources/_TestingInternals/include/Stubs.h

@@ -16,6 +16,15 @@
 
 SWT_ASSUME_NONNULL_BEGIN
 
+/// Mark a code path as unreachable.
+///
+/// This function is necessary because Swift does not have an equivalent of
+/// `__builtin_unreachable()`.
+__attribute__((always_inline, noreturn))
+static inline void swt_unreachable(void) {
+  __builtin_unreachable();
+}
+
 #if !SWT_NO_FILE_IO
 /// The C file handle type.
 ///

Tests/TestingTests/ExitTestTests.swift

@@ -306,7 +306,7 @@ private import _TestingInternals
 
       await Test {
         try await #require(processExitsWith: .success) {}
-        fatalError("Unreachable")
+        Issue.record("#require(processExitsWith:) should have thrown an error")
       }.run(configuration: configuration)
     }
   }