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 }