FileHelpers: Add FileDescriptor.read(filling buffer:)

Because `read(into:)` and `write(into:)` return the number of bytes read
or written which may be smaller than desired, users will often want to
call these functions in a loop until they have read or written all the
bytes they require. Such loops require keeping track of the index and
will be repeated toil in each application.

Swift System already provides an extensions `writeAll(_:)` and
`writeAll(toAbsoluteOffset:_:)` which operates on a sequence of bytes
and writes all the bytes in the sequence.

This patch adds an analogous helper function for reading,
`read(filling buffer:)` which takes an `UnsafeMutableRawBufferPointer`
and reads until the buffer is full, or until EOF is reached.

Author: simonjbeaumont

Sources/System/FileHelpers.swift

@@ -79,6 +79,75 @@ extension FileDescriptor {
     }
   }
 
+  /// Reads bytes at the current file offset into a buffer until the buffer is filled.
+  ///
+  /// - Parameters:
+  ///   - buffer: The region of memory to read into.
+  /// - Returns: The number of bytes that were read, equal to `buffer.count`.
+  ///
+  /// This method either reads until `buffer` is full, or throws an error if
+  /// only part of the buffer was filled.
+  ///
+  /// The <doc://com.apple.documentation/documentation/swift/unsafemutablerawbufferpointer/3019191-count> property of `buffer`
+  /// determines the number of bytes that are read into the buffer.
+  @_alwaysEmitIntoClient
+  @discardableResult
+  public func read(
+    filling buffer: UnsafeMutableRawBufferPointer
+  ) throws -> Int {
+    return try _read(filling: buffer).get()
+  }
+
+  /// Reads bytes at the current file offset into a buffer until the buffer is filled.
+  ///
+  /// - Parameters:
+  ///   - offset: The file offset where reading begins.
+  ///   - buffer: The region of memory to read into.
+  /// - Returns: The number of bytes that were read, equal to `buffer.count`.
+  ///
+  /// This method either reads until `buffer` is full, or throws an error if
+  /// only part of the buffer was filled.
+  ///
+  /// The <doc://com.apple.documentation/documentation/swift/unsafemutablerawbufferpointer/3019191-count> property of `buffer`
+  /// determines the number of bytes that are read into the buffer.
+  @_alwaysEmitIntoClient
+  @discardableResult
+  public func read(
+    fromAbsoluteOffset offset: Int64,
+    filling buffer: UnsafeMutableRawBufferPointer
+  ) throws -> Int {
+    return try _read(fromAbsoluteOffset: offset, filling: buffer).get()
+  }
+
+  @usableFromInline
+  internal func _read(
+    fromAbsoluteOffset offset: Int64? = nil,
+    filling buffer: UnsafeMutableRawBufferPointer
+  ) -> Result<Int, Errno> {
+    var idx = 0
+    while idx < buffer.count {
+      let readResult: Result<Int, Errno>
+      if let offset = offset {
+        readResult = _read(
+          fromAbsoluteOffset: offset + Int64(idx),
+          into: UnsafeMutableRawBufferPointer(rebasing: buffer[idx...]),
+          retryOnInterrupt: true
+        )
+      } else {
+        readResult = _readNoThrow(
+          into: UnsafeMutableRawBufferPointer(rebasing: buffer[idx...]),
+          retryOnInterrupt: true
+        )
+      }
+      switch readResult {
+        case .success(let numBytes): idx += numBytes
+        case .failure(let err): return .failure(err)
+      }
+    }
+    assert(idx == buffer.count)
+    return .success(buffer.count)
+  }
+
   /// Writes a sequence of bytes to the given offset.
   ///
   /// - Parameters:

Sources/System/FileOperations.swift

@@ -158,14 +158,23 @@ extension FileDescriptor {
     into buffer: UnsafeMutableRawBufferPointer,
     retryOnInterrupt: Bool = true
   ) throws -> Int {
-    try _read(into: buffer, retryOnInterrupt: retryOnInterrupt).get()
+    try _readNoThrow(into: buffer, retryOnInterrupt: retryOnInterrupt).get()
   }
 
+  // NOTE: This function (mistakenly marked as throws) is vestigial but remains to preserve ABI.
   @usableFromInline
   internal func _read(
     into buffer: UnsafeMutableRawBufferPointer,
     retryOnInterrupt: Bool
   ) throws -> Result<Int, Errno> {
+    _readNoThrow(into: buffer, retryOnInterrupt: retryOnInterrupt)
+  }
+
+  @usableFromInline
+  internal func _readNoThrow(
+    into buffer: UnsafeMutableRawBufferPointer,
+    retryOnInterrupt: Bool
+  ) -> Result<Int, Errno> {
     valueOrErrno(retryOnInterrupt: retryOnInterrupt) {
       system_read(self.rawValue, buffer.baseAddress, buffer.count)
     }

Tests/SystemTests/FileOperationsTest.swift

@@ -160,5 +160,36 @@ final class FileOperationsTest: XCTestCase {
     issue26.runAllTests()
 
   }
-}
 
+/// This `#if` is present because, While `read(filling:)` is available on all platforms, this test
+/// makes use of `FileDescriptor.pipe()` which is not available on Windows.
+#if !os(Windows)
+  func testReadFilling() async throws {
+    let pipe = try FileDescriptor.pipe()
+    defer {
+      try? pipe.writeEnd.close()
+      try? pipe.readEnd.close()
+    }
+    var abc = "abc"
+    var def = "def"
+    let abcdef = abc + def
+
+    try abc.withUTF8 {
+      XCTAssertEqual(try pipe.writeEnd.writeAll(UnsafeRawBufferPointer($0)), 3)
+    }
+
+    async let readBytes = try Array<UInt8>(unsafeUninitializedCapacity: abcdef.count) { buf, count in
+      count = try pipe.readEnd.read(filling: UnsafeMutableRawBufferPointer(buf))
+      XCTAssertEqual(count, abcdef.count)
+    }
+
+    try def.withUTF8 {
+      XCTAssertEqual(try pipe.writeEnd.writeAll(UnsafeRawBufferPointer($0)), 3)
+    }
+
+    let _readBytes = try await readBytes
+
+    XCTAssertEqual(_readBytes, Array(abcdef.utf8))
+  }
+#endif
+}