Allow in-place mutation of NIOLoopBoundBox.value (#2771)

* Allow in-place mutation of `NIOLoopBoundBox.value`

* Fix typos in docs

Sources/NIOCore/NIOLoopBound.swift

@@ -47,9 +47,9 @@ public struct NIOLoopBound<Value>: @unchecked Sendable {
             self._eventLoop.preconditionInEventLoop()
             return self._value
         }
-        set {
+        _modify {
             self._eventLoop.preconditionInEventLoop()
-            self._value = newValue
+            yield &self._value
         }
     }
 }
@@ -136,9 +136,9 @@ public final class NIOLoopBoundBox<Value>: @unchecked Sendable {
             self._eventLoop.preconditionInEventLoop()
             return self._value
         }
-        set {
+        _modify {
             self._eventLoop.preconditionInEventLoop()
-            self._value = newValue
+            yield &self._value
         }
     }
 }

Tests/NIOPosixTests/CoWValue.swift

@@ -0,0 +1,31 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2024 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
+//
+//===----------------------------------------------------------------------===//
+
+/// A Copy on Write (CoW) type that can be used in tests to assert in-place mutation
+struct CoWValue: @unchecked Sendable {
+    private final class UniquenessIndicator {}
+
+    /// This reference is "copied" if not uniquely referenced
+    private var uniquenessIndicator = UniquenessIndicator()
+
+    /// mutates `self` and returns a boolean whether it was mutated in place or not
+    /// - Returns: true if mutation happened in-place, false if Copy on Write (CoW) was triggered
+    mutating func mutateInPlace() -> Bool {
+        guard isKnownUniquelyReferenced(&self.uniquenessIndicator) else {
+            self.uniquenessIndicator = UniquenessIndicator()
+            return false
+        }
+        return true
+    }
+}

Tests/NIOPosixTests/NIOLoopBoundTests.swift

@@ -68,6 +68,14 @@ final class NIOLoopBoundTests: XCTestCase {
         }.wait())
     }
 
+    func testInPlaceMutation() {
+        var loopBound = NIOLoopBound(CoWValue(), eventLoop: loop)
+        XCTAssertTrue(loopBound.value.mutateInPlace())
+
+        let loopBoundBox = NIOLoopBoundBox(CoWValue(), eventLoop: loop)
+        XCTAssertTrue(loopBoundBox.value.mutateInPlace())
+    }
+
     // MARK: - Helpers
     func sendableBlackhole<S: Sendable>(_ sendableThing: S) {}