ClientBootstrap

public final class ClientBootstrap

A ClientBootstrap is an easy way to bootstrap a SocketChannel when creating network clients.

Usually you re-use a ClientBootstrap once you set it up and called connect multiple times on it. This way you ensure that the same EventLoops will be shared across all your connections.

Example:

    let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
    let bootstrap = ClientBootstrap(group: group)
        // Enable SO_REUSEADDR.
        .channelOption(ChannelOptions.socket(SocketOptionLevel(SOL_SOCKET), SO_REUSEADDR), value: 1)
        .channelInitializer { channel in
            // always instantiate the handler _within_ the closure as
            // it may be called multiple times (for example if the hostname
            // resolves to both IPv4 and IPv6 addresses, cf. Happy Eyeballs).
            channel.pipeline.add(handler: MyChannelHandler())
        }
    defer {
        try! group.syncShutdownGracefully()
    }
    try! bootstrap.connect(host: "example.org", port: 12345).wait()
    /* the Channel is now connected */

The connected SocketChannel will operate on ByteBuffer as inbound and on IOData as outbound messages.

  • Create a ClientBootstrap on the EventLoopGroup group.

    Declaration

    Swift

    public init(group: EventLoopGroup)

    Parameters

    group

    The EventLoopGroup to use.

  • Initialize the connected SocketChannel with initializer. The most common task in initializer is to add ChannelHandlers to the ChannelPipeline.

    The connected Channel will operate on ByteBuffer as inbound and IOData as outbound messages.

    Warning

    The handler closure may be invoked multiple times so it’s usually the right choice to instantiate ChannelHandlers within handler. The reason handler may be invoked multiple times is that to successfully set up a connection multiple connections might be setup in the process. Assuming a hostname that resolves to both IPv4 and IPv6 addresses, NIO will follow Happy Eyeballs and race both an IPv4 and an IPv6 connection. It is possible that both connections get fully established before the IPv4 connection will be closed again because the IPv6 connection ‘won the race’. Therefore the channelInitializer might be called multiple times and it’s important not to share stateful ChannelHandlers in more than one Channel.

    Declaration

    Swift

    public func channelInitializer(_ handler: @escaping (Channel) -> EventLoopFuture<Void>) -> Self

    Parameters

    handler

    A closure that initializes the provided Channel.

  • Specifies a ChannelOption to be applied to the SocketChannel.

    Declaration

    Swift

    public func channelOption<T>(_ option: T, value: T.OptionType) -> Self where T : ChannelOption

    Parameters

    option

    The option to be applied.

    value

    The value for the option.

  • Declaration

    Swift

    public func connectTimeout(_ timeout: TimeAmount) -> Self

    Parameters

    timeout

    The timeout that will apply to the connection attempt.

  • Specifies the Resolver to use or nil if the default should be used.

    Declaration

    Swift

    public func resolver(_ resolver: Resolver?) -> Self

    Parameters

    resolver

    The resolver that will be used during the connection attempt.

  • Specify the host and port to connect to for the TCP Channel that will be established.

    Declaration

    Swift

    public func connect(host: String, port: Int) -> EventLoopFuture<Channel>

    Parameters

    host

    The host to connect to.

    port

    The port to connect to.

    Return Value

    An EventLoopFuture<Channel> to deliver the Channel when connected.

  • Specify the address to connect to for the TCP Channel that will be established.

    Declaration

    Swift

    public func connect(to address: SocketAddress) -> EventLoopFuture<Channel>

    Parameters

    address

    The address to connect to.

    Return Value

    An EventLoopFuture<Channel> to deliver the Channel when connected.

  • Specify the unixDomainSocket path to connect to for the UDS Channel that will be established.

    Declaration

    Swift

    public func connect(unixDomainSocketPath: String) -> EventLoopFuture<Channel>

    Parameters

    unixDomainSocketPath

    The Unix domain socket path to connect to.

    Return Value

    An EventLoopFuture<Channel> to deliver the Channel when connected.

  • Use the existing connected socket file descriptor.

    Declaration

    Swift

    public func withConnectedSocket(descriptor: CInt) -> EventLoopFuture<Channel>

    Parameters

    descriptor

    The Unix file descriptor representing the connected stream socket.

    Return Value

    an EventLoopFuture<Channel> to deliver the Channel immediately.