Merge pull request #2395 from nate-chandler/bitwise-copyable-updates

[BitwiseCopyable] Post-review changes.

Author: allevato

proposals/0426-bitwise-copyable.md

@@ -17,11 +17,11 @@
 
 ## Introduction
 
-We propose a new marker protocol `BitwiseCopyable` that can be conformed to by types that can be moved or copied with direct calls to `memcpy` and which require no special destroy operation[^1].
+We propose a new, [limited](#limitations) protocol `BitwiseCopyable` that _can_ be conformed to by types that are "bitwise-copyable"[^1]--that is, that can be moved or copied with direct calls to `memcpy` and which require no special destroy operation.
 When compiling generic code with such constraints, the compiler can emit these efficient operations directly, only requiring minimal overhead to look up the size of the value at runtime.
 Alternatively, developers can use this constraint to selectively provide high-performance variations of specific operations, such as bulk copying of a container.
 
-[^1]: The term "trivial" is used in [SE-138](0138-unsaferawbufferpointer.md) and [SE-0370](0370-pointer-family-initialization-improvements.md) to refer to types with the property above. The discussion below will explain why certain generic or exported types that are trivial will not in fact be `BitwiseCopyable`.
+[^1]: The term "trivial" is used in [SE-138](0138-unsaferawbufferpointer.md) and [SE-0370](0370-pointer-family-initialization-improvements.md) to refer to types with this property. The discussion below will explain why certain generic or exported types that are bitwise-copyable will not in fact be `BitwiseCopyable`.
 
 ## Motivation
 
@@ -57,12 +57,15 @@ We add a new protocol `BitwiseCopyable` to the standard library:
 @_marker public protocol BitwiseCopyable {}
 ```
 
+That a type conforms to the protocol [implies](#transient-and-permanent) that the type is bitwise-copyable; the reverse is _not_ true.
+
 Many basic types in the standard library will conformed to this protocol.
 
 Developer's own types may be conformed to the protocol, as well.
 The compiler will check any such conformance and emit a diagnostic if the type contains elements that are not `BitwiseCopyable`.
 
-Furthermore, when building a module, the compiler will infer conformance to `BitwiseCopyable` for any non-exported struct or enum defined within the module whose stored members are all `BitwiseCopyable`.
+Furthermore, when building a module, the compiler will infer conformance to `BitwiseCopyable` for any non-exported struct or enum defined within the module whose stored members are all `BitwiseCopyable`,
+except those for which conformance is explicitly [suppressed](#suppression).
 
 Developers cannot conform types defined in other modules to the protocol.
 
@@ -148,7 +151,7 @@ When the module containing the type is built, if all of the type's fields are `B
 
 For generic types, a conformance will only be inferred if its fields unconditionally conform to `BitwiseCopyable`.
 In the `RegularBox` example above, a conditional conformance will not be inferred.
-If this is desired, the developer can explicitly write the conditional conformance.
+If such a conformance is desired, the developer must explicitly write the conditional conformance.
 
 [^2]: This includes raw-value enums.  While such enums do include a conformance to `RawRepresentable` where `RawValue` could be a non-conforming type (`String`), the instances of the enums themselves are `BitwiseCopyable`.
 
@@ -162,7 +165,7 @@ For an imported C struct, if all its fields are `BitwiseCopyable`, the compiler
 The same is true for an imported C++ struct or class, unless the type is non-trivial[^3].
 
 For an imported C or C++ struct, if any of its fields cannot be represented in Swift, the compiler will not generate a conformance.
-This can be overridden, however, by annotating the type `__attribute__((__swift_attr__("_BitwiseCopyable")))`.
+This can be overridden, however, by annotating the type `__attribute__((__swift_attr__("BitwiseCopyable")))`.
 
 [^3]: A C++ type is considered non-trivial (for the purpose of calls, as defined by the Itanium ABI) if any of the following is non-default: its constructor; its copy-constructor; its destructor.
 
@@ -180,26 +183,65 @@ For example, the compiler will infer a conformance of the following struct
 ```swift
 @frozen
 public struct Coordinate3 {
-  var x: Int
-  var y: Int
+  public var x: Int
+  public var y: Int
 }
 ```
 to `BitwiseCopyable`.
 
-### Suppressing inferred conformance
+### Suppressing inferred conformance<a name="suppression"/>
 
-To suppress the inference of `BitwiseCopyable`, a conformance can explicitly be made unavailable:
+To suppress the inference of `BitwiseCopyable`, `~BitwiseCopyable` can be added to the type's inheritance list.
 
+```swift
+struct Coordinate4 : ~BitwiseCopyable {...}
 ```
-@available(*, unavailable)
-extension Coordinate4 : BitwiseCopyable {}
-```
+
+Suppression must be declared on the type declaration itself, not on an extension.
+
+### Transient and permanent notions<a name="transient-and-permanent"/>
+
+The Swift runtime already describes[^4] whether a type is bitwise-copyable.
+It is surfaced, among other places, in the standard library function `_isPOD`[^5].
+
+[^4]: The `IsNonPOD` value witness flag is set for every type that is _not_ bitwise-copyable.
+
+[^5]: "POD" here is an acronym for "plain old data" which is yet another name for the notion of bitwise-copyable or trivial.
+
+If a type conforms to `BitwiseCopyable`, then `_isPOD` must be true for the type.
+The converse is not true, however.
+
+As a type evolves, it may [both gain _and_ lose bitwise-copyability](#fluctuating-bitwise-copyability).
+A type may only _gain_ a conformance to `BitwiseCopyable`, however;
+it cannot _lose_ its conformance without breaking source and ABI.
+
+The two notions are related, but distinct:
+That a type `_isPOD` is a statement that the type is currently bitwise-copyable.
+That a type conforms to `BitwiseCopyable` is a promise that the type is now and will remain bitwise-copyable as the library evolves.
+In other words returning true from `_isPOD` is a transient property, and conformance to `BitwiseCopyable` is a permanent one.
+
+For this reason, conformance to `BitwiseCopyable` is not inherent.
+Its declaration on a public type provides a guarantee that the compiler cannot infer.
+
+### Limitations of BitwiseCopyable<a name="limitations"/>
+
+Being declared with `@_marker`, `BitwiseCopyable` is a limited protocol.
+Its limited nature allows the protocol's runtime behavior to be defined later, as needed.
+
+1. `BitwiseCopyable` cannot be extended.
+This limitation is similar to that on `Sendable` and `Any`:
+it prevents polluting the namespace of conforming types, especially types whose conformance is inferred.
+
+2. Because conformance to `BitwiseCopyable` is distinct from being bitwise-copyable,
+the runtime cannot use the `IsNonPOD` bit as a proxy for conformance (although actual [conformance could be ignored](#casting-by-duck-typing)).
+A separate mechanism would be necessary.
+Until such a mechanism is added, `is`, `as?` and usage as a generic constraint to enable conditional conformance to another protocol is not possible.
 
 ### Standard library API improvements
 
 The standard library includes a load method on both `UnsafeRawPointer` and `UnsafeMutableRawPointer`
 
-```
+```swift
 @inlinable
 @_alwaysEmitIntoClient
 public func loadUnaligned<T>(
@@ -210,7 +252,7 @@ public func loadUnaligned<T>(
 
 and a corresponding write method on `UnsafeMutableRawPointer`
 
-```
+```swift
 @inlinable
 @_alwaysEmitIntoClient
 public func storeBytes<T>(
@@ -222,7 +264,7 @@ that must be called with a trivial `T`.
 
 We propose adding overloads of these methods to constrain the value to `BitwiseCopyable`:
 
-```
+```swift
 // on both UnsafeRawPointer and UnsafeMutableRawPointer
 @inlinable
 @_alwaysEmitIntoClient
@@ -241,6 +283,8 @@ public func storeBytes<T : BitwiseCopyable>(
 
 This allows for optimal code generation because `memcpy` instead of value witnesses can be used.
 
+Additionally, we propose deprecating the original, unconstrained overloads of `loadUnaligned` and `storeBytes`.
+
 ## Effect on ABI stability
 
 The addition of the `BitwiseCopyable` constraint to either a type or a protocol in a library will not cause an ABI break for users.
@@ -249,7 +293,7 @@ The addition of the `BitwiseCopyable` constraint to either a type or a protocol
 
 This addition of a new protocol will not impact existing source code that does not use it.
 
-Removing the `BitwiseCopyable` marker from a type is source-breaking.
+Removing the `BitwiseCopyable` conformance from a type is source-breaking.
 As a result, future versions of Swift may conform additional existing types to `BitwiseCopyable`, but will not remove it from any type already conforming to `BitwiseCopyable`.
 
 ## Effect on API resilience
@@ -278,10 +322,42 @@ extension Box : BitwiseCopyable where Value : BitwiseCopyable {}
 
 In the future we may in some cases be able to derive it automatically.
 
-### MemoryLayout<T>.isBitwiseCopyable
+### Dynamic casting
+
+Being a [limited](#limitations) protocol, `BitwiseCopyable` does not currently have any runtime representation.
+While a type's [transient](#transient-and-permanent) bitwise-copyability has a preexisting runtime representation, that is different from the type conforming to `BitwiseCopyable`.
+
+Being a low-level, performance-enabling feature, it is not clear that dynamic casting should be allowed at all.
+If it were to be allowed at some point, a few different approaches can already be foreseen:
+
+#### Explicitly record a type's conformance
+
+The standard way to support dynamic casting would be to represent a type's conformance to the protocol and query the type at runtime.
+
+This approach has the virtue that dynamic casting behaves as usual.
+A type could only be cast to `BitwiseCopyable` if it actually conformed to the protocol.
+For example, casting a type which suppressed a conformance to `BitwiseCopyable` would fail.
+
+If this approach were taken, such casting could be back-deployed as far as the oldest OS in which this runtime representation was added.
+Further back deployment would be possible by adding conformance records to back deployed binaries.
 
-In certain circumstances, it would be useful to be able to dynamically determine whether a type conforms to `BitwiseCopyable`.
-In order to allow that, a new field could be added to `MemoryLayout`.
+#### Duck typing for BitwiseCopyable<a name="casting-by-duck-typing"/>
+
+An alternative would be to dynamically treat any type that's bitwise-copyable as if it conformed to `BitwiseCopyable`.
+
+This is quite different from typical Swift casting behavior.
+Rather than relying on a permanent characteristic of the type, it would rely on a [transient](#transient-and-permanent) one.
+This would be visible to the programmer in several ways:
+- different overloads would be selected for a value of concrete type from those selected for a value dynamically cast to `BitwiseCopyable`
+- dynamic casts to `BitwiseCopyable` could fail, then succeed, then fail again in successive OS versions
+
+On the other hand, these behavioral differences may be desireable.
+
+Considering that this approach would just ignore the existence of conformances to `BitwiseCopyable`,
+it would be reasonable to ignore the existence of a suppressed conformance as well.
+
+This approach also has the virtue of being completely back-deployable[^6].
+[^6]: All runtimes have had the `IsNonPOD` bit.
 
 ### BitwiseMovable
 
@@ -297,7 +373,7 @@ typealias BitwiseCopyable = Bitwise & Copyable & DefaultDeinit
 ```
 Such a definition remains possible after this proposal.
 
-Because `BitwiseCopyable` is a marker protocol, its ABI is rather limited.
+Because `BitwiseCopyable` is annotated `@_marker`, its ABI is rather limited.
 Specifically, it only affects name mangling.
 If, in a subsequent proposal, the protocol were redefined as a composition, symbols into which `BitwiseCopyable` was mangled could still be mangled in the same way, ensuring ABI compatibility.
 
@@ -356,3 +432,53 @@ The following types in the standard library will gain the `BitwiseCopyable` cons
 - `Hasher`
 - `ObjectIdentifier`
 - `Duration`
+
+## Appendix: Fluctuating bitwise-copyability<a name="fluctuating-bitwise-copyability"/>
+
+Let's say the following type is defined in a framework built with library evolution.
+
+```swift
+public struct Dish {...}
+```
+
+In the first version of the framework, the type only contains bitwise-copyable fields:
+
+```swift
+/// NoodleKit v1.0
+
+public struct Dish {
+  public let substrate: Noodle
+  public let isTopped: Bool
+}
+```
+
+So in version `1.0`, the type is bitwise-copyable.
+
+In the next version of the framework, to expose more information to its clients, the stored `Bool` is replaced with a stored `Array`:
+
+```swift
+/// NoodleKit v1.1
+
+public struct Dish {
+  public let substrate: Noodle
+  public let toppings: [Topping]
+  public let isTopped: Bool { toppings.count > 0 }
+}
+```
+
+As a result, in version `1.1`, the type is _not_ bitwise-copyable.
+
+In a subsequent version, as an optimization, the stored `Array` is replaced with an `OptionSet`
+
+```swift
+/// NoodleKit v2.0
+
+public struct Dish {
+  public let substrate: Noodle
+  private let toppingOptions: Topping
+  public let toppings: [Topping] { ... }
+  public let isTopped: Bool { toppings.count > 0 }
+}
+```
+
+In release `2.0` the type is once again bitwise-copyable.