Add UnsafeRawPointer type and API. (#3677)

* Add UnsafeRawPointer type and API.

As proposed in SE-0107:   UnsafeRawPointer.
https://github.com/apple/swift-evolution/blob/master/proposals/0107-unsaferawpointer.md

The fundamental difference between Unsafe[Mutable]RawPointer and
Unsafe[Mutable]Pointer<Pointee> is simply that the former is used for "untyped"
memory access, and the later is used for "typed" memory access. Let's refer to
these as "raw pointers" and "typed pointers". Because operations on raw pointers
access untyped memory, the compiler cannot make assumptions about the underlying
type of memory and must be conservative. With operations on typed pointers, the
compiler may make strict assumptions about the type of the underlying memory,
which allows more aggressive optimization.

Memory can only be accessed by a typed pointer when it is currently
bound to the Pointee type. Memory can be bound to type `T` via:
- `UnsafePointer<T>.allocate(capacity: n)`
- `UnsafePointer<Pointee>.withMemoryRebound(to: T.self, capacity: n) {...}`
- `UnsafeMutableRawPointer.initializeMemory(as: T.self, at: i, count: n, to: x)`
- `UnsafeMutableRawPointer.initializeMemory(as: T.self, from: p, count: n)`
- `UnsafeMutableRawPointer.moveInitializeMemory(as: T.self, from: p, count: n)`
- `UnsafeMutableRawPointer.bindMemory(to: T.self, capacity: n)`

Mangle UnsafeRawPointer as predefined substitution 'Sv' for Swift void
pointer ([urp] are taken).

* UnsafeRawPointer minor improvements.

Incorporate Dmitri's feedback.

Properly use a _memmove helper.

Add load/storeBytes alignment precondition checks.

Reword comments.

Demangler tests.

* Fix name mangling test cases.

* Fix bind_memory specialization.

Author: atrick

docs/ABI.rst

@@ -1221,6 +1221,8 @@ Predefined Substitutions
   known-nominal-type ::= 'Sd'                // Swift.Float64
   known-nominal-type ::= 'Sf'                // Swift.Float32
   known-nominal-type ::= 'Si'                // Swift.Int
+  known-nominal-type ::= 'SV'                // Swift.UnsafeRawPointer
+  known-nominal-type ::= 'Sv'                // Swift.UnsafeMutableRawPointer
   known-nominal-type ::= 'SP'                // Swift.UnsafePointer
   known-nominal-type ::= 'Sp'                // Swift.UnsafeMutablePointer
   known-nominal-type ::= 'SQ'                // Swift.ImplicitlyUnwrappedOptional

include/swift/SIL/SILCloner.h

@@ -796,7 +796,7 @@ SILCloner<ImplClass>::visitBindMemoryInst(BindMemoryInst *Inst) {
     getBuilder().createBindMemory(getOpLocation(Inst->getLoc()),
                                   getOpValue(Inst->getBase()),
                                   getOpValue(Inst->getIndex()),
-                                  Inst->getBoundType()));
+                                  getOpType(Inst->getBoundType())));
 }
 
 template<typename ImplClass>

lib/AST/Mangle.cpp

@@ -1392,6 +1392,12 @@ bool Mangler::tryMangleStandardSubstitution(const NominalTypeDecl *decl) {
   } else if (name == "Float") {
     Buffer << "Sf";
     return true;
+  } else if (name == "UnsafeRawPointer") {
+    Buffer << "SV";
+    return true;
+  } else if (name == "UnsafeMutableRawPointer") {
+    Buffer << "Sv";
+    return true;
   } else if (name == "UnsafePointer") {
     Buffer << "SP";
     return true;

lib/Basic/Demangle.cpp

@@ -1037,6 +1037,10 @@ class Demangler {
       return createSwiftType(Node::Kind::Structure, "Float");
     if (Mangled.nextIf('i'))
       return createSwiftType(Node::Kind::Structure, "Int");
+    if (Mangled.nextIf('V'))
+      return createSwiftType(Node::Kind::Structure, "UnsafeRawPointer");
+    if (Mangled.nextIf('v'))
+      return createSwiftType(Node::Kind::Structure, "UnsafeMutableRawPointer");
     if (Mangled.nextIf('P'))
       return createSwiftType(Node::Kind::Structure, "UnsafePointer");
     if (Mangled.nextIf('p'))

lib/Basic/Remangle.cpp

@@ -354,6 +354,8 @@ bool Remangler::trySubstitution(Node *node, SubstitutionEntry &entry) {
       SUCCESS_IF_DECLNAME_IS("Double", "Sd");
       SUCCESS_IF_DECLNAME_IS("Float", "Sf");
       SUCCESS_IF_DECLNAME_IS("Int", "Si");
+      SUCCESS_IF_DECLNAME_IS("UnsafeRawPointer", "SV");
+      SUCCESS_IF_DECLNAME_IS("UnsafeMutableRawPointer", "Sv");
       SUCCESS_IF_DECLNAME_IS("UnsafePointer", "SP");
       SUCCESS_IF_DECLNAME_IS("UnsafeMutablePointer", "Sp");
       SUCCESS_IF_DECLNAME_IS("UnsafeBufferPointer", "SR");

stdlib/public/core/CMakeLists.txt

@@ -121,6 +121,7 @@ set(SWIFTLIB_ESSENTIAL
   UnsafeBitMap.swift
   UnsafeBufferPointer.swift.gyb
   UnsafePointer.swift.gyb
+  UnsafeRawPointer.swift.gyb
   WriteBackMutableSlice.swift
   )
 

stdlib/public/core/CTypes.swift

@@ -199,6 +199,24 @@ func _memcpy(
     /*volatile:*/ false._value)
 }
 
+/// Copy `count` bytes of memory from `src` into `dest`.
+///
+/// The memory regions `source..<source + count` and
+/// `dest..<dest + count` may overlap.
+func _memmove(
+  dest destination: UnsafeMutableRawPointer,
+  src: UnsafeRawPointer,
+  size: UInt
+) {
+  let dest = destination._rawValue
+  let src = src._rawValue
+  let size = UInt64(size)._value
+  Builtin.int_memmove_RawPointer_RawPointer_Int64(
+    dest, src, size,
+    /*alignment:*/ Int32()._value,
+    /*volatile:*/ false._value)
+}
+
 @available(*, unavailable, renamed: "OpaquePointer")
 public struct COpaquePointer {}
 

stdlib/public/core/GroupInfo.json

@@ -115,6 +115,7 @@
   "Pointer": [
     "Pointer.swift",
     "UnsafePointer.swift",
+    "UnsafeRawPointer.swift",
     "UnsafeBufferPointer.swift"
   ],
   "Protocols": [

stdlib/public/core/ManagedBuffer.swift

@@ -117,7 +117,7 @@ public class ManagedBuffer<Header, Element>
   /// Destroy the stored Header.
   deinit {
     ManagedBufferPointer(self).withUnsafeMutablePointerToHeader {
-      $0.deinitialize()
+      _ = $0.deinitialize()
     }
   }
 

stdlib/public/core/UnsafePointer.swift.gyb

@@ -129,8 +129,10 @@ public struct ${Self}<Pointee>
   static public func allocate(capacity count: Int)
     -> UnsafeMutablePointer<Pointee> {
     let size = strideof(Pointee.self) * count
-    return UnsafeMutablePointer(
-      Builtin.allocRaw(size._builtinWordValue, Builtin.alignof(Pointee.self)))
+    let rawPtr =
+      Builtin.allocRaw(size._builtinWordValue, Builtin.alignof(Pointee.self))
+    Builtin.bindMemory(rawPtr, count._builtinWordValue, Pointee.self)
+    return UnsafeMutablePointer(rawPtr)
   }
 
   /// Deallocate uninitialized memory allocated for `count` instances
@@ -169,7 +171,8 @@ public struct ${Self}<Pointee>
   /// Initialize `self.pointee` with `count` consecutive copies of `newValue`
   ///
   /// - Precondition: The pointee is not initialized.
-  ///             `count` is non-negative.
+  ///
+  /// - Precondition: `count` is non-negative.
   ///
   /// - Postcondition: The pointee is initialized; the value should eventually
   ///   be destroyed or moved from to avoid leaks.
@@ -262,8 +265,7 @@ public struct ${Self}<Pointee>
   }
 
   /// Initialize memory starting at `self` with `count` `Pointee`s
-  /// beginning at `source`, proceeding forward from `self` to `self +
-  /// count - 1`.
+  /// beginning at `source`.
   ///
   /// - Precondition: `count >= 0`
   ///
@@ -320,7 +322,7 @@ public struct ${Self}<Pointee>
   ///   are uninitialized.
   public func moveAssign(from source: ${Self}, count: Int) {
     _debugPrecondition(
-      count >= 0, "${Self}.moveAssignFrom with negative count")
+      count >= 0, "${Self}.moveAssign(from:) with negative count")
     _debugPrecondition(
       self + count <= source || source + count <= self,
       "moveAssign overlapping range")
@@ -336,18 +338,40 @@ public struct ${Self}<Pointee>
   /// De-initialize the `count` `Pointee`s starting at `self`, returning
   /// their memory to an uninitialized state.
   ///
+  /// Returns an UnsafeMutableRawPointer to this memory.
+  ///
   /// - Precondition: The `Pointee`s at `self..<self + count` are
   ///   initialized.
   ///
   /// - Postcondition: The memory is uninitialized.
-  public func deinitialize(count: Int = 1) {
+  @discardableResult
+  public func deinitialize(count: Int = 1) -> UnsafeMutableRawPointer {
     _debugPrecondition(count >= 0, "${Self}.deinitialize with negative count")
     // FIXME: optimization should be implemented, where if the `count` value
     // is 1, the `Builtin.destroy(Pointee.self, _rawValue)` gets called.
     Builtin.destroyArray(Pointee.self, _rawValue, count._builtinWordValue)
+    return UnsafeMutableRawPointer(self)
   }
 %  end
 
+  /// Rebind memory at `self` to type `T` with capacity to hold `count` adjacent
+  /// `T` values while executing the `body` closure. After executing the
+  /// closure, rebind memory back to `Pointee`.
+  ///
+  /// - Precondition: Type 'T' is layout compatible with type 'Pointee'.
+  ///
+  /// - Precondition: The memory `self..<self + count * strideof(T.self)`
+  ///   is bound to `Pointee`.
+  public func withMemoryRebound<T, Result>(to: T.Type, capacity count: Int,
+    _ body: @noescape (UnsafeMutablePointer<T>) throws -> Result
+  ) rethrows -> Result {
+    Builtin.bindMemory(_rawValue, count._builtinWordValue, T.self)
+    defer {
+      Builtin.bindMemory(_rawValue, count._builtinWordValue, Pointee.self)
+    }
+    return try body(UnsafeMutablePointer<T>(_rawValue))
+  }
+
   /// Access the pointee at `self + i`.
   ///
   /// - Precondition: the pointee at `self + i` is initialized.
@@ -381,7 +405,7 @@ public struct ${Self}<Pointee>
   ///   different invocations of the same program.  Do not persist the
   ///   hash value across program runs.
   public var hashValue: Int {
-    return Int(Builtin.ptrtoint_Word(_rawValue))
+    return Int(bitPattern: self)
   }
 
   /// Returns the next consecutive position.