Network Socket Options¶

NetworkSocketOptions configures the shared socket policy used by Nalix TCP and UDP listeners. The options are loaded from ConfigurationManager, validated by the listener type initializers, and then applied during listener activation and per-socket setup.

Source Mapping¶

Defaults and Validation¶

Validate() runs Validator.ValidateObject(..., validateAllProperties: true). TCP listeners call validation in the static constructor and again during instance construction. UDP listener static initialization currently validates its guard options but does not call s_options.Validate() directly; bootstrap materialization and TCP listener construction still validate the same source type when those paths are used.

Construction and Ownership Flow¶

flowchart TD
    B["Bootstrap.Initialize"] --> C["ConfigurationManager.Get()"]
    C --> T["TcpListenerBase static config"]
    C --> U["UdpListenerBase static config"]
    T --> TV["s_config.Validate()"]
    TV --> TI["TCP Initialize()"]
    U --> UI["UDP Initialize()"]
    TI --> TC["Configure listener socket"]
    TI --> AC["Spawn MaxParallel accept workers"]
    AC --> PC["Bounded process channel"]
    UI --> UC["Configure datagram socket"]
    UI --> UR["Spawn MaxParallelUDP receive loops"]

The options object is configuration-owned. Listener instances read it through static fields and do not dispose or mutate it.

TCP Listener Socket Behavior¶

During TcpListenerBase.Initialize():

• if EnableIPv6 is true, the listener first attempts an IPv6 Socket with DualMode = s_config.DualMode before binding;
• failed IPv6/DualMode setup is logged and falls back to IPv4;
• ExclusiveAddressUse is set to !ReuseAddress;
• ReuseAddress is set before bind;
• the listener receive buffer is set to BufferSize;
• the socket binds to IPv6Any or Any and calls Listen(Backlog).

Accepted TCP client sockets are configured by InitializeOptions(Socket):

• Blocking = true;
• NoDelay = s_config.NoDelay;
• SendBufferSize = BufferSize;
• ReceiveBufferSize = BufferSize;
• when KeepAlive is true, TCP keep-alive is enabled.

Keep-alive tuning attempts the cross-platform TCP options first:

If that fails on Windows, the code falls back to IOControlCode.KeepAliveValues with a 12-byte little-endian payload: enabled, 3000 ms time, 1000 ms interval. On non-Windows platforms where the cross-platform call fails, the fallback is skipped.

TCP Accept and Processing Flow¶

MaxParallel controls how many accept-worker recurring tasks are scheduled. The TCP listener also creates a bounded process channel with:

capacity = ProcessChannelCapacity
SingleReader = true
SingleWriter = false
FullMode = BoundedChannelFullMode.Wait

The producer still uses TryWrite(...), so the Wait full mode is used for fail-fast overflow detection rather than blocking. When the process channel is full, the listener explicitly records the rejection and closes the newly accepted connection. Tune ProcessChannelCapacity with Backlog, accept-worker count, and protocol handshake latency.

When EnableTimeout is true, TCP connections are registered with the shared TimingWheel after initialization and removed from it during shutdown/cleanup. The option does not affect UDP listener timeout behavior.

UDP Listener Socket Behavior¶

During UdpListenerBase.Initialize():

• EnableIPv6 selects AddressFamily.InterNetworkV6 and IPAddress.IPv6Any; otherwise IPv4 AddressFamily.InterNetwork and IPAddress.Any are used;
• if the socket is IPv6 and DualMode is true, _socket.DualMode = true is attempted as best effort;
• UDP sockets are configured before bind;
• the listener binds to the selected wildcard address and configured port;
• _anyEndPoint is reset to the same address family for ReceiveFromAsync reuse.

ConfigureSocket(Socket) applies UDP-specific tuning:

• Blocking = false;
• ExclusiveAddressUse = !ReuseAddress;
• SendBufferSize = BufferSize;
• ReceiveBufferSize = BufferSize;
• socket-level ReuseAddress when enabled;
• DontFragment = true as best effort;
• on Windows, disables SIO_UDP_CONNRESET so ICMP port-unreachable messages do not surface as disruptive receive exceptions.

NoDelay and KeepAlive are intentionally TCP-only and are not applied to UDP sockets.

Diagnostics¶

TCP reports expose values such as EnableIPv6, DualMode, Backlog, BufferSize, KeepAlive, ReuseAddress, EnableTimeout, and MaxParallelAccepts.

UDP reports expose the configured port, socket buffer size, IPv6 mode, and GroupConcurrencyLimit = MaxGroupConcurrency. In the current source, MaxGroupConcurrency is diagnostic/configuration metadata for UDP reports; receive-loop parallelism is controlled by MaxParallelUDP.

Tuning Guidance¶

• Increase Backlog and ProcessChannelCapacity together for bursty TCP handshakes.
• Increase MaxParallel only when accept workers are saturated; too many accept loops can add scheduling overhead.
• Keep MaxParallelUDP proportional to datagram volume and CPU budget.
• Size BufferSize for throughput, but remember it is applied per accepted TCP socket and to UDP sockets, so high values multiply memory pressure under many connections.
• Use EnableIPv6 + DualMode when a single IPv6 socket should also accept IPv4-mapped traffic; keep IPv4 fallback behavior in mind for platforms without dual-stack support.
• Enable KeepAlive for long-lived TCP sessions behind NAT/firewalls; the hard-coded keep-alive probe profile detects dead peers quickly.

Related APIs¶

• TCP Listener
• UDP Listener
• Connection Limit Options
• Timing Wheel Options