Harmonize _AttachableImageWrapper and AttachableAs___ across Darwin and Windows. (#1261)

This PR makes some changes to harmonize the `_AttachableImageWrapper`
wrapper type and the `AttachableAsCGImage`/`AttachableAsIWICBitmap`
protocols across Darwin and Windows:

- `_AttachableImageWrapper` is now a class on both platforms, not just
Windows.
- The `_makeCopyForAttachment()` function is now named
`_copyAttachableValue()` (which is a more accurate name already used on
Windows.)
- A default implementation of `_copyAttachableValue()` and of
`_deinitializeAttachableValue()` is provided for `Sendable` types on
Windows.

### 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/Overlays/_Testing_AppKit/Attachments/NSImage+AttachableAsCGImage.swift

@@ -53,7 +53,7 @@ extension NSImage: AttachableAsCGImage {
     return maxRepWidth ?? 1.0
   }
 
-  public func _makeCopyForAttachment() -> Self {
+  public func _copyAttachableValue() -> Self {
     // If this image is of an NSImage subclass, we cannot reliably make a deep
     // copy of it because we don't know what its `init(data:)` implementation
     // might do. Try to make a copy (using NSCopying), but if that doesn't work

Sources/Overlays/_Testing_CoreGraphics/Attachments/AttachableAsCGImage.swift

@@ -65,16 +65,17 @@ public protocol AttachableAsCGImage {
   ///
   /// - Returns: A copy of `self`, or `self` if no copy is needed.
   ///
-  /// Several system image types do not conform to `Sendable`; use this
-  /// function to make copies of such images that will not be shared outside
-  /// of an attachment and so can be generally safely stored.
+  /// The testing library uses this function to take ownership of image
+  /// resources that test authors pass to it. If possible, make a copy of or add
+  /// a reference to `self`. If this type does not support making copies, return
+  /// `self` verbatim.
   ///
   /// The default implementation of this function when `Self` conforms to
   /// `Sendable` simply returns `self`.
   ///
   /// This function is not part of the public interface of the testing library.
   /// It may be removed in a future update.
-  func _makeCopyForAttachment() -> Self
+  func _copyAttachableValue() -> Self
 }
 
 @available(_uttypesAPI, *)
@@ -90,7 +91,7 @@ extension AttachableAsCGImage {
 
 @available(_uttypesAPI, *)
 extension AttachableAsCGImage where Self: Sendable {
-  public func _makeCopyForAttachment() -> Self {
+  public func _copyAttachableValue() -> Self {
     self
   }
 }

Sources/Overlays/_Testing_CoreGraphics/Attachments/_AttachableImageWrapper.swift

@@ -54,20 +54,20 @@ import UniformTypeIdentifiers
 ///   (iOS, watchOS, tvOS, visionOS, and Mac Catalyst)
 @_spi(Experimental)
 @available(_uttypesAPI, *)
-public struct _AttachableImageWrapper<Image>: Sendable where Image: AttachableAsCGImage {
+public final class _AttachableImageWrapper<Image>: Sendable where Image: AttachableAsCGImage {
   /// The underlying image.
   ///
   /// `CGImage` and `UIImage` are sendable, but `NSImage` is not. `NSImage`
   /// instances can be created from closures that are run at rendering time.
   /// The AppKit cross-import overlay is responsible for ensuring that any
   /// instances of this type it creates hold "safe" `NSImage` instances.
-  nonisolated(unsafe) var image: Image
+  nonisolated(unsafe) let image: Image
 
   /// The image format to use when encoding the represented image.
-  var imageFormat: AttachableImageFormat?
+  let imageFormat: AttachableImageFormat?
 
   init(image: Image, imageFormat: AttachableImageFormat?) {
-    self.image = image._makeCopyForAttachment()
+    self.image = image._copyAttachableValue()
     self.imageFormat = imageFormat
   }
 }
@@ -80,7 +80,7 @@ extension _AttachableImageWrapper: AttachableWrapper {
     image
   }
 
-  public func withUnsafeBytes<R>(for attachment: borrowing Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+  public func withUnsafeBytes<R>(for attachment: borrowing Attachment<_AttachableImageWrapper>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     let data = NSMutableData()
 
     // Convert the image to a CGImage.
@@ -116,7 +116,7 @@ extension _AttachableImageWrapper: AttachableWrapper {
     }
   }
 
-  public borrowing func preferredName(for attachment: borrowing Attachment<Self>, basedOn suggestedName: String) -> String {
+  public borrowing func preferredName(for attachment: borrowing Attachment<_AttachableImageWrapper>, basedOn suggestedName: String) -> String {
     let contentType = AttachableImageFormat.computeContentType(for: imageFormat, withPreferredName: suggestedName)
     return (suggestedName as NSString).appendingPathExtension(for: contentType)
   }

Sources/Overlays/_Testing_CoreImage/Attachments/CIImage+AttachableAsCGImage.swift

@@ -23,7 +23,7 @@ extension CIImage: AttachableAsCGImage {
     }
   }
 
-  public func _makeCopyForAttachment() -> Self {
+  public func _copyAttachableValue() -> Self {
     // CIImage is documented as thread-safe, but does not conform to Sendable.
     // It conforms to NSCopying but does not actually copy itself, so there's no
     // point in calling copy().

Sources/Overlays/_Testing_WinSDK/Attachments/AttachableAsIWICBitmap.swift

@@ -138,6 +138,9 @@ public protocol AttachableAsIWICBitmap {
   /// a reference to `self`. If this type does not support making copies, return
   /// `self` verbatim.
   ///
+  /// The default implementation of this function when `Self` conforms to
+  /// `Sendable` simply returns `self`.
+  ///
   /// This function is not part of the public interface of the testing library.
   /// It may be removed in a future update.
   func _copyAttachableValue() -> Self
@@ -151,6 +154,9 @@ public protocol AttachableAsIWICBitmap {
   /// This function is not responsible for releasing the image returned from
   /// `_copyAttachableIWICBitmap(using:)`.
   ///
+  /// The default implementation of this function when `Self` conforms to
+  /// `Sendable` does nothing.
+  ///
   /// This function is not part of the public interface of the testing library.
   /// It may be removed in a future update.
   func _deinitializeAttachableValue()
@@ -190,4 +196,12 @@ extension AttachableAsIWICBitmap {
     }
   }
 }
+
+extension AttachableAsIWICBitmap where Self: Sendable {
+  public func _copyAttachableValue() -> Self {
+    self
+  }
+
+  public func _deinitializeAttachableValue() {}
+}
 #endif

Sources/Overlays/_Testing_WinSDK/Attachments/AttachableImageFormat+CLSID.swift

@@ -112,7 +112,7 @@ extension AttachableImageFormat {
         if ext.starts(with: ".") {
           ext.dropFirst(1)
         } else {
-          ext[...]
+          ext
         }
       }.map(String.init)
   }