ServerBootstrap
public final class ServerBootstrap
A ServerBootstrap
is an easy way to bootstrap a ServerSocketChannel
when creating network servers.
Example:
let group = MultiThreadedEventLoopGroup(numberOfThreads: System.coreCount)
defer {
try! group.syncShutdownGracefully()
}
let bootstrap = ServerBootstrap(group: group)
// Specify backlog and enable SO_REUSEADDR for the server itself
.serverChannelOption(ChannelOptions.backlog, value: 256)
.serverChannelOption(ChannelOptions.socketOption(.so_reuseaddr), value: 1)
// Set the handlers that are applied to the accepted child `Channel`s.
.childChannelInitializer { channel in
// Ensure we don't read faster then we can write by adding the BackPressureHandler into the pipeline.
channel.pipeline.addHandler(BackPressureHandler()).flatMap { () in
// make sure to instantiate your `ChannelHandlers` inside of
// the closure as it will be invoked once per connection.
channel.pipeline.addHandler(MyChannelHandler())
}
}
// Enable SO_REUSEADDR for the accepted Channels
.childChannelOption(ChannelOptions.socketOption(.so_reuseaddr), value: 1)
.childChannelOption(ChannelOptions.maxMessagesPerRead, value: 16)
.childChannelOption(ChannelOptions.recvAllocator, value: AdaptiveRecvByteBufferAllocator())
let channel = try! bootstrap.bind(host: host, port: port).wait()
/* the server will now be accepting connections */
try! channel.closeFuture.wait() // wait forever as we never close the Channel
The EventLoopFuture
returned by bind
will fire with a ServerSocketChannel
. This is the channel that owns the listening socket.
Each time it accepts a new connection it will fire a SocketChannel
through the ChannelPipeline
via fireChannelRead
: as a result,
the ServerSocketChannel
operates on Channel
s as inbound messages. Outbound messages are not supported on a ServerSocketChannel
which means that each write attempt will fail.
Accepted SocketChannel
s operate on ByteBuffer
as inbound data, and IOData
as outbound data.
-
Create a
ServerBootstrap
on theEventLoopGroup
group
.The
EventLoopGroup
group
must be compatible, otherwise the program will crash.ServerBootstrap
is compatible only withMultiThreadedEventLoopGroup
as well as theEventLoop
s returned byMultiThreadedEventLoopGroup.next
. Seeinit(validatingGroup:childGroup:)
for a fallible initializer for situations where it’s impossible to tell ahead of time if theEventLoopGroup
s are compatible or not.Declaration
Swift
public convenience init(group: EventLoopGroup)
Parameters
group
The
EventLoopGroup
to use for thebind
of theServerSocketChannel
and to accept newSocketChannel
s with. -
Create a
ServerBootstrap
on theEventLoopGroup
group
which acceptsChannel
s onchildGroup
.The
EventLoopGroup
sgroup
andchildGroup
must be compatible, otherwise the program will crash.ServerBootstrap
is compatible only withMultiThreadedEventLoopGroup
as well as theEventLoop
s returned byMultiThreadedEventLoopGroup.next
. Seeinit(validatingGroup:childGroup:)
for a fallible initializer for situations where it’s impossible to tell ahead of time if theEventLoopGroup
s are compatible or not.Declaration
Swift
public convenience init(group: EventLoopGroup, childGroup: EventLoopGroup)
Parameters
group
The
EventLoopGroup
to use for thebind
of theServerSocketChannel
and to accept newSocketChannel
s with.childGroup
The
EventLoopGroup
to run the acceptedSocketChannel
s on. -
Create a
ServerBootstrap
on theEventLoopGroup
group
which acceptsChannel
s onchildGroup
, validating that theEventLoopGroup
s are compatible withServerBootstrap
.Declaration
Swift
public init?(validatingGroup group: EventLoopGroup, childGroup: EventLoopGroup? = nil)
Parameters
group
The
EventLoopGroup
to use for thebind
of theServerSocketChannel
and to accept newSocketChannel
s with.childGroup
The
EventLoopGroup
to run the acceptedSocketChannel
s on. Ifnil
,group
is used. -
Initialize the
ServerSocketChannel
withinitializer
. The most common task in initializer is to addChannelHandler
s to theChannelPipeline
.The
ServerSocketChannel
uses the acceptedChannel
s as inbound messages.Note
To set the initializer for the accepted
SocketChannel
s, look atServerBootstrap.childChannelInitializer
.Declaration
Swift
public func serverChannelInitializer(_ initializer: @escaping (Channel) -> EventLoopFuture<Void>) -> Self
Parameters
initializer
A closure that initializes the provided
Channel
. -
Initialize the accepted
SocketChannel
s withinitializer
. The most common task in initializer is to addChannelHandler
s to theChannelPipeline
. Note that if theinitializer
fails then the error will be fired in the parent channel.Warning
Theinitializer
will be invoked once for every accepted connection. Therefore it’s usually the right choice to instantiate statefulChannelHandler
s within the closure to make sure they are not accidentally shared acrossChannel
s. There are expert use-cases where stateful handler need to be shared acrossChannel
s in which case the user is responsible to synchronise the state access appropriately.The accepted
Channel
will operate onByteBuffer
as inbound andIOData
as outbound messages.Declaration
Swift
public func childChannelInitializer(_ initializer: @escaping (Channel) -> EventLoopFuture<Void>) -> Self
Parameters
initializer
A closure that initializes the provided
Channel
. -
Specifies a
ChannelOption
to be applied to theServerSocketChannel
.Note
To specify options for the accepted
SocketChannel
s, look atServerBootstrap.childChannelOption
.Declaration
Swift
@inlinable public func serverChannelOption<Option>(_ option: Option, value: Option.Value) -> Self where Option : ChannelOption
Parameters
option
The option to be applied.
value
The value for the option.
-
Specifies a
ChannelOption
to be applied to the acceptedSocketChannel
s.Declaration
Swift
@inlinable public func childChannelOption<Option>(_ option: Option, value: Option.Value) -> Self where Option : ChannelOption
Parameters
option
The option to be applied.
value
The value for the option.
-
Specifies a timeout to apply to a bind attempt. Currently unsupported.
Declaration
Swift
public func bindTimeout(_ timeout: TimeAmount) -> Self
Parameters
timeout
The timeout that will apply to the bind attempt.
-
Bind the
ServerSocketChannel
tohost
andport
.Declaration
Swift
public func bind(host: String, port: Int) -> EventLoopFuture<Channel>
Parameters
host
The host to bind on.
port
The port to bind on.
-
Bind the
ServerSocketChannel
toaddress
.Declaration
Swift
public func bind(to address: SocketAddress) -> EventLoopFuture<Channel>
Parameters
address
The
SocketAddress
to bind on. -
Bind the
ServerSocketChannel
to a UNIX Domain Socket.Declaration
Swift
public func bind(unixDomainSocketPath: String) -> EventLoopFuture<Channel>
Parameters
unixDomainSocketPath
The Unix domain socket path to bind to.
unixDomainSocketPath
must not exist, it will be created by the system. -
Bind the
ServerSocketChannel
to a UNIX Domain Socket.Declaration
Swift
public func bind(unixDomainSocketPath: String, cleanupExistingSocketFile: Bool) -> EventLoopFuture<Channel>
Parameters
unixDomainSocketPath
The Unix domain socket path to bind to.
unixDomainSocketPath
must not exist, it will be created by the system.cleanupExistingSocketFile
Whether to cleanup an existing socket file at
path
. -
Use the existing bound socket file descriptor.
Declaration
Swift
@available(*, deprecated, renamed: "withBoundSocket(_:﹚") public func withBoundSocket(descriptor: CInt) -> EventLoopFuture<Channel>
Parameters
descriptor
The Unix file descriptor representing the bound stream socket.
-
Use the existing bound socket file descriptor.
Declaration
Swift
public func withBoundSocket(_ socket: NIOBSDSocket.Handle) -> EventLoopFuture<Channel>
Parameters
descriptor
The Unix file descriptor representing the bound stream socket.