Skip to main content

tuwunel_core/config/
runtime.rs

1//! Configures stream concurrency and batching.
2//!
3//! Stream widths set the amount of concurrent work. Amplification controls
4//! request batch sizes independently of the detected hardware queue topology.
5
6use serde::Deserialize;
7use tuwunel_macros::config_example_generator;
8
9/// Runtime scheduling
10///
11/// Groups internal scheduling settings. `[global.runtime.stream]` sets how
12/// much work the server's internal streams run at once and how large their
13/// database request batches are. The defaults adapt to the hardware
14/// detected at startup.
15#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
16#[derive(Clone, Copy, Debug, Default, Deserialize)]
17#[config_example_generator(
18	filename = "tuwunel-example.toml",
19	section = "global.runtime",
20	group = "true",
21	ignore = "stream"
22)]
23pub struct Runtime {
24	/// Settings for runtime stream.
25	///
26	/// display: section
27	#[serde(default)]
28	pub stream: Stream,
29}
30
31/// Stream concurrency
32///
33/// Sets the concurrency (width) and database batch size (amplification) of
34/// the server's internal streams. With `width_scale` above zero, both are
35/// recalculated at startup from the `[global.database.pool]` size, using
36/// `width_default` and `amplification` as the base values. All keys are
37/// read once at startup.
38///
39/// Tips:
40/// - Width is clamped to 1 through 1024 and amplification to 32 through
41///   32768.
42#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
43#[derive(Clone, Copy, Debug, Deserialize)]
44#[config_example_generator(
45	filename = "tuwunel-example.toml",
46	section = "global.runtime.stream",
47	group = "true"
48)]
49pub struct Stream {
50	/// Sets the initial stream concurrency.
51	///
52	/// The default is 32. The computed
53	/// `runtime.stream.width_scale` overrides this value unless scaling is
54	/// disabled, in which case it provides a fixed stream width.
55	///
56	/// default: 32
57	/// legacy: stream_width_default
58	#[serde(default = "default_width_default")]
59	pub width_default: usize,
60
61	/// Scales stream concurrency from the detected system capacity.
62	///
63	/// The base is the database pool worker count derived from hardware
64	/// queue size, such as 32 for SSDs or 64 or 128+ for NVMe; multipliers
65	/// such as 1.5 or 2.0 increase it, while 0.5 improves responsiveness for
66	/// many users at the cost of per-user throughput. The result cannot
67	/// exceed the pool's worker count per queue, because larger values stall
68	/// the Tokio task. A value of 0.0 fixes the width at
69	/// `runtime.stream.width_default`. The default scale of 1.0 matches
70	/// detected system capabilities.
71	///
72	/// default: 1.0
73	/// legacy: stream_width_scale
74	#[serde(default = "default_width_scale")]
75	pub width_scale: f32,
76
77	/// Sets the initial request batch amplification factor.
78	///
79	/// The factor controls batch sizes submitted by each pool worker,
80	/// multiplying stream throughput independently of specific hardware
81	/// characteristics, so it can greatly exceed thread counts or queue
82	/// sizes. Each database query may require several index lookups,
83	/// allowing queries in a batch to progress independently while sharing
84	/// index and data blocks, whether cached or not. Large batches reduce
85	/// complexity. The maximum is 32768, which still requires sufficient
86	/// hardware.
87	///
88	/// default: 1024
89	/// legacy: stream_amplification
90	#[serde(default = "default_amplification")]
91	pub amplification: usize,
92}
93
94impl Default for Stream {
95	fn default() -> Self {
96		Self {
97			width_default: default_width_default(),
98			width_scale: default_width_scale(),
99			amplification: default_amplification(),
100		}
101	}
102}
103
104fn default_width_default() -> usize { 32 }
105
106fn default_width_scale() -> f32 { 1.0 }
107
108fn default_amplification() -> usize { 1024 }