mirror
/
swift-nio-transport-services
mirror of https://github.com/apple/swift-nio-transport-services.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Fix docs

This commit is contained in:
Gus Cairo 2025-04-25 16:51:35 +01:00
parent 1378a1341e
commit 24ff6590d7
4 changed files with 70 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
Sources/NIOTransportServices/Datagram/NIOTSDatagramConnectionBootstrap.swift
View File

@ -20,9 +20,10 @@ import Network
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public typealias NIOTSDatagramBootstrap = NIOTSDatagramConnectionBootstrap
/// A `NIOTSDatagramConnectionBootstrap` is an easy way to bootstrap a `NIOTSDatagramConnectionChannel` when creating network clients.
/// A ``NIOTSDatagramConnectionBootstrap`` is an easy way to bootstrap a UDP channel when creating network clients.
///
/// Usually you re-use a `NIOTSDatagramConnectionBootstrap` once you set it up, calling `connect` multiple times on the same bootstrap.
/// Usually you re-use a ``NIOTSDatagramConnectionBootstrap`` once you set it up, calling `connect` multiple times on the
/// same bootstrap.
/// This way you ensure that the same `EventLoop`s will be shared across all your connections.
///
/// Example:
@ -40,7 +41,7 @@ public typealias NIOTSDatagramBootstrap = NIOTSDatagramConnectionBootstrap
/// /* the Channel is now connected */
/// ```
///
/// The connected `NIOTSDatagramConnectionChannel` will operate on `ByteBuffer` as inbound and outbound messages.
/// The connected channel will operate on `ByteBuffer` as inbound and outbound messages.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public final class NIOTSDatagramConnectionBootstrap {
private let group: EventLoopGroup
@ -76,7 +77,7 @@ public final class NIOTSDatagramConnectionBootstrap {
self.init(group: group as EventLoopGroup)
}
/// Initialize the connected `NIOTSDatagramConnectionChannel` with `initializer`. The most common task in initializer is to add
/// Initialize the connected channel with `initializer`. The most common task in initializer is to add
/// `ChannelHandler`s to the `ChannelPipeline`.
///
/// The connected `Channel` will operate on `ByteBuffer` as inbound and outbound messages.
@ -89,7 +90,7 @@ public final class NIOTSDatagramConnectionBootstrap {
return self
}
/// Specifies a `ChannelOption` to be applied to the `NIOTSDatagramConnectionChannel`.
/// Specifies a `ChannelOption` to be applied to the channel.
///
/// - parameters:
/// - option: The option to be applied.

59
Sources/NIOTransportServices/Datagram/NIOTSDatagramListenerBootstrap.swift
View File

@ -17,8 +17,7 @@ import NIOCore
import Dispatch
import Network
/// A ``NIOTSDatagramListenerBootstrap`` is an easy way to bootstrap a `NIOTSDatagramListenerChannel` when
/// creating network servers.
/// A ``NIOTSDatagramListenerBootstrap`` is an easy way to bootstrap a listener channel when creating network servers.
///
/// Example:
///
@ -47,13 +46,12 @@ import Network
/// try! channel.closeFuture.wait() // wait forever as we never close the Channel
/// ```
///
/// The `EventLoopFuture` returned by `bind` will fire with a `NIOTSDatagramListenerChannel`. This is the channel that
/// owns the listening socket. Each time it accepts a new connection it will fire a `NIOTSDatagramConnectionChannel` through the
/// `ChannelPipeline` via `fireChannelRead`: as a result, the `NIOTSDatagramListenerChannel` operates on
/// `Channel`s as inbound messages. Outbound messages are not supported on a `NIOTSDatagramConnectionChannel` which means that
/// each write attempt will fail.
/// The `EventLoopFuture` returned by `bind` will fire with a channel. This is the channel that owns the listening socket. Each
/// time it accepts a new connection it will fire a new child channel for the new connection through the `ChannelPipeline` via
/// `fireChannelRead`: as a result, the listening channel operates on `Channel`s as inbound messages. Outbound messages are
/// not supported on these listening channels, which means that each write attempt will fail.
///
/// Accepted `NIOTSDatagramConnectionChannel`s operate on `ByteBuffer` as inbound data, and `IOData` as outbound data.
/// Accepted channels operate on `ByteBuffer` as inbound data, and `IOData` as outbound data.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public final class NIOTSDatagramListenerBootstrap {
private let group: EventLoopGroup
@ -83,7 +81,7 @@ public final class NIOTSDatagramListenerBootstrap {
/// > Note: The "real" solution is described in https://github.com/apple/swift-nio/issues/674.
///
/// - parameters:
/// - group: The `EventLoopGroup` to use for the `NIOTSDatagramListenerChannel`.
/// - group: The `EventLoopGroup` to use for the listening channel.
public convenience init(group: EventLoopGroup) {
self.init(group: group, childGroup: group)
}
@ -91,7 +89,7 @@ public final class NIOTSDatagramListenerBootstrap {
/// Create a ``NIOTSDatagramListenerBootstrap`` for the ``NIOTSEventLoopGroup`` `group`.
///
/// - parameters:
/// - group: The ``NIOTSEventLoopGroup`` to use for the `NIOTSDatagramListenerChannel`.
/// - group: The ``NIOTSEventLoopGroup`` to use for the listening channel.
public convenience init(group: NIOTSEventLoopGroup) {
self.init(group: group as EventLoopGroup)
}
@ -107,9 +105,8 @@ public final class NIOTSDatagramListenerBootstrap {
/// > Note: The "real" solution is described in https://github.com/apple/swift-nio/issues/674.
///
/// - parameters:
/// - group: The `EventLoopGroup` to use for the `bind` of the `NIOTSDatagramListenerChannel`
/// and to accept new `NIOTSDatagramConnectionChannel`s with.
/// - childGroup: The `EventLoopGroup` to run the accepted `NIOTSDatagramConnectionChannel`s on.
/// - group: The `EventLoopGroup` to use for the `bind` of the listening channel and to accept new child channels with.
/// - childGroup: The `EventLoopGroup` to run the accepted child channels on.
public convenience init(group: EventLoopGroup, childGroup: EventLoopGroup) {
guard NIOTSBootstraps.isCompatible(group: group) && NIOTSBootstraps.isCompatible(group: childGroup) else {
preconditionFailure(
@ -126,9 +123,8 @@ public final class NIOTSDatagramListenerBootstrap {
/// on `childGroup`, validating that the `EventLoopGroup`s are compatible with ``NIOTSDatagramListenerBootstrap``.
///
/// - parameters:
/// - group: The `EventLoopGroup` to use for the `bind` of the `NIOTSDatagramListenerChannel`
/// and to accept new `NIOTSDatagramConnectionChannel`s with.
/// - childGroup: The `EventLoopGroup` to run the accepted `NIOTSDatagramConnectionChannel`s on.
/// - group: The `EventLoopGroup` to use for the `bind` of the listening channel and to accept new child channels with.
/// - childGroup: The `EventLoopGroup` to run the accepted child channels on.
public init?(validatingGroup group: EventLoopGroup, childGroup: EventLoopGroup? = nil) {
let childGroup = childGroup ?? group
guard NIOTSBootstraps.isCompatible(group: group) && NIOTSBootstraps.isCompatible(group: childGroup) else {
@ -142,20 +138,19 @@ public final class NIOTSDatagramListenerBootstrap {
/// Create a ``NIOTSDatagramListenerBootstrap``.
///
/// - parameters:
/// - group: The ``NIOTSEventLoopGroup`` to use for the `bind` of the `NIOTSDatagramListenerChannel`
/// and to accept new `NIOTSDatagramConnectionChannel`s with.
/// - childGroup: The ``NIOTSEventLoopGroup`` to run the accepted `NIOTSDatagramConnectionChannel`s on.
/// - group: The ``NIOTSEventLoopGroup`` to use for the `bind` of the listening channel and to accept new child
/// channels with.
/// - childGroup: The ``NIOTSEventLoopGroup`` to run the accepted child channels on.
public convenience init(group: NIOTSEventLoopGroup, childGroup: NIOTSEventLoopGroup) {
self.init(group: group as EventLoopGroup, childGroup: childGroup as EventLoopGroup)
}
/// Initialize the `NIOTSDatagramListenerChannel` with `initializer`. The most common task in initializer is to add
/// Initialize the listening channel with `initializer`. The most common task in initializer is to add
/// `ChannelHandler`s to the `ChannelPipeline`.
///
/// The `NIOTSDatagramListenerChannel` uses the accepted `NIOTSDatagramConnectionChannel`s as inbound messages.
/// The listening channel uses the accepted child channels as inbound messages.
///
/// > Note: To set the initializer for the accepted `NIOTSDatagramConnectionChannel`s, look at
/// ``childChannelInitializer(_:)``.
/// > Note: To set the initializer for the accepted child channels, look at ``childChannelInitializer(_:)``.
///
/// - parameters:
/// - initializer: A closure that initializes the provided `Channel`.
@ -166,7 +161,7 @@ public final class NIOTSDatagramListenerBootstrap {
return self
}
/// Initialize the accepted `NIOTSDatagramConnectionChannel`s with `initializer`. The most common task in initializer is to add
/// Initialize the accepted child channels with `initializer`. The most common task in initializer is to add
/// `ChannelHandler`s to the `ChannelPipeline`. Note that if the `initializer` fails then the error will be
/// fired in the *parent* channel.
///
@ -180,9 +175,9 @@ public final class NIOTSDatagramListenerBootstrap {
return self
}
/// Specifies a `ChannelOption` to be applied to the `NIOTSDatagramListenerChannel`.
/// Specifies a `ChannelOption` to be applied to the listening channel.
///
/// > Note: To specify options for the accepted `NIOTSDatagramConnectionChannel`s, look at ``childChannelOption(_:value:)``.
/// > Note: To specify options for the accepted child channels, look at ``childChannelOption(_:value:)``.
///
/// - parameters:
/// - option: The option to be applied.
@ -192,7 +187,7 @@ public final class NIOTSDatagramListenerBootstrap {
return self
}
/// Specifies a `ChannelOption` to be applied to the accepted `NIOTSDatagramConnectionChannel`s.
/// Specifies a `ChannelOption` to be applied to the accepted child channels.
///
/// - parameters:
/// - option: The option to be applied.
@ -269,7 +264,7 @@ public final class NIOTSDatagramListenerBootstrap {
return self
}
/// Bind the `NIOTSDatagramListenerChannel` to `host` and `port`.
/// Bind the listening channel to `host` and `port`.
///
/// - parameters:
/// - host: The host to bind on.
@ -293,7 +288,7 @@ public final class NIOTSDatagramListenerBootstrap {
}
}
/// Bind the `NIOTSDatagramListenerChannel` to `address`.
/// Bind the listening channel to `address`.
///
/// - parameters:
/// - address: The `SocketAddress` to bind on.
@ -303,7 +298,7 @@ public final class NIOTSDatagramListenerBootstrap {
}
}
/// Bind the `NIOTSDatagramListenerChannel` to a UNIX Domain Socket.
/// Bind the listening channel to a UNIX Domain Socket.
///
/// - parameters:
/// - unixDomainSocketPath: The _Unix domain socket_ path to bind to. `unixDomainSocketPath` must not exist, it will be created by the system.
@ -318,7 +313,7 @@ public final class NIOTSDatagramListenerBootstrap {
}
}
/// Bind the `NIOTSDatagramListenerChannel` to a given `NWEndpoint`.
/// Bind the listening channel to a given `NWEndpoint`.
///
/// - parameters:
/// - endpoint: The `NWEndpoint` to bind this channel to.
@ -328,7 +323,7 @@ public final class NIOTSDatagramListenerBootstrap {
}
}
/// Bind the `NIOTSDatagramListenerChannel` to an existing `NWListener`.
/// Bind the listening channel to an existing `NWListener`.
///
/// - parameters:
/// - listener: The NWListener to wrap.

8
Sources/NIOTransportServices/NIOTSConnectionBootstrap.swift
View File

@ -17,7 +17,7 @@ import NIOCore
import Dispatch
import Network
/// A ``NIOTSConnectionBootstrap`` is an easy way to bootstrap a `NIOTSConnectionChannel` when creating network clients.
/// A ``NIOTSConnectionBootstrap`` is an easy way to bootstrap a channel when creating network clients.
///
/// Usually you re-use a ``NIOTSConnectionBootstrap`` once you set it up, calling `connect` multiple times on the same bootstrap.
/// This way you ensure that the same `EventLoop`s will be shared across all your connections.
@ -37,7 +37,7 @@ import Network
/// /* the Channel is now connected */
/// ```
///
/// The connected `NIOTSConnectionChannel` will operate on `ByteBuffer` as inbound and on `IOData` as outbound messages.
/// The connected channel will operate on `ByteBuffer` as inbound and on `IOData` as outbound messages.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public final class NIOTSConnectionBootstrap {
private let group: EventLoopGroup
@ -107,7 +107,7 @@ public final class NIOTSConnectionBootstrap {
self._channelInitializer = { channel in channel.eventLoop.makeSucceededVoidFuture() }
}
/// Initialize the connected `NIOTSConnectionChannel` with `initializer`. The most common task in initializer is to add
/// Initialize the connected channel with `initializer`. The most common task in initializer is to add
/// `ChannelHandler`s to the `ChannelPipeline`.
///
/// The connected `Channel` will operate on `ByteBuffer` as inbound and `IOData` as outbound messages.
@ -120,7 +120,7 @@ public final class NIOTSConnectionBootstrap {
return self
}
/// Specifies a `ChannelOption` to be applied to the `NIOTSConnectionChannel`.
/// Specifies a `ChannelOption` to be applied to the channel.
///
/// - parameters:
/// - option: The option to be applied.

67
Sources/NIOTransportServices/NIOTSListenerBootstrap.swift
View File

@ -17,7 +17,7 @@ import NIOCore
import Dispatch
import Network
/// A ``NIOTSListenerBootstrap`` is an easy way to bootstrap a `NIOTSListenerChannel` when creating network servers.
/// A ``NIOTSListenerBootstrap`` is an easy way to bootstrap a listener channel when creating network servers.
///
/// Example:
///
@ -46,13 +46,12 @@ import Network
/// try! channel.closeFuture.wait() // wait forever as we never close the Channel
/// ```
///
/// The `EventLoopFuture` returned by `bind` will fire with a `NIOTSListenerChannel`. This is the channel that owns the
/// listening socket. Each time it accepts a new connection it will fire a `NIOTSConnectionChannel` through the
/// `ChannelPipeline` via `fireChannelRead`: as a result, the `NIOTSListenerChannel` operates on `Channel`s as inbound
/// messages. Outbound messages are not supported on a `NIOTSListenerChannel` which means that each write attempt will
/// fail.
/// The `EventLoopFuture` returned by `bind` will fire with a channel. This is the channel that owns the listening socket. Each
/// time it accepts a new connection it will fire a new child channel for the new connection through the `ChannelPipeline` via
/// `fireChannelRead`: as a result, the listening channel operates on `Channel`s as inbound messages. Outbound messages are
/// not supported on these listening channels, which means that each write attempt will fail.
///
/// Accepted `NIOTSConnectionChannel`s operate on `ByteBuffer` as inbound data, and `IOData` as outbound data.
/// Accepted channels operate on `ByteBuffer` as inbound data, and `IOData` as outbound data.
@available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *)
public final class NIOTSListenerBootstrap {
private let group: EventLoopGroup
@ -82,7 +81,7 @@ public final class NIOTSListenerBootstrap {
/// > Note: The "real" solution is described in https://github.com/apple/swift-nio/issues/674.
///
/// - parameters:
/// - group: The `EventLoopGroup` to use for the `NIOTSListenerChannel`.
/// - group: The `EventLoopGroup` to use for the listening channel.
public convenience init(group: EventLoopGroup) {
self.init(group: group, childGroup: group)
}
@ -90,7 +89,7 @@ public final class NIOTSListenerBootstrap {
/// Create a ``NIOTSListenerBootstrap`` for the ``NIOTSEventLoopGroup`` `group`.
///
/// - parameters:
/// - group: The ``NIOTSEventLoopGroup`` to use for the `NIOTSListenerChannel`.
/// - group: The ``NIOTSEventLoopGroup`` to use for the listening channel.
public convenience init(group: NIOTSEventLoopGroup) {
self.init(group: group as EventLoopGroup)
}
@ -106,9 +105,9 @@ public final class NIOTSListenerBootstrap {
/// > Note: The "real" solution is described in https://github.com/apple/swift-nio/issues/674.
///
/// - parameters:
/// - group: The `EventLoopGroup` to use for the `bind` of the `NIOTSListenerChannel`
/// and to accept new `NIOTSConnectionChannel`s with.
/// - childGroup: The `EventLoopGroup` to run the accepted `NIOTSConnectionChannel`s on.
/// - group: The `EventLoopGroup` to use for the `bind` of the listening channel
/// and to accept new child channels with.
/// - childGroup: The `EventLoopGroup` to run the accepted child channels on.
public convenience init(group: EventLoopGroup, childGroup: EventLoopGroup) {
guard NIOTSBootstraps.isCompatible(group: group) && NIOTSBootstraps.isCompatible(group: childGroup) else {
preconditionFailure(
@ -125,9 +124,9 @@ public final class NIOTSListenerBootstrap {
/// validating that the `EventLoopGroup`s are compatible with ``NIOTSListenerBootstrap``.
///
/// - parameters:
/// - group: The `EventLoopGroup` to use for the `bind` of the `NIOTSListenerChannel`
/// and to accept new `NIOTSConnectionChannel`s with.
/// - childGroup: The `EventLoopGroup` to run the accepted `NIOTSConnectionChannel`s on.
/// - group: The `EventLoopGroup` to use for the `bind` of the listening channel
/// and to accept new child channels with.
/// - childGroup: The `EventLoopGroup` to run the accepted child channels on.
public init?(validatingGroup group: EventLoopGroup, childGroup: EventLoopGroup? = nil) {
let childGroup = childGroup ?? group
guard NIOTSBootstraps.isCompatible(group: group) && NIOTSBootstraps.isCompatible(group: childGroup) else {
@ -144,19 +143,19 @@ public final class NIOTSListenerBootstrap {
/// Create a ``NIOTSListenerBootstrap``.
///
/// - parameters:
/// - group: The ``NIOTSEventLoopGroup`` to use for the `bind` of the `NIOTSListenerChannel`
/// and to accept new `NIOTSConnectionChannel`s with.
/// - childGroup: The ``NIOTSEventLoopGroup`` to run the accepted `NIOTSConnectionChannel`s on.
/// - group: The ``NIOTSEventLoopGroup`` to use for the `bind` of the listening channel
/// and to accept new child channels with.
/// - childGroup: The ``NIOTSEventLoopGroup`` to run the accepted child channels on.
public convenience init(group: NIOTSEventLoopGroup, childGroup: NIOTSEventLoopGroup) {
self.init(group: group as EventLoopGroup, childGroup: childGroup as EventLoopGroup)
}
/// Initialize the `NIOTSListenerChannel` with `initializer`. The most common task in initializer is to add
/// Initialize the listening channel with `initializer`. The most common task in initializer is to add
/// `ChannelHandler`s to the `ChannelPipeline`.
///
/// The `NIOTSListenerChannel` uses the accepted `NIOTSConnectionChannel`s as inbound messages.
/// The listening channel uses the accepted child channels as inbound messages.
///
/// > Note: To set the initializer for the accepted `NIOTSConnectionChannel`s, look at
/// > Note: To set the initializer for the accepted child channels, look at
/// ``childChannelInitializer(_:)``.
///
/// - parameters:
@ -168,7 +167,7 @@ public final class NIOTSListenerBootstrap {
return self
}
/// Initialize the accepted `NIOTSConnectionChannel`s with `initializer`. The most common task in initializer is to add
/// Initialize the accepted child channels with `initializer`. The most common task in initializer is to add
/// `ChannelHandler`s to the `ChannelPipeline`. Note that if the `initializer` fails then the error will be
/// fired in the *parent* channel.
///
@ -182,9 +181,9 @@ public final class NIOTSListenerBootstrap {
return self
}
/// Specifies a `ChannelOption` to be applied to the `NIOTSListenerChannel`.
/// Specifies a `ChannelOption` to be applied to the listening channel.
///
/// > Note: To specify options for the accepted `NIOTSConnectionChannel`s, look at ``childChannelOption(_:value:)``.
/// > Note: To specify options for the accepted child channels, look at ``childChannelOption(_:value:)``.
///
/// - parameters:
/// - option: The option to be applied.
@ -194,7 +193,7 @@ public final class NIOTSListenerBootstrap {
return self
}
/// Specifies a `ChannelOption` to be applied to the accepted `NIOTSConnectionChannel`s.
/// Specifies a `ChannelOption` to be applied to the accepted child channels.
///
/// - parameters:
/// - option: The option to be applied.
@ -281,7 +280,7 @@ public final class NIOTSListenerBootstrap {
self.serverChannelOption(NIOTSChannelOptions.multipathServiceType, value: type)
}
/// Bind the `NIOTSListenerChannel` to `host` and `port`.
/// Bind the listening channel to `host` and `port`.
///
/// - parameters:
/// - host: The host to bind on.
@ -305,7 +304,7 @@ public final class NIOTSListenerBootstrap {
}
}
/// Bind the `NIOTSListenerChannel` to `address`.
/// Bind the listening channel to `address`.
///
/// - parameters:
/// - address: The `SocketAddress` to bind on.
@ -315,7 +314,7 @@ public final class NIOTSListenerBootstrap {
}
}
/// Bind the `NIOTSListenerChannel` to a UNIX Domain Socket.
/// Bind the listening channel to a UNIX Domain Socket.
///
/// - parameters:
/// - unixDomainSocketPath: The _Unix domain socket_ path to bind to. `unixDomainSocketPath` must not exist, it will be created by the system.
@ -330,7 +329,7 @@ public final class NIOTSListenerBootstrap {
}
}
/// Bind the `NIOTSListenerChannel` to a given `NWEndpoint`.
/// Bind the listening channel to a given `NWEndpoint`.
///
/// - parameters:
/// - endpoint: The `NWEndpoint` to bind this channel to.
@ -340,7 +339,7 @@ public final class NIOTSListenerBootstrap {
}
}
/// Bind the `NIOTSListenerChannel` to an existing `NWListener`.
/// Bind the listening channel to an existing `NWListener`.
///
/// - parameters:
/// - listener: The NWListener to wrap.
@ -441,7 +440,7 @@ public final class NIOTSListenerBootstrap {
@available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
extension NIOTSListenerBootstrap {
/// Bind the `NIOTSListenerChannel` to `host` and `port`.
/// Bind the listening channel to `host` and `port`.
///
/// - Parameters:
/// - host: The host to bind on.
@ -486,7 +485,7 @@ extension NIOTSListenerBootstrap {
).get()
}
/// Bind the `NIOTSListenerChannel` to `address`.
/// Bind the listening channel to `address`.
///
/// - Parameters:
/// - address: The `SocketAddress` to bind on.
@ -516,7 +515,7 @@ extension NIOTSListenerBootstrap {
).get()
}
/// Bind the `NIOTSListenerChannel` to a given `NWEndpoint`.
/// Bind the listening channel to a given `NWEndpoint`.
///
/// - Parameters:
/// - endpoint: The `NWEndpoint` to bind this channel to.
@ -549,7 +548,7 @@ extension NIOTSListenerBootstrap {
).get()
}
/// Bind the `NIOTSListenerChannel` to an existing `NWListener`.
/// Bind the listening channel to an existing `NWListener`.
///
/// - Parameters:
/// - listener: The NWListener to wrap.