Eagerly move attachable values to the heap. (#809)

This PR modifies `Test.Attachment.init(...)` so that, if the attachable
value passed to it is of a large or non-bitwise-copyable value type, we
store it in a heap-allocated container object.

Why do we want to do this? Attachable values have arbitrary types we
don't really know anything about, and may be very expensive to copy if
they are large or if they contain many references to other objects.
Since attachments are sendable and need to pass through many layers in
the system, the cost of making copies for these attachable values can
add up quickly. So, instead of copying them repeatedly, if we store them
in a refcounted container and pass _that_ value around, we only infer a
single copy cost.

There are four modes for attachable value storage after this PR:

```mermaid
flowchart TB;
    S@{ shape: diam, label: "Sendable?" };
    C@{ shape: diam, label: "Copyable?" };
    AO@{ shape: diam, label: "AnyObject?" };
    BC@{ shape: diam, label: "BitwiseCopyable (POD)?" };
    SMOL@{ shape: diam, label: "Fits in an existential box?" };

    MO@{ shape: das, label: "In a heap-allocated box\n(eagerly serialized)" };
    EX@{ shape: das,  label: "Inline in an existential box" };
    H@{ shape: das,  label: "In a heap-allocated box" };
    RC@{ shape: das,  label: "Directly on the heap" };

    S-- Yes ---C
        C-- Yes ---AO
            AO-- Yes ---RC
            AO-- No ---BC
                BC-- Yes ---SMOL
                BC-- No ---H
                    SMOL-- Yes ---EX
                    SMOL-- No ---H
        C-- No ---MO
    S-- No ---MO
```

### 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/Attachments/Test.Attachment.swift

@@ -68,7 +68,11 @@ extension Test {
       named preferredName: String? = nil,
       sourceLocation: SourceLocation = #_sourceLocation
     ) {
-      self.attachableValue = attachableValue
+      if _shouldMoveValueToHeap(attachableValue) {
+        self.attachableValue = _HeapAllocatedAttachableProxy(rawValue: attachableValue)
+      } else {
+        self.attachableValue = attachableValue
+      }
       self.preferredName = preferredName ?? Self.defaultPreferredName
       self.sourceLocation = sourceLocation
     }
@@ -95,10 +99,71 @@ extension Test.Attachment {
   }
 }
 
+// MARK: - Heap allocation optimizations
+
+/// A type that stands in for an attachable value of value type (as opposed to
+/// reference type.)
+///
+/// We don't know the in-memory layout of an attachable value; it may be very
+/// expensive to make the typical copies Swift makes over the course of a test
+/// run if a value is large or contains lots of references to objects. So we
+/// eagerly move attachments of value type to the heap by ensconcing them in
+/// instances of this type.
+private final class _HeapAllocatedAttachableProxy<RawValue>: RawRepresentable, Test.Attachable, Sendable where RawValue: Test.Attachable & Sendable {
+  let rawValue: RawValue
+
+  init(rawValue: RawValue) {
+    self.rawValue = rawValue
+  }
+
+  var estimatedAttachmentByteCount: Int? {
+    rawValue.estimatedAttachmentByteCount
+  }
+
+  func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+    try rawValue.withUnsafeBufferPointer(for: attachment, body)
+  }
+}
+
+/// Whether or not an attachable value should be moved to the heap when adding
+/// it to an attachment.
+///
+/// - Parameters:
+///   - attachableValue: The value that is being attached.
+///
+/// - Returns: Whether or not `attachableValue` should be boxed in an instance
+///   of `_HeapAllocatedAttachableProxy`.
+private func _shouldMoveValueToHeap<T>(_ attachableValue: borrowing T) -> Bool where T: Test.Attachable {
+  // Do not (redundantly) move existing heap-allocated objects to the heap.
+  if T.self is AnyClass {
+    return false
+  }
+
+  // Do not move small POD value types to the heap.
+  //
+  // _isPOD() is defined in the standard library and is approximately equivalent
+  // to testing for conformance to BitwiseCopyable, but it's a marker protocol
+  // which means we can't test for conformance in a generic context.
+  //
+  // The size limit used is the size of an existential box's inline storage (see
+  // NumWords_ValueBuffer in the Swift repository.) Such values can be directly
+  // stored inside an `Attachment` and are cheap to copy.
+  if _isPOD(T.self) && MemoryLayout<T>.stride <= (MemoryLayout<Int>.stride * 3) {
+    return false
+  }
+
+  return true
+}
+
 // MARK: - Non-sendable and move-only attachments
 
-/// A type that stands in for an attachable type that is not also sendable.
-private struct _AttachableProxy: Test.Attachable, Sendable {
+/// A type that stands in for an attachable value that is not also sendable.
+///
+/// This type is a value type so that we can mutate its properties while
+/// transferring information from the original attachable value. Consequently,
+/// instances will be boxed in an instance of `_HeapAllocatedAttachableProxy`
+/// when they are used to initialize instances of ``Test/Attachment``.
+private struct _EagerlyCopiedAttachableProxy: Test.Attachable, Sendable {
   /// The result of `withUnsafeBufferPointer(for:_:)` from the original
   /// attachable value.
   var encodedValue = [UInt8]()
@@ -135,7 +200,7 @@ extension Test.Attachment {
     named preferredName: String? = nil,
     sourceLocation: SourceLocation = #_sourceLocation
   ) {
-    var proxyAttachable = _AttachableProxy()
+    var proxyAttachable = _EagerlyCopiedAttachableProxy()
     proxyAttachable.estimatedAttachmentByteCount = attachableValue.estimatedAttachmentByteCount
 
     // BUG: the borrow checker thinks that withErrorRecording() is consuming

Tests/TestingTests/AttachmentTests.swift

@@ -199,6 +199,58 @@ struct AttachmentTests {
     }
   }
 
+  @Test func attachRefCountedValue() throws {
+    let attachableValue = MySendableAttachableWithRefcountedSemantics(values: (1, 2, 3))
+    let attachment = Test.Attachment(attachableValue, named: "loremipsum")
+
+    #expect(attachment.attachableValue is MySendableAttachableWithRefcountedSemantics)
+    #expect(attachment.attachableValue.estimatedAttachmentByteCount == attachableValue.estimatedAttachmentByteCount)
+    try attachment.attachableValue.withUnsafeBufferPointer(for: attachment) { buffer in
+      withUnsafeBytes(of: (1, 2, 3)) { buffer2 in
+        #expect(buffer.elementsEqual(buffer2))
+      }
+    }
+  }
+
+  @Test func attachSmallPODValue() throws {
+    let attachableValue = MySendableAttachableWithSmallPODSemantics(values: (1, 2, 3))
+    let attachment = Test.Attachment(attachableValue, named: "loremipsum")
+
+    #expect(!(type(of: attachment.attachableValue) is AnyClass))
+    #expect(attachment.attachableValue.estimatedAttachmentByteCount == attachableValue.estimatedAttachmentByteCount)
+    try attachment.attachableValue.withUnsafeBufferPointer(for: attachment) { buffer in
+      withUnsafeBytes(of: (1, 2, 3)) { buffer2 in
+        #expect(buffer.elementsEqual(buffer2))
+      }
+    }
+  }
+
+  @Test func attachBigPODValue() throws {
+    let attachableValue = MySendableAttachableWithBigPODSemantics(values: (1, 2, 3, 4, 5, 6))
+    let attachment = Test.Attachment(attachableValue, named: "loremipsum")
+
+    #expect(type(of: attachment.attachableValue) is AnyClass)
+    #expect(attachment.attachableValue.estimatedAttachmentByteCount == attachableValue.estimatedAttachmentByteCount)
+    try attachment.attachableValue.withUnsafeBufferPointer(for: attachment) { buffer in
+      withUnsafeBytes(of: (1, 2, 3, 4, 5, 6)) { buffer2 in
+        #expect(buffer.elementsEqual(buffer2))
+      }
+    }
+  }
+
+  @Test func attachNonPODValue() throws {
+    let attachableValue = MySendableAttachableWithNonPODSemantics(values: (1, 2, 3))
+    let attachment = Test.Attachment(attachableValue, named: "loremipsum")
+
+    #expect(type(of: attachment.attachableValue) is AnyClass)
+    #expect(attachment.attachableValue.estimatedAttachmentByteCount == attachableValue.estimatedAttachmentByteCount)
+    try attachment.attachableValue.withUnsafeBufferPointer(for: attachment) { buffer in
+      withUnsafeBytes(of: (1, 2, 3)) { buffer2 in
+        #expect(buffer.elementsEqual(buffer2))
+      }
+    }
+  }
+
   @Test func issueRecordedWhenAttachingNonSendableValueThatThrows() async {
     await confirmation("Attachment detected") { valueAttached in
       await confirmation("Issue recorded") { issueRecorded in
@@ -322,13 +374,39 @@ struct MySendableAttachable: Test.Attachable, Sendable {
   }
 }
 
-struct MySendableAttachableWithDefaultByteCount: Test.Attachable, Sendable {
-  var string: String
+final class MySendableAttachableWithRefcountedSemantics: Test.Attachable, Sendable {
+  let values: (Int, Int, Int)
+
+  init(values: (Int, Int, Int)) {
+    self.values = values
+  }
 
   func withUnsafeBufferPointer<R>(for attachment: borrowing Testing.Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
-    var string = string
-    return try string.withUTF8 { buffer in
-      try body(.init(buffer))
-    }
+    try withUnsafeBytes(of: values, body)
+  }
+}
+
+struct MySendableAttachableWithSmallPODSemantics: Test.Attachable, Sendable {
+  var values: (Int, Int, Int)
+
+  func withUnsafeBufferPointer<R>(for attachment: borrowing Testing.Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+    try withUnsafeBytes(of: values, body)
+  }
+}
+
+struct MySendableAttachableWithBigPODSemantics: Test.Attachable, Sendable {
+  var values: (Int, Int, Int, Int, Int, Int)
+
+  func withUnsafeBufferPointer<R>(for attachment: borrowing Testing.Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+    try withUnsafeBytes(of: values, body)
+  }
+}
+
+struct MySendableAttachableWithNonPODSemantics: Test.Attachable, Sendable {
+  var values: (Int, Int, Int)
+  var makeItComplicated = "it's complicated"
+
+  func withUnsafeBufferPointer<R>(for attachment: borrowing Testing.Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+    try withUnsafeBytes(of: values, body)
   }
 }