rename Channel._unsafe to Channel._channelCore (#820)

Motivation:

_unsafe is non-descriptive

Modifications:

- rename Channel._unsafe to Channel._channelCore

Result:

clearer API

Sources/NIO/BaseSocketChannel.swift

@@ -275,7 +275,7 @@ class BaseSocketChannel<T: BaseSocket>: SelectableChannel, ChannelCore {
     }
 
     // MARK: Computed Properties
-    public final var _unsafe: ChannelCore { return self }
+    public final var _channelCore: ChannelCore { return self }
 
     // This is `Channel` API so must be thread-safe.
     public final var localAddress: SocketAddress? {

Sources/NIO/Channel.swift

@@ -14,7 +14,9 @@
 
 import NIOConcurrencyHelpers
 
-/// The core `Channel` methods for NIO-internal use only.
+/// The core `Channel` methods that are for internal use of the `Channel` implementation only.
+///
+/// - warning: If you are not implementing a custom `Channel` type, you should never call any of these.
 ///
 /// - note: All methods must be called from the `EventLoop` thread.
 public protocol ChannelCore: class {
@@ -134,10 +136,10 @@ public protocol Channel: class, ChannelOutboundInvoker {
     /// or `channelInactive` can be expected next when `handlerAdded` was received.
     var isActive: Bool { get }
 
-    /// Reach out to the `ChannelCore`.
+    /// Reach out to the `_ChannelCore`.
     ///
     /// - warning: Unsafe, this is for use in NIO's core only.
-    var _unsafe: ChannelCore { get }
+    var _channelCore: ChannelCore { get }
 }
 
 /// A `SelectableChannel` is a `Channel` that can be used with a `Selector` which notifies a user when certain events

Sources/NIO/ChannelPipeline.swift

@@ -935,35 +935,35 @@ extension ChannelPipeline {
     private init() { }
 
     func register(ctx: ChannelHandlerContext, promise: EventLoopPromise<Void>?) {
-        ctx.channel._unsafe.register0(promise: promise)
+        ctx.channel._channelCore.register0(promise: promise)
     }
 
     func bind(ctx: ChannelHandlerContext, to address: SocketAddress, promise: EventLoopPromise<Void>?) {
-        ctx.channel._unsafe.bind0(to: address, promise: promise)
+        ctx.channel._channelCore.bind0(to: address, promise: promise)
     }
 
     func connect(ctx: ChannelHandlerContext, to address: SocketAddress, promise: EventLoopPromise<Void>?) {
-        ctx.channel._unsafe.connect0(to: address, promise: promise)
+        ctx.channel._channelCore.connect0(to: address, promise: promise)
     }
 
     func write(ctx: ChannelHandlerContext, data: NIOAny, promise: EventLoopPromise<Void>?) {
-        ctx.channel._unsafe.write0(data, promise: promise)
+        ctx.channel._channelCore.write0(data, promise: promise)
     }
 
     func flush(ctx: ChannelHandlerContext) {
-        ctx.channel._unsafe.flush0()
+        ctx.channel._channelCore.flush0()
     }
 
     func close(ctx: ChannelHandlerContext, mode: CloseMode, promise: EventLoopPromise<Void>?) {
-        ctx.channel._unsafe.close0(error: mode.error, mode: mode, promise: promise)
+        ctx.channel._channelCore.close0(error: mode.error, mode: mode, promise: promise)
     }
 
     func read(ctx: ChannelHandlerContext) {
-        ctx.channel._unsafe.read0()
+        ctx.channel._channelCore.read0()
     }
 
     func triggerUserOutboundEvent(ctx: ChannelHandlerContext, event: Any, promise: EventLoopPromise<Void>?) {
-        ctx.channel._unsafe.triggerUserOutboundEvent0(event, promise: promise)
+        ctx.channel._channelCore.triggerUserOutboundEvent0(event, promise: promise)
     }
 
 }
@@ -1019,11 +1019,11 @@ private extension CloseMode {
     }
 
     func errorCaught(ctx: ChannelHandlerContext, error: Error) {
-        ctx.channel._unsafe.errorCaught0(error: error)
+        ctx.channel._channelCore.errorCaught0(error: error)
     }
 
     func channelRead(ctx: ChannelHandlerContext, data: NIOAny) {
-        ctx.channel._unsafe.channelRead0(data)
+        ctx.channel._channelCore.channelRead0(data)
     }
 }
 
@@ -1063,7 +1063,7 @@ public final class ChannelHandlerContext: ChannelInvoker {
     public var remoteAddress: SocketAddress? {
         do {
             // Fast-path access to the remoteAddress.
-            return try self.channel._unsafe.remoteAddress0()
+            return try self.channel._channelCore.remoteAddress0()
         } catch ChannelError.ioOnClosedChannel {
             // Channel was closed already but we may still have the address cached so try to access it via the Channel
             // so we are able to use it in channelInactive(...) / handlerRemoved(...) methods.
@@ -1076,7 +1076,7 @@ public final class ChannelHandlerContext: ChannelInvoker {
     public var localAddress: SocketAddress? {
         do {
             // Fast-path access to the localAddress.
-            return try self.channel._unsafe.localAddress0()
+            return try self.channel._channelCore.localAddress0()
         } catch ChannelError.ioOnClosedChannel {
             // Channel was closed already but we may still have the address cached so try to access it via the Channel
             // so we are able to use it in channelInactive(...) / handlerRemoved(...) methods.

Sources/NIO/DeadChannel.swift

@@ -113,5 +113,5 @@ internal final class DeadChannel: Channel {
 
     let isWritable = false
     let isActive = false
-    let _unsafe: ChannelCore = DeadChannelCore()
+    let _channelCore: ChannelCore = DeadChannelCore()
 }

Sources/NIO/Embedded.swift

@@ -295,7 +295,7 @@ public class EmbeddedChannel: Channel {
 
     private lazy var channelcore: EmbeddedChannelCore = EmbeddedChannelCore(pipeline: self._pipeline, eventLoop: self.eventLoop)
 
-    public var _unsafe: ChannelCore {
+    public var _channelCore: ChannelCore {
         return channelcore
     }
 

Sources/_NIO1APIShims/NIO1APIShims.swift

@@ -372,6 +372,13 @@ extension ByteBuffer {
     }
 }
 
+extension Channel {
+    @available(*, deprecated, renamed: "_channelCore")
+    var _unsafe: ChannelCore {
+        return self._channelCore
+    }
+}
+
 @available(*, deprecated, renamed: "HTTPServerProtocolUpgrader")
 public typealias HTTPProtocolUpgrader = HTTPServerProtocolUpgrader
 

Tests/NIOTests/AcceptBackoffHandlerTest.swift

@@ -213,7 +213,7 @@ public class AcceptBackoffHandlerTest: XCTestCase {
             serverChannel.read()
             let readCount = readCountHandler.readCount
             // Directly trigger a read again without going through the pipeline. This will allow us to use serverChannel.readable()
-            serverChannel._unsafe.read0()
+            serverChannel._channelCore.read0()
             serverChannel.readable()
             return readCount
         }.wait())

Tests/NIOTests/ChannelOptionStorageTest.swift

@@ -91,7 +91,7 @@ class OptionsCollectingChannel: Channel {
 
     var isActive: Bool { fatalError() }
 
-    var _unsafe: ChannelCore { fatalError() }
+    var _channelCore: ChannelCore { fatalError() }
 
     var eventLoop: EventLoop {
         return EmbeddedEventLoop()

Tests/NIOTests/EmbeddedChannelTest.swift

@@ -137,7 +137,7 @@ class EmbeddedChannelTest: XCTestCase {
         let channel = EmbeddedChannel()
         let pipelineEventLoop = channel.pipeline.eventLoop
         XCTAssert(pipelineEventLoop === channel.eventLoop)
-        XCTAssert(pipelineEventLoop === (channel._unsafe as! EmbeddedChannelCore).eventLoop)
+        XCTAssert(pipelineEventLoop === (channel._channelCore as! EmbeddedChannelCore).eventLoop)
         XCTAssertFalse(try channel.finish())
     }
 

docs/public-api-changes-NIO1-to-NIO2.md

@@ -4,6 +4,7 @@
 - renamed `SniResult` to `SNIResult`
 - renamed `SniHandler` to `SNIHandler`
 - made `EventLoopGroup.makeIterator()` a required method
+- `Channel._unsafe` is now `Channel._channelCore`
 - `TimeAmount.Value` is now `Int64` (from `Int` on 64 bit platforms, no change
   for 32 bit platforms)
 - `ByteToMessageDecoder`s now need to be wrapped in `ByteToMessageHandler`

docs/public-api.md

@@ -15,7 +15,7 @@ If we prefix something with an underscore or put it into one of NIO's internal m
 ##### Examples
 
  - ✅ `channel.close(promise: nil)`
- - ❌ `channel._unsafe.flush0()`, underscored property
+ - ❌ `channel._channelCore.flush0()`, underscored property
  - ❌ `import CNIOAtomics`, module name doesn't start with NIO
  - ❌ `ByteBuffer(_enableSuperSpecialAllocationMode: true)`, as the initialiser's first argument is underscored
 
@@ -114,4 +114,4 @@ Needless to say if you require at least version `2.3.4` you would specify `from:
 
 ## What happens if you ignore these guidelines?
 
-We are trying to be nice people and we ❤️ our users so we will never break anybody just because they didn't perfectly stick to these guidelines. But just ignoring those guidelines might mean rewriting some of your code, debugging random build, or runtime failures that we didn't hit in the pre-release testing. We do have a source compatibility suite to which you can [ask to be added](https://forums.swift.org/t/register-as-swiftnio-user-to-get-ahead-of-time-security-notifications-be-added-to-the-source-compatibility-suite/17792) and we try not to break you (within reason). But it is impossible for us to test all of our users' projects and we don't want to lose the ability to move fast without breaking things. Certain failures like clashing protocol conformances can have delicate failure modes.
+We are trying to be nice people and we ❤️ our users so we will never break anybody just because they didn't perfectly stick to these guidelines. But just ignoring those guidelines might mean rewriting some of your code, debugging random build, or runtime failures that we didn't hit in the pre-release testing. We do have a source compatibility suite to which you can [ask to be added](https://forums.swift.org/t/register-as-swiftnio-user-to-get-ahead-of-time-security-notifications-be-added-to-the-source-compatibility-suite/17792) and we try not to break you (within reason). But it is impossible for us to test all of our users' projects and we don't want to lose the ability to move fast without breaking things. Certain failures like clashing protocol conformances can have delicate failure modes.