Extract PriorityQueue to its own module. (#1932)

Motivation:

I'd like to move EmbeddedChannel and friends out of the main NIO
repository and into their own module. Unfortunately, EmbeddedChannel
shares the PriorityQueue implementation we wrote with the various POSIX
channels. To avoid duplicating the code, we should pull it out to its
own module.

However, we've never wanted to commit to the API of this data structure,
and the same is true now. To that end, I'm pulling it into an
underscored module that is not a product of the package.

We could have used the `@_spi` annotation here but honestly I'm a bit
nervous about doing that at the low-level of NIO itself, as if the Swift
team does change the spelling of it at any point in the future we'll be
in real trouble. This way works almost as well, and makes our intent a
lot clearer.

Modifications:

- Extracted Heap and PriorityQueue to a new module.
- Made everything @inlinable to do our best to make performance
  acceptable.

Result:

We can re-use PriorityQueue.

Author: Lukasa

Package.swift

@@ -3,7 +3,7 @@
 //
 // This source file is part of the SwiftNIO open source project
 //
-// Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors
+// Copyright (c) 2017-2021 Apple Inc. and the SwiftNIO project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -18,12 +18,14 @@ import PackageDescription
 var targets: [PackageDescription.Target] = [
     .target(name: "NIOCore",
             dependencies: ["NIOConcurrencyHelpers", "CNIOLinux"]),
+    .target(name: "_NIODataStructures"),
     .target(name: "NIO",
             dependencies: ["CNIOLinux",
                            "CNIODarwin",
                            "CNIOWindows",
                            "NIOConcurrencyHelpers",
-                           "NIOCore"]),
+                           "NIOCore",
+                           "_NIODataStructures"]),
     .target(name: "_NIOConcurrency",
             dependencies: ["NIO"]),
     .target(name: "NIOFoundationCompat", dependencies: ["NIO"]),
@@ -74,6 +76,8 @@ var targets: [PackageDescription.Target] = [
                 dependencies: ["NIO", "NIOFoundationCompat", "NIOTestUtils", "NIOConcurrencyHelpers"]),
     .testTarget(name: "NIOConcurrencyHelpersTests",
                 dependencies: ["NIOConcurrencyHelpers", "NIO"]),
+    .testTarget(name: "NIODataStructuresTests",
+                dependencies: ["_NIODataStructures"]),
     .testTarget(name: "NIOHTTP1Tests",
                 dependencies: ["NIOHTTP1", "NIOFoundationCompat", "NIOTestUtils"]),
     .testTarget(name: "NIOTLSTests",

Sources/NIO/Embedded.swift

@@ -13,6 +13,7 @@
 //===----------------------------------------------------------------------===//
 
 import Dispatch
+import _NIODataStructures
 
 private final class EmbeddedScheduledTask {
     let task: () -> Void

Sources/NIO/SelectableEventLoop.swift

@@ -14,6 +14,7 @@
 
 import Dispatch
 import NIOConcurrencyHelpers
+import _NIODataStructures
 
 /// Execute the given closure and ensure we release all auto pools if needed.
 @inlinable

Sources/NIO/Heap.swift renamed to Sources/_NIODataStructures/Heap.swift

@@ -2,7 +2,7 @@
 //
 // This source file is part of the SwiftNIO open source project
 //
-// Copyright (c) 2017-2020 Apple Inc. and the SwiftNIO project authors
+// Copyright (c) 2017-2021 Apple Inc. and the SwiftNIO project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -11,37 +11,49 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 //===----------------------------------------------------------------------===//
+#if os(macOS) || os(iOS) || os(watchOS) || os(tvOS)
+import Darwin.C
+#elseif os(Linux) || os(FreeBSD) || os(Android)
+import Glibc
+#endif
 
 @usableFromInline
 internal struct Heap<Element: Comparable> {
     @usableFromInline
-    internal private(set) var storage: ContiguousArray<Element> = []
+    internal private(set) var storage: ContiguousArray<Element>
 
-    @usableFromInline
-    internal init() {}
+    @inlinable
+    internal init() {
+        self.storage = []
+    }
 
+    @inlinable
     internal func comparator(_ lhs: Element, _ rhs: Element) -> Bool {
         // This heap is always a min-heap.
         return lhs < rhs
     }
 
     // named `PARENT` in CLRS
-    private func parentIndex(_ i: Int) -> Int {
+    @inlinable
+    internal func parentIndex(_ i: Int) -> Int {
         return (i-1) / 2
     }
 
     // named `LEFT` in CLRS
+    @inlinable
     internal func leftIndex(_ i: Int) -> Int {
         return 2*i + 1
     }
 
     // named `RIGHT` in CLRS
+    @inlinable
     internal func rightIndex(_ i: Int) -> Int {
         return 2*i + 2
     }
 
     // named `MAX-HEAPIFY` in CLRS
-    private mutating func heapify(_ index: Int) {
+    /* private but */ @inlinable
+    mutating func _heapify(_ index: Int) {
         let left = self.leftIndex(index)
         let right = self.rightIndex(index)
 
@@ -58,12 +70,13 @@ internal struct Heap<Element: Comparable> {
 
         if root != index {
             self.storage.swapAt(index, root)
-            self.heapify(root)
+            self._heapify(root)
         }
     }
 
     // named `HEAP-INCREASE-KEY` in CRLS
-    private mutating func heapRootify(index: Int, key: Element) {
+    /* private but */ @inlinable
+    mutating func _heapRootify(index: Int, key: Element) {
         var index = index
         if self.comparator(storage[index], key) {
             fatalError("New key must be closer to the root than current key")
@@ -76,7 +89,7 @@ internal struct Heap<Element: Comparable> {
         }
     }
 
-    @usableFromInline
+    @inlinable
     internal mutating func append(_ value: Element) {
         var i = self.storage.count
         self.storage.append(value)
@@ -87,44 +100,45 @@ internal struct Heap<Element: Comparable> {
     }
 
     @discardableResult
-    @usableFromInline
+    @inlinable
     internal mutating func removeRoot() -> Element? {
-        return self.remove(index: 0)
+        return self._remove(index: 0)
     }
 
     @discardableResult
-    @usableFromInline
+    @inlinable
     internal mutating func remove(value: Element) -> Bool {
         if let idx = self.storage.firstIndex(of: value) {
-            self.remove(index: idx)
+            self._remove(index: idx)
             return true
         } else {
             return false
         }
     }
 
     @discardableResult
-    private mutating func remove(index: Int) -> Element? {
+    /* private but */ @inlinable
+    mutating func _remove(index: Int) -> Element? {
         guard self.storage.count > 0 else {
             return nil
         }
         let element = self.storage[index]
         if self.storage.count == 1 || self.storage[index] == self.storage[self.storage.count - 1] {
             self.storage.removeLast()
         } else if !self.comparator(self.storage[index], self.storage[self.storage.count - 1]) {
-            self.heapRootify(index: index, key: self.storage[self.storage.count - 1])
+            self._heapRootify(index: index, key: self.storage[self.storage.count - 1])
             self.storage.removeLast()
         } else {
             self.storage[index] = self.storage[self.storage.count - 1]
             self.storage.removeLast()
-            self.heapify(index)
+            self._heapify(index)
         }
         return element
     }
 }
 
 extension Heap: CustomDebugStringConvertible {
-    @usableFromInline
+    @inlinable
     var debugDescription: String {
         guard self.storage.count > 0 else {
             return "<empty heap>"
@@ -184,40 +198,52 @@ extension Heap: CustomDebugStringConvertible {
 
 @usableFromInline
 struct HeapIterator<Element: Comparable>: IteratorProtocol {
-    private var heap: Heap<Element>
+    /* private but */ @usableFromInline
+    var _heap: Heap<Element>
 
+    @inlinable
     init(heap: Heap<Element>) {
-        self.heap = heap
+        self._heap = heap
     }
 
-    @usableFromInline
+    @inlinable
     mutating func next() -> Element? {
-        return self.heap.removeRoot()
+        return self._heap.removeRoot()
     }
 }
 
 extension Heap: Sequence {
-    var startIndex: Int { return self.storage.startIndex }
-    var endIndex: Int { return self.storage.endIndex }
+    @inlinable
+    var startIndex: Int {
+        return self.storage.startIndex
+    }
 
-    @usableFromInline
+    @inlinable
+    var endIndex: Int {
+        return self.storage.endIndex
+    }
+
+    @inlinable
     var underestimatedCount: Int {
         return self.storage.count
     }
 
-    @usableFromInline
+    @inlinable
     func makeIterator() -> HeapIterator<Element> {
         return HeapIterator(heap: self)
     }
 
+    @inlinable
     subscript(position: Int) -> Element {
         return self.storage[position]
     }
 
+    @inlinable
     func index(after i: Int) -> Int {
         return i + 1
     }
 
+    @inlinable
     var count: Int {
         return self.storage.count
     }

Sources/NIO/PriorityQueue.swift renamed to Sources/_NIODataStructures/PriorityQueue.swift

@@ -2,7 +2,7 @@
 //
 // This source file is part of the SwiftNIO open source project
 //
-// Copyright (c) 2017-2020 Apple Inc. and the SwiftNIO project authors
+// Copyright (c) 2017-2021 Apple Inc. and the SwiftNIO project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -12,83 +12,87 @@
 //
 //===----------------------------------------------------------------------===//
 
-@usableFromInline
-internal struct PriorityQueue<Element: Comparable> {
+public struct PriorityQueue<Element: Comparable> {
     @usableFromInline
     internal var _heap: Heap<Element>
 
-    internal init() {
+    @inlinable
+    public init() {
         self._heap = Heap()
     }
 
     @inlinable
-    internal mutating func remove(_ key: Element) {
+    public mutating func remove(_ key: Element) {
         self._heap.remove(value: key)
     }
 
     @inlinable
-    internal mutating func push(_ key: Element) {
+    public mutating func push(_ key: Element) {
         self._heap.append(key)
     }
 
     @inlinable
-    internal func peek() -> Element? {
+    public func peek() -> Element? {
         return self._heap.storage.first
     }
 
     @inlinable
-    internal var isEmpty: Bool {
+    public var isEmpty: Bool {
         return self._heap.storage.isEmpty
     }
 
     @inlinable
     @discardableResult
-    internal mutating func pop() -> Element? {
+    public mutating func pop() -> Element? {
         return self._heap.removeRoot()
     }
 
     @inlinable
-    internal mutating func clear() {
+    public mutating func clear() {
         self._heap = Heap()
     }
 }
 
 extension PriorityQueue: Equatable {
-    @usableFromInline
-    internal static func ==(lhs: PriorityQueue, rhs: PriorityQueue) -> Bool {
+    @inlinable
+    public static func ==(lhs: PriorityQueue, rhs: PriorityQueue) -> Bool {
         return lhs.count == rhs.count && lhs.elementsEqual(rhs)
     }
 }
 
 extension PriorityQueue: Sequence {
-    @usableFromInline
-    struct Iterator: IteratorProtocol {
+    public struct Iterator: IteratorProtocol {
+
+        /* private but */ @usableFromInline
+        var _queue: PriorityQueue<Element>
 
-        private var queue: PriorityQueue<Element>
-        fileprivate init(queue: PriorityQueue<Element>) {
-            self.queue = queue
+        /* fileprivate but */ @inlinable
+        public init(queue: PriorityQueue<Element>) {
+            self._queue = queue
         }
 
+        @inlinable
         public mutating func next() -> Element? {
-            return self.queue.pop()
+            return self._queue.pop()
         }
     }
 
-    @usableFromInline
-    func makeIterator() -> Iterator {
+    @inlinable
+    public func makeIterator() -> Iterator {
         return Iterator(queue: self)
     }
 }
 
 extension PriorityQueue {
-    var count: Int {
+    @inlinable
+    public var count: Int {
         return self._heap.count
     }
 }
 
 extension PriorityQueue: CustomStringConvertible {
-    @usableFromInline
-    var description: String {
+    @inlinable
+    public var description: String {
         return "PriorityQueue(count: \(self.count)): \(Array(self))"
     }
 }

Tests/LinuxMain.swift

@@ -24,6 +24,7 @@ import XCTest
 
 #if os(Linux) || os(FreeBSD) || os(Android)
    @testable import NIOConcurrencyHelpersTests
+   @testable import NIODataStructuresTests
    @testable import NIOFoundationCompatTests
    @testable import NIOHTTP1Tests
    @testable import NIOTLSTests

Tests/NIOTests/HeapTests+XCTest.swift renamed to Tests/NIODataStructuresTests/HeapTests+XCTest.swift

@@ -13,7 +13,7 @@
 //===----------------------------------------------------------------------===//
 
 import XCTest
-@testable import NIO
+@testable import _NIODataStructures
 
 public func getRandomNumbers(count: Int) -> [UInt8] {
     return (0..<count).map { _ in