Struct ServerBuilder

Source

pub struct ServerBuilder<Cfg = NoConfig> { /* private fields */ }

Expand description

Builder for a network server.

Register listeners and their service factories, configure the worker pool, and call run to start the server.

Implementations§

Source §

impl<Cfg> ServerBuilder<Cfg>
where Cfg: ServerAppConfig,

Source

pub fn new(cfg: Cfg) -> ServerBuilder<Cfg>

Creates a server builder with the specified application configuration.

Source

pub fn name<T: AsRef<str>>(self, name: T) -> Self

Sets the server name.

The name is also used for the accept and worker thread names. It defaults to the current system name.

Source

pub fn workers(self, num: usize) -> Self

Sets the number of worker threads to start.

By default, the server uses the number of available logical CPUs.

Source

pub fn backlog(self, num: i32) -> Self

Sets the maximum number of pending connections.

This refers to the number of clients that can be waiting to be served. Exceeding this number results in the client getting an error when attempting to connect. It should only affect servers under significant load.

Generally set in the 64-2048 range. Default value is 2048.

It applies to listeners created by later bind and configure calls. It does not affect listeners passed to listen or listen_uds.

Source

pub fn max_connections(self, num: usize) -> Self

Sets the maximum per-worker number of concurrent connections.

A worker stops taking new connections while it is at this limit. When no worker can take a connection, the listeners stop accepting.

The limit is a process-wide setting shared by every server in the process. Set it before the server starts, because each worker reads it when its first service is created.

The default is 25,600 connections per worker.

Source

pub fn stop_runtime(self) -> Self

Stops the current ntex runtime after the server has stopped.

By default, “stop runtime” is disabled.

Source

pub fn stop_on_panic(self) -> Self

Stops the server when one of the workers fails.

A worker fails when it panics or its service cannot be created. The stop is graceful only if graceful_shutdown is enabled. Without this option, a failed worker is restarted.

By default, “stop on panic” is disabled.

Source

pub fn disable_signals(self) -> Self

Disables signal handling.

By default, the server stops on SIGINT, SIGTERM, and SIGQUIT.

Source

pub fn enable_affinity(self) -> Self

Enables CPU affinity for worker threads.

By default, affinity is disabled.

Source

pub fn graceful_shutdown(self) -> Self

Enables graceful shutdown on SIGQUIT, fatal signals, and panics.

When enabled, SIGQUIT, SIGSEGV, SIGABRT, application panics, and worker failures with “stop on panic” stop the server gracefully. SIGTERM always stops gracefully and SIGINT always stops immediately.

By default, these events stop the server immediately.

Source

pub fn graceful_shutdown_timeout<T: Into<Millis>>(self, timeout: T) -> Self

Timeout for graceful worker shutdown.

After receiving a stop signal, workers have this much time to finish serving requests. Workers that are still alive after the timeout are forcefully dropped.

This bounds the worker as a whole, not an individual connection. Each connection is bound separately by IoConfig::set_shutdown_timeout, so this value should leave room for the connections a worker is still draining to shut down themselves.

By default, the timeout is set to 30 seconds.

Source

pub fn status_handler<F>(self, handler: F) -> Self
where F: FnMut(ServerStatus) + Send + 'static,

Sets the server status handler.

The handler runs on the accept thread. It receives ServerStatus::Ready when the listeners resume accepting and ServerStatus::NotReady when they pause. The same status may be reported more than once.

Source

pub async fn configure<F>(self, f: F) -> Result<Self>
where F: AsyncFnOnce(ServiceConfig<Cfg>) -> Result<()>,

Runs asynchronous configuration as part of the server building process.

Listeners registered on the ServiceConfig are added to the server. Services for them are attached per worker in ServiceConfig::on_worker_start. This is useful for moving parts of the configuration to a different module or library.

Source

pub fn bind<F, S, I>( self, name: impl AsRef<str>, addr: impl ToSocketAddrs, cfg: impl Into<SharedCfg>, factory: F, ) -> Result<Self>
where F: AsyncFn(&Cfg::State) -> I + Send + Clone + 'static, S: Service<Cfg::State, Io> + 'static, I: IntoService<S, Cfg::State, Io> + 'static,

Binds TCP listeners and registers a service factory.

A listener is created for every address resolved from addr. Binding succeeds if at least one of them binds; addresses that fail to bind are skipped.

cfg is the I/O configuration for accepted connections. factory is called once per worker with that worker’s application state and returns the connection service.

Source

pub fn bind_uds<F, I, S>( self, name: impl AsRef<str>, addr: impl AsRef<Path>, cfg: impl Into<SharedCfg>, factory: F, ) -> Result<Self>
where F: AsyncFn(&Cfg::State) -> I + Send + Clone + 'static, I: IntoService<S, Cfg::State, Io> + 'static, S: Service<Cfg::State, Io> + 'static,

Binds a Unix domain socket and registers a service factory.

Any existing file at addr is removed before binding. The socket file is removed again when the server stops. See bind for cfg and factory.

Source

pub fn listen_uds<F, I, S>( self, name: impl AsRef<str>, lst: UnixListener, cfg: impl Into<SharedCfg>, factory: F, ) -> Result<Self>
where F: AsyncFn(&Cfg::State) -> I + Send + Clone + 'static, I: IntoService<S, Cfg::State, Io> + 'static, S: Service<Cfg::State, Io> + 'static,

Registers a service factory for an existing Unix domain listener.

This is useful for socket activation, including listeners acquired through systemd. The listener is switched to non-blocking mode. See bind for cfg and factory.

Source