kestrel_timer/
config.rs

1//! Timer Configuration Module
2//!
3//! Provides hierarchical configuration structure and Builder pattern for configuring timing wheel, service, and batch processing behavior.
4//!
5//! 定时器配置模块，提供分层的配置结构和 Builder 模式，用于配置时间轮、服务和批处理行为。
6use crate::error::TimerError;
7use std::time::Duration;
8use std::num::NonZeroUsize;
9
10/// Timing Wheel Configuration
11///
12/// Used to configure parameters for hierarchical timing wheel. The system only supports hierarchical mode.
13///
14/// # 时间轮配置
15/// 
16/// 用于配置分层时间轮的参数。系统只支持分层模式。
17/// 
18/// # Examples (示例)
19/// ```no_run
20/// use kestrel_timer::config::WheelConfig;
21/// use std::time::Duration;
22///
23/// // Use default configuration (使用默认配置，分层模式)
24/// let config = WheelConfig::default();
25///
26/// // Use Builder to customize configuration (使用 Builder 自定义配置)
27/// let config = WheelConfig::builder()
28///     .l0_tick_duration(Duration::from_millis(20))
29///     .l0_slot_count(1024)
30///     .l1_tick_duration(Duration::from_secs(2))
31///     .l1_slot_count(128)
32///     .build()
33///     .unwrap();
34/// ```
35#[derive(Debug, Clone)]
36pub struct WheelConfig {
37    /// Duration of each tick in L0 layer, bottom layer
38    /// 
39    /// L0 层每个 tick 的持续时间
40    pub l0_tick_duration: Duration,
41    
42    /// Number of slots in L0 layer, must be power of 2
43    /// 
44    /// L0 层槽位数，必须是 2 的幂
45    pub l0_slot_count: usize,
46    
47    /// Duration of each tick in L1 layer, upper layer
48    /// 
49    /// L1 层每个 tick 的持续时间
50    pub l1_tick_duration: Duration,
51
52    /// Number of slots in L1 layer, must be power of 2
53    /// 
54    /// L1 层槽位数，必须是 2 的幂
55    pub l1_slot_count: usize,
56}
57
58impl Default for WheelConfig {
59    fn default() -> Self {
60        Self {
61            l0_tick_duration: Duration::from_millis(10),
62            l0_slot_count: 512,
63            l1_tick_duration: Duration::from_secs(1),
64            l1_slot_count: 64,
65        }
66    }
67}
68
69impl WheelConfig {
70    /// Create configuration builder (创建配置构建器)
71    pub fn builder() -> WheelConfigBuilder {
72        WheelConfigBuilder::default()
73    }
74}
75
76/// Timing Wheel Configuration Builder
77#[derive(Debug, Clone)]
78pub struct WheelConfigBuilder {
79    l0_tick_duration: Duration,
80    l0_slot_count: usize,
81    l1_tick_duration: Duration,
82    l1_slot_count: usize,
83}
84
85impl Default for WheelConfigBuilder {
86    fn default() -> Self {
87        Self {
88            l0_tick_duration: Duration::from_millis(10),
89            l0_slot_count: 512,
90            l1_tick_duration: Duration::from_secs(1),
91            l1_slot_count: 64,
92        }
93    }
94}
95
96impl WheelConfigBuilder {
97    /// Set L0 layer tick duration
98    pub fn l0_tick_duration(mut self, duration: Duration) -> Self {
99        self.l0_tick_duration = duration;
100        self
101    }
102
103    /// Set L0 layer slot count
104    pub fn l0_slot_count(mut self, count: usize) -> Self {
105        self.l0_slot_count = count;
106        self
107    }
108
109    /// Set L1 layer tick duration
110    pub fn l1_tick_duration(mut self, duration: Duration) -> Self {
111        self.l1_tick_duration = duration;
112        self
113    }
114
115    /// Set L1 layer slot count
116    pub fn l1_slot_count(mut self, count: usize) -> Self {
117        self.l1_slot_count = count;
118        self
119    }
120
121    /// Build and validate configuration
122    ///
123    /// # Returns
124    /// - `Ok(WheelConfig)`: Configuration is valid
125    /// - `Err(TimerError)`: Configuration validation failed
126    ///
127    /// # Validation Rules
128    /// - L0 tick duration must be greater than 0
129    /// - L1 tick duration must be greater than 0
130    /// - L0 slot count must be greater than 0 and power of 2
131    /// - L1 slot count must be greater than 0 and power of 2
132    /// - L1 tick must be an integer multiple of L0 tick
133    pub fn build(self) -> Result<WheelConfig, TimerError> {
134        // Validate L0 layer configuration
135        if self.l0_tick_duration.is_zero() {
136            return Err(TimerError::InvalidConfiguration {
137                field: "l0_tick_duration".to_string(),
138                reason: "L0 layer tick duration must be greater than 0".to_string(),
139            });
140        }
141
142        if self.l0_slot_count == 0 {
143            return Err(TimerError::InvalidSlotCount {
144                slot_count: self.l0_slot_count,
145                reason: "L0 layer slot count must be greater than 0",
146            });
147        }
148
149        if !self.l0_slot_count.is_power_of_two() {
150            return Err(TimerError::InvalidSlotCount {
151                slot_count: self.l0_slot_count,
152                reason: "L0 layer slot count must be power of 2",
153            });
154        }
155
156        // Validate L1 layer configuration
157        if self.l1_tick_duration.is_zero() {
158            return Err(TimerError::InvalidConfiguration {
159                field: "l1_tick_duration".to_string(),
160                reason: "L1 layer tick duration must be greater than 0".to_string(),
161            });
162        }
163
164        if self.l1_slot_count == 0 {
165            return Err(TimerError::InvalidSlotCount {
166                slot_count: self.l1_slot_count,
167                reason: "L1 layer slot count must be greater than 0",
168            });
169        }
170
171        if !self.l1_slot_count.is_power_of_two() {
172            return Err(TimerError::InvalidSlotCount {
173                slot_count: self.l1_slot_count,
174                reason: "L1 layer slot count must be power of 2",
175            });
176        }
177
178        // Validate L1 tick is an integer multiple of L0 tick
179        let l0_ms = self.l0_tick_duration.as_millis() as u64;
180        let l1_ms = self.l1_tick_duration.as_millis() as u64;
181        if l1_ms % l0_ms != 0 {
182            return Err(TimerError::InvalidConfiguration {
183                field: "l1_tick_duration".to_string(),
184                reason: format!(
185                    "L1 tick duration ({} ms) must be an integer multiple of L0 tick duration ({} ms)",
186                    l1_ms, l0_ms
187                ),
188            });
189        }
190
191        Ok(WheelConfig {
192            l0_tick_duration: self.l0_tick_duration,
193            l0_slot_count: self.l0_slot_count,
194            l1_tick_duration: self.l1_tick_duration,
195            l1_slot_count: self.l1_slot_count,
196        })
197    }
198}
199
200/// Service Configuration
201///
202/// Used to configure channel capacities for TimerService.
203///
204/// # 服务配置
205/// 
206/// 用于配置 TimerService 的通道容量。
207/// 
208/// # Examples (示例)
209/// ```no_run
210/// use kestrel_timer::config::ServiceConfig;
211/// use std::num::NonZeroUsize;
212///
213/// // Use default configuration (使用默认配置)
214/// let config = ServiceConfig::default();
215///
216/// // Use Builder to customize configuration (使用 Builder 自定义配置)
217/// let config = ServiceConfig::builder()
218///     .command_channel_capacity(NonZeroUsize::new(1024).unwrap())
219///     .timeout_channel_capacity(NonZeroUsize::new(2000).unwrap())
220///     .build();
221/// ```
222#[derive(Debug, Clone)]
223pub struct ServiceConfig {
224    /// Command channel capacity 
225    /// 
226    /// 命令通道容量
227    pub command_channel_capacity: NonZeroUsize,
228
229    /// Timeout channel capacity
230    /// 
231    /// 超时通道容量
232    pub timeout_channel_capacity: NonZeroUsize,
233}
234
235impl Default for ServiceConfig {
236    fn default() -> Self {
237        Self {
238            command_channel_capacity: NonZeroUsize::new(512).unwrap(),
239            timeout_channel_capacity: NonZeroUsize::new(1000).unwrap(),
240        }
241    }
242}
243
244impl ServiceConfig {
245    /// Create configuration builder (创建配置构建器)
246    pub fn builder() -> ServiceConfigBuilder {
247        ServiceConfigBuilder::default()
248    }
249}
250
251/// Service Configuration Builder 
252/// 
253/// 用于构建 ServiceConfig 的构建器。
254#[derive(Debug, Clone)]
255pub struct ServiceConfigBuilder {
256    /// Command channel capacity
257    /// 
258    /// 命令通道容量
259    pub command_channel_capacity: NonZeroUsize,
260    
261    /// Timeout channel capacity
262    /// 
263    /// 超时通道容量
264    pub timeout_channel_capacity: NonZeroUsize,
265}
266
267impl Default for ServiceConfigBuilder {
268    fn default() -> Self {
269        let config = ServiceConfig::default();
270        Self {
271            command_channel_capacity: config.command_channel_capacity,
272            timeout_channel_capacity: config.timeout_channel_capacity,
273        }
274    }
275}
276
277impl ServiceConfigBuilder {
278    /// Set command channel capacity (设置命令通道容量)
279    pub fn command_channel_capacity(mut self, capacity: NonZeroUsize) -> Self {
280        self.command_channel_capacity = capacity;
281        self
282    }
283
284    /// Set timeout channel capacity (设置超时通道容量)
285    pub fn timeout_channel_capacity(mut self, capacity: NonZeroUsize) -> Self {
286        self.timeout_channel_capacity = capacity;
287        self
288    }
289
290    /// Build and validate configuration
291    ///
292    /// # Returns
293    /// - `Ok(ServiceConfig)`: Configuration is valid
294    /// - `Err(TimerError)`: Configuration validation failed
295    ///
296    /// # Validation Rules
297    /// - All channel capacities must be greater than 0
298    /// 
299    /// 构建并验证配置
300    /// 
301    /// # 返回值
302    /// - `Ok(ServiceConfig)`: 配置有效
303    /// - `Err(TimerError)`: 配置验证失败
304    /// 
305    /// # 验证规则
306    /// - 所有通道容量必须大于 0
307    /// 
308    pub fn build(self) -> ServiceConfig {
309        ServiceConfig {
310            command_channel_capacity: self.command_channel_capacity,
311            timeout_channel_capacity: self.timeout_channel_capacity,
312        }
313    }
314}
315
316/// Batch Processing Configuration
317///
318/// Used to configure optimization parameters for batch operations.
319/// 
320/// 用于配置批处理操作的优化参数。
321/// 
322/// # 批处理配置
323/// 
324/// 用于配置批处理操作的优化参数。
325///
326/// # Examples (示例)
327/// ```no_run
328/// use kestrel_timer::config::BatchConfig;
329///
330/// // Use default configuration (使用默认配置)
331/// let config = BatchConfig::default();
332///
333/// // Custom configuration (使用自定义配置)
334/// let config = BatchConfig {
335///     small_batch_threshold: 20,
336/// };
337/// ```
338#[derive(Debug, Clone)]
339pub struct BatchConfig {
340    /// Small batch threshold, used for batch cancellation optimization
341    /// When the number of tasks to be cancelled is less than or equal to this value, cancel individually without grouping and sorting
342    /// 
343    /// 小批量阈值，用于批量取消操作的优化
344    /// 
345    /// 当需要取消的任务数量小于或等于此值时，取消操作将单独进行，无需分组和排序
346    pub small_batch_threshold: usize,
347}
348
349impl Default for BatchConfig {
350    fn default() -> Self {
351        Self {
352            small_batch_threshold: 10,
353        }
354    }
355}
356
357/// Top-level Timer Configuration
358///
359/// Combines all sub-configurations to provide complete timer system configuration.
360///
361/// # 定时器配置
362/// 
363/// 用于组合所有子配置，提供完整的定时器系统配置。
364/// 
365/// # Examples (示例)
366/// ```no_run
367/// use kestrel_timer::config::TimerConfig;
368/// use std::num::NonZeroUsize;
369///
370/// // Use default configuration (使用默认配置)
371/// let config = TimerConfig::default();
372///
373/// // Use Builder to customize configuration, service parameters only
374/// // (使用 Builder 自定义配置，仅配置服务参数)
375/// let config = TimerConfig::builder()
376///     .command_channel_capacity(NonZeroUsize::new(1024).unwrap())
377///     .timeout_channel_capacity(NonZeroUsize::new(2000).unwrap())
378///     .build();
379/// ```
380#[derive(Debug, Clone)]
381pub struct TimerConfig {
382    /// Timing wheel configuration
383    pub wheel: WheelConfig,
384    /// Service configuration
385    pub service: ServiceConfig,
386    /// Batch processing configuration
387    pub batch: BatchConfig,
388}
389
390impl Default for TimerConfig {
391    fn default() -> Self {
392        Self {
393            wheel: WheelConfig::default(),
394            service: ServiceConfig::default(),
395            batch: BatchConfig::default(),
396        }
397    }
398}
399
400impl TimerConfig {
401    /// Create configuration builder (创建配置构建器)
402    pub fn builder() -> TimerConfigBuilder {
403        TimerConfigBuilder::default()
404    }
405}
406
407/// Top-level Timer Configuration Builder (顶级定时器配置构建器)
408/// 
409/// 用于构建 TimerConfig 的构建器。
410#[derive(Debug)]
411pub struct TimerConfigBuilder {
412    wheel_builder: WheelConfigBuilder,
413    service_builder: ServiceConfigBuilder,
414    batch_config: BatchConfig,
415}
416
417impl Default for TimerConfigBuilder {
418    fn default() -> Self {
419        Self {
420            wheel_builder: WheelConfigBuilder::default(),
421            service_builder: ServiceConfigBuilder::default(),
422            batch_config: BatchConfig::default(),
423        }
424    }
425}
426
427impl TimerConfigBuilder {
428    /// Set command channel capacity (设置命令通道容量)
429    pub fn command_channel_capacity(mut self, capacity: NonZeroUsize) -> Self {
430        self.service_builder = self.service_builder.command_channel_capacity(capacity);
431        self
432    }
433
434    /// Set timeout channel capacity (设置超时通道容量)
435    pub fn timeout_channel_capacity(mut self, capacity: NonZeroUsize) -> Self {
436        self.service_builder = self.service_builder.timeout_channel_capacity(capacity);
437        self
438    }
439
440    /// Set small batch threshold (设置小批量阈值)
441    pub fn small_batch_threshold(mut self, threshold: usize) -> Self {
442        self.batch_config.small_batch_threshold = threshold;
443        self
444    }
445
446    /// Build and validate configuration
447    ///
448    /// # Returns
449    /// - `Ok(TimerConfig)`: Configuration is valid
450    /// - `Err(TimerError)`: Configuration validation failed
451    /// 
452    /// # 构建并验证配置
453    /// 
454    /// # 返回值
455    /// - `Ok(TimerConfig)`: 配置有效
456    /// - `Err(TimerError)`: 配置验证失败
457    /// 
458    pub fn build(self) -> Result<TimerConfig, TimerError> {
459        Ok(TimerConfig {
460            wheel: self.wheel_builder.build()?,
461            service: self.service_builder.build(),
462            batch: self.batch_config,
463        })
464    }
465}
466
467#[cfg(test)]
468mod tests {
469    use super::*;
470
471    #[test]
472    fn test_wheel_config_default() {
473        let config = WheelConfig::default();
474        assert_eq!(config.l0_tick_duration, Duration::from_millis(10));
475        assert_eq!(config.l0_slot_count, 512);
476        assert_eq!(config.l1_tick_duration, Duration::from_secs(1));
477        assert_eq!(config.l1_slot_count, 64);
478    }
479
480    #[test]
481    fn test_wheel_config_builder() {
482        let config = WheelConfig::builder()
483            .l0_tick_duration(Duration::from_millis(20))
484            .l0_slot_count(1024)
485            .l1_tick_duration(Duration::from_secs(2))
486            .l1_slot_count(128)
487            .build()
488            .unwrap();
489
490        assert_eq!(config.l0_tick_duration, Duration::from_millis(20));
491        assert_eq!(config.l0_slot_count, 1024);
492        assert_eq!(config.l1_tick_duration, Duration::from_secs(2));
493        assert_eq!(config.l1_slot_count, 128);
494    }
495
496    #[test]
497    fn test_wheel_config_validation_zero_tick() {
498        let result = WheelConfig::builder()
499            .l0_tick_duration(Duration::ZERO)
500            .build();
501
502        assert!(result.is_err());
503    }
504
505    #[test]
506    fn test_wheel_config_validation_invalid_slot_count() {
507        let result = WheelConfig::builder()
508            .l0_slot_count(100)
509            .build();
510
511        assert!(result.is_err());
512    }
513
514    #[test]
515    fn test_service_config_builder() {
516        let config = ServiceConfig::builder()
517            .command_channel_capacity(NonZeroUsize::new(1024).unwrap())
518            .timeout_channel_capacity(NonZeroUsize::new(2000).unwrap())
519            .build();
520
521        assert_eq!(config.command_channel_capacity, NonZeroUsize::new(1024).unwrap());
522        assert_eq!(config.timeout_channel_capacity, NonZeroUsize::new(2000).unwrap());
523    }
524
525    #[test]
526    fn test_batch_config_default() {
527        let config = BatchConfig::default();
528        assert_eq!(config.small_batch_threshold, 10);
529    }
530
531    #[test]
532    fn test_timer_config_default() {
533        let config = TimerConfig::default();
534        assert_eq!(config.wheel.l0_slot_count, 512);
535        assert_eq!(config.service.command_channel_capacity, NonZeroUsize::new(512).unwrap());
536        assert_eq!(config.batch.small_batch_threshold, 10);
537    }
538
539    #[test]
540    fn test_timer_config_builder() {
541        let config = TimerConfig::builder()
542            .command_channel_capacity(NonZeroUsize::new(1024).unwrap())
543            .timeout_channel_capacity(NonZeroUsize::new(2000).unwrap())
544            .small_batch_threshold(20)
545            .build()
546            .unwrap();
547
548        assert_eq!(config.service.command_channel_capacity, NonZeroUsize::new(1024).unwrap());
549        assert_eq!(config.service.timeout_channel_capacity, NonZeroUsize::new(2000).unwrap());
550        assert_eq!(config.batch.small_batch_threshold, 20);
551    }
552}
553
kestrel_timer/config.rs

kestrel_timer/
config.rs
