OnLoopSendable: Sendable containers if on EventLoop (#2370)

Co-authored-by: Cory Benfield <lukasa@apple.com>

Sources/NIOCore/NIOLoopBound.swift

@@ -0,0 +1,125 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2023 Apple Inc. and the SwiftNIO project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+/// ``NIOLoopBound`` is an always-``Sendable``, value-typed container allowing you access to ``Value`` if and only if
+/// you are accessing it on the right EventLoop``.
+///
+/// ``NIOLoopBound`` is useful to transport a value of a non-``Sendable`` type that needs to go from one place in
+/// your code to another where you (but not the compiler) know is on one and the same ``EventLoop``. Usually this
+/// involves `@Sendable` closures. This type is safe because it verifies (using `eventLoop.preconditionInEventLoop()`)
+/// that this is actually true.
+///
+/// A ``NIOLoopBound`` can only be constructed, read from or written to when you are provably
+/// (through `eventLoop.preconditionInEventLoop()`) on the ``EventLoop`` associated with the ``NIOLoopBound``. Accessing
+/// or constructing it from any other place will crash your program with a precondition as it would be undefined
+/// behaviour to do so.
+public struct NIOLoopBound<Value>: @unchecked Sendable {
+    public let _eventLoop: EventLoop
+
+    @usableFromInline
+    /* private */ var _value: Value
+
+    /// Initialise a ``NIOLoopBound`` to `value` with the precondition that the code is running on `eventLoop`.
+    @inlinable
+    public init(_ value: Value, eventLoop: EventLoop) {
+        eventLoop.preconditionInEventLoop()
+        self._eventLoop = eventLoop
+        self._value = value
+    }
+
+    /// Access the `value` with the precondition that the code is running on `eventLoop`.
+    ///
+    /// - note: ``NIOLoopBound`` itself is value-typed, so any writes will only affect the current value.
+    @inlinable
+    public var value: Value {
+        get {
+            self._eventLoop.preconditionInEventLoop()
+            return self._value
+        }
+        set {
+            self._eventLoop.preconditionInEventLoop()
+            self._value = newValue
+        }
+    }
+}
+
+/// ``NIOLoopBoundBox`` is an always-``Sendable``, reference-typed container allowing you access to ``Value`` if and
+/// only if you are accessing it on the right EventLoop``.
+///
+/// ``NIOLoopBoundBox`` is useful to transport a value of a non-``Sendable`` type that needs to go from one place in
+/// your code to another where you (but not the compiler) know is on one and the same ``EventLoop``. Usually this
+/// involves `@Sendable` closures. This type is safe because it verifies (using `eventLoop.preconditionInEventLoop()`)
+/// that this is actually true.
+///
+/// A ``NIOLoopBoundBox`` can only be read from or written to when you are provably
+/// (through `eventLoop.preconditionInEventLoop()`) on the ``EventLoop`` associated with the ``NIOLoopBoundBox``. Accessing
+/// or constructing it from any other place will crash your program with a precondition as it would be undefined
+/// behaviour to do so.
+///
+/// If constructing a ``NIOLoopBoundBox`` with a `value`, it is also required for the program to already be on `eventLoop`
+/// but if you have a ``NIOLoopBoundBox`` that contains an ``Optional`` type, you may initialise it _without a value_
+/// whilst off the ``EventLoop`` by using ``NIOLoopBoundBox.makeEmptyBox``. Any read/write access to `value`
+/// afterwards will require you to be on `eventLoop`.
+public final class NIOLoopBoundBox<Value>: @unchecked Sendable {
+    public let _eventLoop: EventLoop
+
+    @usableFromInline
+    /* private */var _value: Value
+
+    @inlinable
+    internal init(_value value: Value, uncheckedEventLoop eventLoop: EventLoop) {
+        self._eventLoop = eventLoop
+        self._value = value
+    }
+
+    /// Initialise a ``NIOLoopBoundBox`` to `value` with the precondition that the code is running on `eventLoop`.
+    @inlinable
+    public convenience init(_ value: Value, eventLoop: EventLoop) {
+        // This precondition is absolutely required. If not, it were possible to take a non-Sendable `Value` from
+        // _off_ the ``EventLoop`` and transport it _to_ the ``EventLoop``. That would be illegal.
+        eventLoop.preconditionInEventLoop()
+        self.init(_value: value, uncheckedEventLoop: eventLoop)
+    }
+
+    /// Initialise a ``NIOLoopBoundBox`` that is empty (contains `nil`), this does _not_ require you to be running on `eventLoop`.
+    public static func makeEmptyBox<NonOptionalValue>(
+        valueType: NonOptionalValue.Type = NonOptionalValue.self,
+        eventLoop: EventLoop
+    ) -> NIOLoopBoundBox<Value> where Optional<NonOptionalValue> == Value {
+        // Here, we -- possibly surprisingly -- do not precondition being on the EventLoop. This is okay for a few
+        // reasons:
+        // - We write the `Optional.none` value which we know is _not_ a value of the potentially non-Sendable type
+        //   `Value`.
+        // - Because of Swift's Definitive Initialisation (DI), we know that we did write `self._value` before `init`
+        //   returns.
+        // - The only way to ever write (or read indeed) `self._value` is by proving to be inside the `EventLoop`.
+        return .init(_value: nil, uncheckedEventLoop: eventLoop)
+    }
+
+    /// Access the `value` with the precondition that the code is running on `eventLoop`.
+    ///
+    /// - note: ``NIOLoopBoundBox`` itself is reference-typed, so any writes will affect anybody sharing this reference.
+    @inlinable
+    public var value: Value {
+        get {
+            self._eventLoop.preconditionInEventLoop()
+            return self._value
+        }
+        set {
+            self._eventLoop.preconditionInEventLoop()
+            self._value = newValue
+        }
+    }
+}
+

Sources/NIOCrashTester/CrashTestSuites.swift

@@ -19,5 +19,6 @@ let crashTestSuites: [String: Any] = [
     "SystemCrashTests": SystemCrashTests(),
     "HTTPCrashTests": HTTPCrashTests(),
     "StrictCrashTests": StrictCrashTests(),
+    "LoopBoundTests": LoopBoundTests(),
 ]
 #endif

Sources/NIOCrashTester/CrashTests+LoopBound.swift

@@ -0,0 +1,75 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2020-2021 Apple Inc. and the SwiftNIO project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import NIOCore
+import NIOPosix
+
+fileprivate let group = MultiThreadedEventLoopGroup(numberOfThreads: 2)
+
+struct LoopBoundTests {
+    #if !os(iOS) && !os(tvOS) && !os(watchOS)
+    let testInitChecksEventLoop = CrashTest(
+        regex: "NIOCore/NIOLoopBound.swift:[0-9]+: Precondition failed"
+    ) {
+        _ = NIOLoopBound(1, eventLoop: group.any()) // BOOM
+    }
+
+    let testInitOfBoxChecksEventLoop = CrashTest(
+        regex: "NIOCore/NIOLoopBound.swift:[0-9]+: Precondition failed"
+    ) {
+        _ = NIOLoopBoundBox(1, eventLoop: group.any()) // BOOM
+    }
+
+    let testGetChecksEventLoop = CrashTest(
+        regex: "NIOCore/NIOLoopBound.swift:[0-9]+: Precondition failed"
+    ) {
+        let loop = group.any()
+        let sendable = try? loop.submit {
+            NIOLoopBound(1, eventLoop: loop)
+        }.wait()
+        _ = sendable?.value // BOOM
+    }
+
+    let testGetOfBoxChecksEventLoop = CrashTest(
+        regex: "NIOCore/NIOLoopBound.swift:[0-9]+: Precondition failed"
+    ) {
+        let loop = group.any()
+        let sendable = try? loop.submit {
+            NIOLoopBoundBox(1, eventLoop: loop)
+        }.wait()
+        _ = sendable?.value // BOOM
+    }
+
+    let testSetChecksEventLoop = CrashTest(
+        regex: "NIOCore/NIOLoopBound.swift:[0-9]+: Precondition failed"
+    ) {
+        let loop = group.any()
+        let sendable = try? loop.submit {
+            NIOLoopBound(1, eventLoop: loop)
+        }.wait()
+        var sendableVar = sendable
+        sendableVar?.value = 2
+    }
+
+    let testSetOfBoxChecksEventLoop = CrashTest(
+        regex: "NIOCore/NIOLoopBound.swift:[0-9]+: Precondition failed"
+    ) {
+        let loop = group.any()
+        let sendable = try? loop.submit {
+            NIOLoopBoundBox(1, eventLoop: loop)
+        }.wait()
+        sendable?.value = 2
+    }
+    #endif
+}

Tests/LinuxMain.swift

@@ -111,6 +111,7 @@ class LinuxMainRunner {
              testCase(NIOHTTP1TestServerTest.allTests),
              testCase(NIOHTTPClientResponseAggregatorTest.allTests),
              testCase(NIOHTTPServerRequestAggregatorTest.allTests),
+             testCase(NIOLoopBoundTests.allTests),
              testCase(NIOSingleStepByteToMessageDecoderTest.allTests),
              testCase(NIOTests.allTests),
              testCase(NIOThreadPoolTest.allTests),

Tests/NIOPosixTests/NIOLoopBoundTests+XCTest.swift

@@ -0,0 +1,35 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2017-2023 Apple Inc. and the SwiftNIO project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+//
+// NIOLoopBoundTests+XCTest.swift
+//
+import XCTest
+
+///
+/// NOTE: This file was generated by generate_linux_tests.rb
+///
+/// Do NOT edit this file directly as it will be regenerated automatically when needed.
+///
+
+extension NIOLoopBoundTests {
+
+   @available(*, deprecated, message: "not actually deprecated. Just deprecated to allow deprecated tests (which test deprecated functionality) without warnings")
+   static var allTests : [(String, (NIOLoopBoundTests) -> () throws -> Void)] {
+      return [
+                ("testLoopBoundIsSendableWithNonSendableValue", testLoopBoundIsSendableWithNonSendableValue),
+                ("testLoopBoundBoxCanBeInitialisedWithNilOffLoopAndLaterSetToValue", testLoopBoundBoxCanBeInitialisedWithNilOffLoopAndLaterSetToValue),
+           ]
+   }
+}
+

Tests/NIOPosixTests/NIOLoopBoundTests.swift

@@ -0,0 +1,69 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2023 Apple Inc. and the SwiftNIO project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import NIOCore
+import NIOPosix
+import NIOEmbedded
+import XCTest
+
+final class NIOLoopBoundTests: XCTestCase {
+    private var loop: EmbeddedEventLoop!
+
+    func testLoopBoundIsSendableWithNonSendableValue() {
+        let nonSendable = NotSendable()
+        let sendable = NIOLoopBound(nonSendable, eventLoop: self.loop)
+        let sendableBox = NIOLoopBoundBox(nonSendable, eventLoop: self.loop)
+
+        XCTAssert(sendable.value === nonSendable)
+        XCTAssert(sendableBox.value === nonSendable)
+
+        sendableBlackhole(sendable)
+        sendableBlackhole(sendableBox)
+    }
+
+    func testLoopBoundBoxCanBeInitialisedWithNilOffLoopAndLaterSetToValue() {
+        let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+        defer {
+            XCTAssertNoThrow(try group.syncShutdownGracefully())
+        }
+
+        let loop = group.any()
+
+        let sendableBox = NIOLoopBoundBox.makeEmptyBox(valueType: NotSendable.self, eventLoop: loop)
+        XCTAssertNoThrow(try loop.submit {
+            sendableBox.value = NotSendable()
+        }.wait())
+        XCTAssertNoThrow(try loop.submit {
+            XCTAssertNotNil(sendableBox.value)
+        }.wait())
+    }
+
+    // MARK: - Helpers
+    func sendableBlackhole<S: Sendable>(_ sendableThing: S) {}
+
+    // MARK: - Setup/teardown
+    override func setUp() {
+        self.loop = EmbeddedEventLoop()
+    }
+
+    override func tearDown() {
+        XCTAssertNoThrow(try self.loop?.syncShutdownGracefully())
+        self.loop = nil
+    }
+}
+
+final class NotSendable {}
+
+@available(*, unavailable)
+extension NotSendable: Sendable {}