1use std::{
23 any::Any,
24 cell::{RefCell, UnsafeCell},
25 collections::VecDeque,
26 fmt::{Debug, Display},
27 marker::PhantomData,
28 num::{NonZeroU64, NonZeroUsize},
29 rc::Rc,
30};
31
32use nautilus_core::{DurationNanos, UnixNanos, correctness::FAILED};
33use serde::{Deserialize, Serialize};
34use ustr::Ustr;
35
36use crate::{
37 actor::{
38 Actor,
39 registry::{register_actor, try_get_actor_unchecked, with_actor_registry},
40 },
41 clock::Clock,
42 msgbus::{self, Endpoint, Handler, MStr, ShareableMessageHandler},
43 timer::{TimeEvent, TimeEventCallback},
44};
45
46const MAX_INITIAL_TIMESTAMPS_CAPACITY: usize = 1024;
47
48pub struct Throttler<T, F> {
75 clock: Rc<RefCell<dyn Clock>>,
76 actor_id: Ustr,
77 timer_name: Ustr,
78 limit: NonZeroUsize,
79 interval_ns: NonZeroU64,
80 large_limit: bool,
81 buffer: VecDeque<T>,
82 timestamps: VecDeque<UnixNanos>,
83 is_limiting: bool,
84 recv_count: usize,
85 sent_count: usize,
86 output_send: F,
87 output_drop: Option<F>,
88}
89
90impl<T, F> Actor for Throttler<T, F>
91where
92 T: 'static + Debug,
93 F: Fn(T) + 'static,
94{
95 fn id(&self) -> Ustr {
96 self.actor_id
97 }
98
99 fn handle(&mut self, _msg: &dyn Any) {}
100
101 fn as_any(&self) -> &dyn Any {
102 self
103 }
104}
105
106impl<T, F> Debug for Throttler<T, F>
107where
108 T: Debug,
109{
110 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
111 f.debug_struct(stringify!(Throttler))
112 .field("actor_id", &self.actor_id)
113 .field("timer_name", &self.timer_name)
114 .field("limit", &self.limit())
115 .field("interval_ns", &self.interval_ns().as_u64())
116 .field("buffer", &self.buffer)
117 .field("timestamps", &self.timestamps)
118 .field("is_limiting", &self.is_limiting)
119 .field("recv_count", &self.recv_count)
120 .field("sent_count", &self.sent_count)
121 .finish()
122 }
123}
124
125impl<T, F> Throttler<T, F>
126where
127 T: Debug,
128{
129 #[inline]
134 pub fn new(
135 rate_limit: RateLimit,
136 clock: Rc<RefCell<dyn Clock>>,
137 timer_name: &str,
138 output_send: F,
139 output_drop: Option<F>,
140 actor_id: Ustr,
141 ) -> Self {
142 Self {
143 clock,
144 actor_id,
145 timer_name: Ustr::from(format!("{timer_name}-{actor_id}").as_str()),
146 limit: rate_limit.limit,
147 interval_ns: rate_limit.interval_ns,
148 large_limit: rate_limit.limit.get() > MAX_INITIAL_TIMESTAMPS_CAPACITY,
149 buffer: VecDeque::new(),
150 timestamps: VecDeque::with_capacity(
151 rate_limit.limit.get().min(MAX_INITIAL_TIMESTAMPS_CAPACITY),
152 ),
153 is_limiting: false,
154 recv_count: 0,
155 sent_count: 0,
156 output_send,
157 output_drop,
158 }
159 }
160
161 #[inline]
174 pub(crate) fn set_timer(&self, callback: Option<TimeEventCallback>) {
175 let mut clock = self.clock.borrow_mut();
176 if clock.timer_exists(&self.timer_name) {
177 clock.cancel_timer(&self.timer_name);
178 }
179
180 let now = clock.timestamp_ns();
181
182 let Some(alert_ts) = now.checked_add(self.delta_next_at(now)) else {
183 return;
185 };
186
187 clock
188 .set_time_alert_ns(self.timer_name.as_str(), alert_ts, callback, Some(true))
189 .expect(FAILED);
190 }
191
192 #[inline]
197 pub fn delta_next(&self) -> DurationNanos {
198 match self.timestamps.get(self.limit.get() - 1) {
199 Some(ts) => {
200 let diff = self
201 .clock
202 .borrow()
203 .timestamp_ns()
204 .saturating_duration_since(*ts);
205 DurationNanos::new(self.interval_ns.get()).saturating_sub(diff)
206 }
207 None => DurationNanos::default(),
208 }
209 }
210
211 #[inline]
212 fn delta_next_at(&self, now: UnixNanos) -> DurationNanos {
213 match self.timestamps.get(self.limit.get() - 1) {
214 Some(ts) => {
215 let diff = now.saturating_duration_since(*ts);
216 DurationNanos::new(self.interval_ns.get()).saturating_sub(diff)
217 }
218 None => DurationNanos::default(),
219 }
220 }
221
222 #[inline]
225 pub fn reset(&mut self) {
226 self.cancel_timer_internal();
227 self.buffer.clear();
228 self.recv_count = 0;
229 self.sent_count = 0;
230 self.is_limiting = false;
231 self.timestamps.clear();
232 }
233}
234
235impl<T, F> Throttler<T, F> {
236 fn cancel_timer_internal(&self) {
243 if let Ok(mut clock) = self.clock.try_borrow_mut() {
244 clock.cancel_timer(&self.timer_name);
245 }
246 }
247
248 fn count_in_window(&self, now: UnixNanos) -> usize {
251 let Some(interval_start) = now.checked_sub(DurationNanos::new(self.interval_ns.get()))
252 else {
253 return self.timestamps.len();
254 };
255
256 if let Some(oldest) = self.timestamps.back()
257 && *oldest > interval_start
258 {
259 return self.timestamps.len();
260 }
261
262 match self.timestamps.front() {
263 Some(newest) if *newest > interval_start => {}
264 _ => return 0,
265 }
266
267 self.timestamps
268 .iter()
269 .take_while(|&&ts| ts > interval_start)
270 .count()
271 }
272
273 #[inline]
275 pub const fn limit(&self) -> usize {
276 self.limit.get()
277 }
278
279 #[inline]
281 pub const fn interval_ns(&self) -> DurationNanos {
282 DurationNanos::new(self.interval_ns.get())
283 }
284
285 #[inline]
287 pub const fn rate_limit(&self) -> RateLimit {
288 RateLimit {
289 limit: self.limit,
290 interval_ns: self.interval_ns,
291 }
292 }
293
294 #[inline]
296 pub fn qsize(&self) -> usize {
297 self.buffer.len()
298 }
299
300 #[inline]
302 pub fn used(&self) -> f64 {
303 if self.timestamps.is_empty() {
304 return 0.0;
305 }
306 let messages_in_current_interval = self.count_in_window(self.clock.borrow().timestamp_ns());
307 (messages_in_current_interval as f64) / (self.limit.get() as f64)
308 }
309
310 #[inline]
312 pub const fn is_limiting(&self) -> bool {
313 self.is_limiting
314 }
315
316 #[inline]
318 pub const fn recv_count(&self) -> usize {
319 self.recv_count
320 }
321
322 #[inline]
324 pub const fn sent_count(&self) -> usize {
325 self.sent_count
326 }
327}
328
329impl<T, F> Throttler<T, F>
330where
331 T: 'static + Debug,
332 F: Fn(T) + 'static,
333{
334 pub fn to_actor(self) -> Rc<UnsafeCell<Self>> {
337 let process_handler = ThrottlerProcess::<T, F>::new(self.actor_id);
339 msgbus::register_any(
340 process_handler.id().into(),
341 ShareableMessageHandler::from(Rc::new(process_handler) as Rc<dyn Handler<dyn Any>>),
342 );
343
344 register_actor(self)
346 }
347
348 pub fn dispose(&mut self) {
357 self.cancel_timer_internal();
358 msgbus::deregister_any(process_endpoint(self.actor_id));
359 with_actor_registry(|registry| {
360 registry.remove(&self.actor_id);
361 });
362 }
363
364 #[inline]
365 pub(crate) fn send_msg(&mut self, msg: T) {
366 let now = self.clock.borrow().timestamp_ns();
367
368 if self.timestamps.len() >= self.limit.get() {
369 self.timestamps.pop_back();
370 }
371 self.timestamps.push_front(now);
372
373 self.sent_count += 1;
374 (self.output_send)(msg);
375 }
376
377 #[inline]
385 pub fn try_reserve(&mut self, count: usize) -> bool {
386 self.recv_count += count;
387
388 if count == 0 {
389 return true;
390 }
391
392 let now = self.clock.borrow().timestamp_ns();
393 let delta = self.delta_next_at(now);
394 if self.is_limiting && delta.is_zero() && self.buffer.is_empty() {
395 self.is_limiting = false;
396 }
397
398 if self.is_limiting {
399 return false;
400 }
401
402 let used = self.count_in_window(now);
403
404 if self.limit.get().saturating_sub(used) < count {
405 self.is_limiting = true;
406
407 if !delta.is_zero() {
408 self.set_timer(Some(throttler_resume::<T, F>(self.actor_id)));
409 }
410 return false;
411 }
412
413 for _ in 0..count {
414 if self.timestamps.len() >= self.limit.get() {
415 self.timestamps.pop_back();
416 }
417 self.timestamps.push_front(now);
418 }
419 self.sent_count += count;
420 true
421 }
422
423 #[inline]
424 pub(crate) fn limit_msg(&mut self, msg: T) {
425 if self.output_drop.is_none() {
426 self.buffer.push_front(msg);
427 log::debug!("Buffering {}", self.buffer.len());
428
429 if !self.is_limiting {
430 log::debug!("Limiting");
431 let cb = Some(ThrottlerProcess::<T, F>::new(self.actor_id).get_timer_callback());
432 self.set_timer(cb);
433 self.is_limiting = true;
434 }
435 } else {
436 log::debug!("Dropping");
437
438 if let Some(drop) = &self.output_drop {
439 drop(msg);
440 }
441
442 if !self.is_limiting {
443 log::debug!("Limiting");
444 self.set_timer(Some(throttler_resume::<T, F>(self.actor_id)));
445 self.is_limiting = true;
446 }
447 }
448 }
449
450 #[inline]
451 pub fn send(&mut self, msg: T)
452 where
453 T: 'static,
454 F: Fn(T) + 'static,
455 {
456 self.recv_count += 1;
457
458 if self.large_limit && self.timestamps.len() < self.limit.get() && !self.is_limiting {
459 self.send_msg(msg);
460 return;
461 }
462
463 let delta = if self.is_limiting && !self.buffer.is_empty() {
464 DurationNanos::default()
465 } else {
466 self.delta_next()
467 };
468
469 if self.is_limiting && delta.is_zero() && self.buffer.is_empty() {
474 self.is_limiting = false;
475 }
476
477 if self.is_limiting || !delta.is_zero() {
478 self.limit_msg(msg);
479 } else {
480 self.send_msg(msg);
481 }
482 }
483}
484
485fn process_endpoint(actor_id: Ustr) -> MStr<Endpoint> {
488 MStr::endpoint(format!("{actor_id}_process")).expect(FAILED)
489}
490
491struct ThrottlerProcess<T, F> {
496 actor_id: Ustr,
497 endpoint: MStr<Endpoint>,
498 phantom_t: PhantomData<T>,
499 phantom_f: PhantomData<F>,
500}
501
502impl<T, F> ThrottlerProcess<T, F>
503where
504 T: Debug,
505{
506 pub(crate) fn new(actor_id: Ustr) -> Self {
507 Self {
508 actor_id,
509 endpoint: process_endpoint(actor_id),
510 phantom_t: PhantomData,
511 phantom_f: PhantomData,
512 }
513 }
514
515 pub(crate) fn get_timer_callback(&self) -> TimeEventCallback {
516 let endpoint = self.endpoint;
517 TimeEventCallback::from(move |event: TimeEvent| {
518 msgbus::send_any(endpoint, &(event));
519 })
520 }
521}
522
523impl<T, F> Handler<dyn Any> for ThrottlerProcess<T, F>
524where
525 T: 'static + Debug,
526 F: Fn(T) + 'static,
527{
528 fn id(&self) -> Ustr {
529 *self.endpoint
530 }
531
532 fn handle(&self, _message: &dyn Any) {
533 let Some(mut throttler) = try_get_actor_unchecked::<Throttler<T, F>>(&self.actor_id) else {
536 return;
537 };
538
539 while let Some(msg) = throttler.buffer.pop_back() {
540 throttler.send_msg(msg);
541
542 if !throttler.buffer.is_empty() && !throttler.delta_next().is_zero() {
546 throttler.is_limiting = true;
547 throttler.set_timer(Some(self.get_timer_callback()));
548 return;
549 }
550 }
551
552 throttler.is_limiting = false;
553 }
554}
555
556impl<T, F> Drop for Throttler<T, F> {
557 fn drop(&mut self) {
558 self.cancel_timer_internal();
562 }
563}
564
565pub fn throttler_resume<T, F>(actor_id: Ustr) -> TimeEventCallback
575where
576 T: 'static + Debug,
577 F: Fn(T) + 'static,
578{
579 TimeEventCallback::from(move |_event: TimeEvent| {
580 if let Some(mut throttler) = try_get_actor_unchecked::<Throttler<T, F>>(&actor_id) {
581 if throttler.buffer.is_empty() {
582 throttler.is_limiting = false;
583 } else {
584 let cb = Some(ThrottlerProcess::<T, F>::new(actor_id).get_timer_callback());
585 throttler.set_timer(cb);
586 }
587 }
588 })
589}
590
591#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
600#[serde(deny_unknown_fields)]
601pub struct RateLimit {
602 limit: NonZeroUsize,
603 interval_ns: NonZeroU64,
604}
605
606impl RateLimit {
607 pub fn new_checked(limit: usize, interval_ns: DurationNanos) -> anyhow::Result<Self> {
613 let limit = NonZeroUsize::new(limit)
614 .ok_or_else(|| anyhow::anyhow!("Invalid limit: {limit} (must be non-zero)"))?;
615
616 let interval_ns = NonZeroU64::new(interval_ns.as_u64()).ok_or_else(|| {
617 anyhow::anyhow!("Invalid interval_ns: {interval_ns} (must be non-zero)")
618 })?;
619
620 Ok(Self { limit, interval_ns })
621 }
622
623 #[must_use]
629 pub fn new(limit: usize, interval_ns: DurationNanos) -> Self {
630 Self::new_checked(limit, interval_ns).expect(FAILED)
631 }
632
633 #[must_use]
635 pub const fn limit(&self) -> usize {
636 self.limit.get()
637 }
638
639 #[must_use]
641 pub const fn interval_ns(&self) -> DurationNanos {
642 DurationNanos::new(self.interval_ns.get())
643 }
644}
645
646impl Display for RateLimit {
647 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
648 let interval = self.interval_ns();
649 let limit = self.limit();
650 let total_secs = interval.as_secs();
651 let remainder_ns = interval.subsec_nanos();
652 let hours = total_secs / 3600;
653 let minutes = (total_secs % 3600) / 60;
654 let seconds = total_secs % 60;
655
656 if remainder_ns == 0 {
657 write!(f, "{limit}/{hours:02}:{minutes:02}:{seconds:02}")
658 } else {
659 let micros = remainder_ns / 1_000;
660 write!(
661 f,
662 "{limit}/{hours:02}:{minutes:02}:{seconds:02}.{micros:06}"
663 )
664 }
665 }
666}
667
668#[cfg(test)]
669mod tests {
670 use std::{
671 cell::{RefCell, UnsafeCell},
672 rc::Rc,
673 };
674
675 use nautilus_core::{DurationNanos, UUID4, UnixNanos};
676 use rstest::{fixture, rstest};
677 use ustr::Ustr;
678
679 use super::{MAX_INITIAL_TIMESTAMPS_CAPACITY, RateLimit, Throttler, ThrottlerProcess};
680 use crate::{
681 clock::{Clock, VirtualClock},
682 msgbus::{self, Handler},
683 };
684 type SharedThrottler = Rc<UnsafeCell<Throttler<u64, Box<dyn Fn(u64)>>>>;
685
686 #[derive(Clone)]
691 struct TestThrottler {
692 throttler: SharedThrottler,
693 clock: Rc<RefCell<VirtualClock>>,
694 interval: DurationNanos,
695 }
696
697 #[allow(unsafe_code)]
698 impl TestThrottler {
699 #[expect(clippy::mut_from_ref)]
700 pub(crate) fn get_throttler(&self) -> &mut Throttler<u64, Box<dyn Fn(u64)>> {
701 unsafe { &mut *self.throttler.get() }
702 }
703 }
704
705 fn timer_count_with_prefix(
709 throttler: &Throttler<u64, Box<dyn Fn(u64)>>,
710 prefix: &str,
711 ) -> usize {
712 throttler
713 .clock
714 .borrow()
715 .timer_names()
716 .iter()
717 .filter(|name| name.starts_with(prefix))
718 .count()
719 }
720
721 #[allow(unsafe_code)]
722 #[expect(clippy::mut_from_ref)]
723 fn access_shared(t: &SharedThrottler) -> &mut Throttler<u64, Box<dyn Fn(u64)>> {
724 unsafe { &mut *t.get() }
725 }
726
727 #[rstest]
728 #[case(0, 1_000)]
729 #[case(1_000, 0)]
730 fn test_rate_limit_new_checked_rejects_zero(#[case] limit: usize, #[case] interval_ns: u64) {
731 assert!(RateLimit::new_checked(limit, DurationNanos::new(interval_ns)).is_err());
732 }
733
734 #[rstest]
735 #[case(0, 1_000)]
736 #[case(1_000, 0)]
737 #[should_panic]
738 fn test_rate_limit_new_panics_on_zero(#[case] limit: usize, #[case] interval_ns: u64) {
739 let _ = RateLimit::new(limit, DurationNanos::new(interval_ns));
740 }
741
742 #[rstest]
743 fn test_rate_limit_new_checked_accepts_positive() {
744 let rate = RateLimit::new_checked(5, DurationNanos::new(10)).unwrap();
745
746 assert_eq!(rate.limit(), 5);
747 assert_eq!(rate.interval_ns(), DurationNanos::new(10));
748 }
749
750 #[rstest]
751 #[case::whole_seconds(100, 1_000_000_000, "100/00:00:01")]
752 #[case::hours_minutes_seconds(17, 3_723_000_000_000, "17/01:02:03")]
753 #[case::large_hours(23, 360_000_000_000_000, "23/100:00:00")]
754 #[case::fractional_seconds(31, 1_234_567_000, "31/00:00:01.234567")]
755 #[case::truncated_nanoseconds(41, 1_234_567_890, "41/00:00:01.234567")]
756 #[case::below_microsecond(53, 999, "53/00:00:00.000000")]
757 fn test_rate_limit_display(
758 #[case] limit: usize,
759 #[case] interval_ns: u64,
760 #[case] expected: &str,
761 ) {
762 let rate = RateLimit::new(limit, DurationNanos::new(interval_ns));
763
764 assert_eq!(rate.to_string(), expected);
765 }
766
767 #[fixture]
768 pub fn test_throttler_buffered() -> TestThrottler {
769 let output_send: Box<dyn Fn(u64)> = Box::new(|msg: u64| {
770 log::debug!("Sent: {msg}");
771 });
772 let clock = Rc::new(RefCell::new(VirtualClock::new()));
773 let inner_clock = Rc::clone(&clock);
774 let rate_limit = RateLimit::new(5, DurationNanos::new(10));
775 let interval = rate_limit.interval_ns();
776 let actor_id = Ustr::from(UUID4::new().as_str());
777
778 TestThrottler {
779 throttler: Throttler::new(
780 rate_limit,
781 clock,
782 "buffer_timer",
783 output_send,
784 None,
785 actor_id,
786 )
787 .to_actor(),
788 clock: inner_clock,
789 interval,
790 }
791 }
792
793 #[fixture]
794 pub fn test_throttler_unbuffered() -> TestThrottler {
795 let output_send: Box<dyn Fn(u64)> = Box::new(|msg: u64| {
796 log::debug!("Sent: {msg}");
797 });
798 let output_drop: Box<dyn Fn(u64)> = Box::new(|msg: u64| {
799 log::debug!("Dropped: {msg}");
800 });
801 let clock = Rc::new(RefCell::new(VirtualClock::new()));
802 let inner_clock = Rc::clone(&clock);
803 let rate_limit = RateLimit::new(5, DurationNanos::new(10));
804 let interval = rate_limit.interval_ns();
805 let actor_id = Ustr::from(UUID4::new().as_str());
806
807 TestThrottler {
808 throttler: Throttler::new(
809 rate_limit,
810 clock,
811 "dropper_timer",
812 output_send,
813 Some(output_drop),
814 actor_id,
815 )
816 .to_actor(),
817 clock: inner_clock,
818 interval,
819 }
820 }
821
822 #[rstest]
823 fn test_buffering_send_to_limit_becomes_throttled(test_throttler_buffered: TestThrottler) {
824 let throttler = test_throttler_buffered.get_throttler();
825 for _ in 0..6 {
826 throttler.send(42);
827 }
828 assert_eq!(throttler.qsize(), 1);
829
830 assert!(throttler.is_limiting);
831 assert_eq!(throttler.recv_count, 6);
832 assert_eq!(throttler.sent_count, 5);
833 assert_eq!(timer_count_with_prefix(throttler, "buffer_timer"), 1);
834 }
835
836 #[rstest]
837 fn test_buffering_used_when_sent_to_limit_returns_one(test_throttler_buffered: TestThrottler) {
838 let throttler = test_throttler_buffered.get_throttler();
839
840 for _ in 0..5 {
841 throttler.send(42);
842 }
843
844 assert_eq!(throttler.used(), 1.0);
845 assert_eq!(throttler.recv_count, 5);
846 assert_eq!(throttler.sent_count, 5);
847 }
848
849 #[rstest]
850 fn test_buffering_used_when_half_interval_from_limit_returns_one(
851 test_throttler_buffered: TestThrottler,
852 ) {
853 let throttler = test_throttler_buffered.get_throttler();
854
855 for _ in 0..5 {
856 throttler.send(42);
857 }
858
859 let half_interval = test_throttler_buffered.interval / 2;
860 {
862 let mut clock = test_throttler_buffered.clock.borrow_mut();
863 clock.advance_time(UnixNanos::default() + half_interval, true);
864 }
865
866 assert_eq!(throttler.used(), 1.0);
867 assert_eq!(throttler.recv_count, 5);
868 assert_eq!(throttler.sent_count, 5);
869 }
870
871 #[rstest]
872 fn test_buffering_used_before_limit_when_halfway_returns_half(
873 test_throttler_buffered: TestThrottler,
874 ) {
875 let throttler = test_throttler_buffered.get_throttler();
876
877 for _ in 0..3 {
878 throttler.send(42);
879 }
880
881 assert_eq!(throttler.used(), 0.6);
882 assert_eq!(throttler.recv_count, 3);
883 assert_eq!(throttler.sent_count, 3);
884 }
885
886 #[rstest]
887 fn test_try_reserve_counts_messages_without_output(test_throttler_buffered: TestThrottler) {
888 let throttler = test_throttler_buffered.get_throttler();
889
890 assert!(throttler.try_reserve(3));
891
892 assert_eq!(throttler.used(), 0.6);
893 assert_eq!(throttler.recv_count, 3);
894 assert_eq!(throttler.sent_count, 3);
895 assert_eq!(throttler.qsize(), 0);
896 }
897
898 #[rstest]
899 fn test_try_reserve_rejects_when_full_batch_exceeds_limit(
900 test_throttler_buffered: TestThrottler,
901 ) {
902 let throttler = test_throttler_buffered.get_throttler();
903
904 assert!(throttler.try_reserve(3));
905 assert!(!throttler.try_reserve(3));
906
907 assert_eq!(throttler.used(), 0.6);
908 assert_eq!(throttler.recv_count, 6);
909 assert_eq!(throttler.sent_count, 3);
910 assert_eq!(throttler.qsize(), 0);
911 assert!(throttler.is_limiting);
912 assert_eq!(timer_count_with_prefix(throttler, "buffer_timer"), 0);
916
917 assert!(throttler.try_reserve(2));
918
919 assert_eq!(throttler.used(), 1.0);
920 assert_eq!(throttler.recv_count, 8);
921 assert_eq!(throttler.sent_count, 5);
922 assert_eq!(throttler.qsize(), 0);
923 assert!(!throttler.is_limiting);
924 }
925
926 #[rstest]
927 fn test_try_reserve_rejects_batch_larger_than_limit() {
928 let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
929 let mut throttler = Throttler::<u64, Box<dyn Fn(u64)>>::new(
930 RateLimit::new(5, DurationNanos::new(10)),
931 clock,
932 "reserve_over_limit",
933 Box::new(|_| ()) as Box<dyn Fn(u64)>,
934 None,
935 Ustr::from("reserve-over-limit-actor"),
936 );
937
938 assert!(!throttler.try_reserve(6));
939
940 assert_eq!(throttler.used(), 0.0);
941 assert_eq!(throttler.recv_count, 6);
942 assert_eq!(throttler.sent_count, 0);
943 assert_eq!(throttler.qsize(), 0);
944 assert!(throttler.is_limiting);
945 assert_eq!(throttler.clock.borrow().timer_count(), 0);
946 }
947
948 #[rstest]
949 fn test_try_reserve_zero_count_is_noop() {
950 let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
951 let mut throttler = Throttler::<u64, Box<dyn Fn(u64)>>::new(
952 RateLimit::new(5, DurationNanos::new(10)),
953 clock,
954 "reserve_zero",
955 Box::new(|_| ()) as Box<dyn Fn(u64)>,
956 None,
957 Ustr::from("reserve-zero-actor"),
958 );
959
960 assert!(throttler.try_reserve(0));
961
962 assert_eq!(throttler.used(), 0.0);
963 assert_eq!(throttler.recv_count, 0);
964 assert_eq!(throttler.sent_count, 0);
965 assert_eq!(throttler.qsize(), 0);
966 assert!(!throttler.is_limiting);
967 assert_eq!(throttler.clock.borrow().timer_count(), 0);
968 }
969
970 #[rstest]
971 fn test_buffering_refresh_when_at_limit_sends_remaining_items(
972 test_throttler_buffered: TestThrottler,
973 ) {
974 let throttler = test_throttler_buffered.get_throttler();
975
976 for _ in 0..6 {
977 throttler.send(42);
978 }
979
980 {
982 let mut clock = test_throttler_buffered.clock.borrow_mut();
983 let time_events = clock.advance_time(
984 UnixNanos::default() + test_throttler_buffered.interval,
985 true,
986 );
987
988 for each_event in clock.match_handlers(time_events) {
989 drop(clock); each_event.callback.call(each_event.event);
992
993 clock = test_throttler_buffered.clock.borrow_mut();
995 }
996 }
997
998 assert_eq!(throttler.used(), 0.2);
1000 assert_eq!(throttler.recv_count, 6);
1001 assert_eq!(throttler.sent_count, 6);
1002 assert_eq!(throttler.qsize(), 0);
1003 }
1004
1005 #[rstest]
1006 fn test_buffering_send_message_after_buffering_message(test_throttler_buffered: TestThrottler) {
1007 let throttler = test_throttler_buffered.get_throttler();
1008
1009 for _ in 0..6 {
1010 throttler.send(43);
1011 }
1012
1013 {
1015 let mut clock = test_throttler_buffered.clock.borrow_mut();
1016 let time_events = clock.advance_time(
1017 UnixNanos::default() + test_throttler_buffered.interval,
1018 true,
1019 );
1020
1021 for each_event in clock.match_handlers(time_events) {
1022 drop(clock); each_event.callback.call(each_event.event);
1025
1026 clock = test_throttler_buffered.clock.borrow_mut();
1028 }
1029 }
1030
1031 for _ in 0..6 {
1032 throttler.send(42);
1033 }
1034
1035 assert_eq!(throttler.used(), 1.0);
1037 assert_eq!(throttler.recv_count, 12);
1038 assert_eq!(throttler.sent_count, 10);
1039 assert_eq!(throttler.qsize(), 2);
1040 }
1041
1042 #[rstest]
1043 fn test_buffering_send_message_after_halfway_after_buffering_message(
1044 test_throttler_buffered: TestThrottler,
1045 ) {
1046 let throttler = test_throttler_buffered.get_throttler();
1047
1048 for _ in 0..6 {
1049 throttler.send(42);
1050 }
1051
1052 {
1054 let mut clock = test_throttler_buffered.clock.borrow_mut();
1055 let time_events = clock.advance_time(
1056 UnixNanos::default() + test_throttler_buffered.interval,
1057 true,
1058 );
1059
1060 for each_event in clock.match_handlers(time_events) {
1061 drop(clock); each_event.callback.call(each_event.event);
1064
1065 clock = test_throttler_buffered.clock.borrow_mut();
1067 }
1068 }
1069
1070 for _ in 0..3 {
1071 throttler.send(42);
1072 }
1073
1074 assert_eq!(throttler.used(), 0.8);
1076 assert_eq!(throttler.recv_count, 9);
1077 assert_eq!(throttler.sent_count, 9);
1078 assert_eq!(throttler.qsize(), 0);
1079 }
1080
1081 #[rstest]
1082 fn test_dropping_send_sends_message_to_handler(test_throttler_unbuffered: TestThrottler) {
1083 let throttler = test_throttler_unbuffered.get_throttler();
1084 throttler.send(42);
1085
1086 assert!(!throttler.is_limiting);
1087 assert_eq!(throttler.recv_count, 1);
1088 assert_eq!(throttler.sent_count, 1);
1089 }
1090
1091 #[rstest]
1092 fn test_dropping_send_to_limit_drops_message(test_throttler_unbuffered: TestThrottler) {
1093 let throttler = test_throttler_unbuffered.get_throttler();
1094 for _ in 0..6 {
1095 throttler.send(42);
1096 }
1097 assert_eq!(throttler.qsize(), 0);
1098
1099 assert!(throttler.is_limiting);
1100 assert_eq!(throttler.used(), 1.0);
1101 assert_eq!(throttler.clock.borrow().timer_count(), 1);
1102 assert_eq!(timer_count_with_prefix(throttler, "dropper_timer"), 1);
1103 assert_eq!(throttler.recv_count, 6);
1104 assert_eq!(throttler.sent_count, 5);
1105 }
1106
1107 #[rstest]
1108 fn test_dropping_advance_time_when_at_limit_dropped_message(
1109 test_throttler_unbuffered: TestThrottler,
1110 ) {
1111 let throttler = test_throttler_unbuffered.get_throttler();
1112 for _ in 0..6 {
1113 throttler.send(42);
1114 }
1115
1116 {
1118 let mut clock = test_throttler_unbuffered.clock.borrow_mut();
1119 let time_events = clock.advance_time(
1120 UnixNanos::default() + test_throttler_unbuffered.interval,
1121 true,
1122 );
1123
1124 for each_event in clock.match_handlers(time_events) {
1125 drop(clock); each_event.callback.call(each_event.event);
1128
1129 clock = test_throttler_unbuffered.clock.borrow_mut();
1131 }
1132 }
1133
1134 assert_eq!(throttler.clock.borrow().timer_count(), 0);
1135 assert!(!throttler.is_limiting);
1136 assert_eq!(throttler.used(), 0.0);
1137 assert_eq!(throttler.recv_count, 6);
1138 assert_eq!(throttler.sent_count, 5);
1139 }
1140
1141 #[rstest]
1142 fn test_dropping_send_message_after_dropping_message(test_throttler_unbuffered: TestThrottler) {
1143 let throttler = test_throttler_unbuffered.get_throttler();
1144 for _ in 0..6 {
1145 throttler.send(42);
1146 }
1147
1148 {
1150 let mut clock = test_throttler_unbuffered.clock.borrow_mut();
1151 let time_events = clock.advance_time(
1152 UnixNanos::default() + test_throttler_unbuffered.interval,
1153 true,
1154 );
1155
1156 for each_event in clock.match_handlers(time_events) {
1157 drop(clock); each_event.callback.call(each_event.event);
1160
1161 clock = test_throttler_unbuffered.clock.borrow_mut();
1163 }
1164 }
1165
1166 throttler.send(42);
1167
1168 assert_eq!(throttler.used(), 0.2);
1169 assert_eq!(throttler.clock.borrow().timer_count(), 0);
1170 assert!(!throttler.is_limiting);
1171 assert_eq!(throttler.recv_count, 7);
1172 assert_eq!(throttler.sent_count, 6);
1173 }
1174
1175 #[rstest]
1176 fn test_embedded_dropping_auto_resets_after_window_without_actor_callback() {
1177 let clock: Rc<RefCell<VirtualClock>> = Rc::new(RefCell::new(VirtualClock::new()));
1178 let sent = Rc::new(RefCell::new(0));
1179 let dropped = Rc::new(RefCell::new(0));
1180
1181 let sent_cb = {
1182 let sent = Rc::clone(&sent);
1183 Box::new(move |_| *sent.borrow_mut() += 1) as Box<dyn Fn(u64)>
1184 };
1185 let drop_cb = {
1186 let dropped = Rc::clone(&dropped);
1187 Box::new(move |_| *dropped.borrow_mut() += 1) as Box<dyn Fn(u64)>
1188 };
1189
1190 let mut throttler = Throttler::new(
1191 RateLimit::new(5, DurationNanos::new(10)),
1192 Rc::clone(&clock) as Rc<RefCell<dyn Clock>>,
1193 "embedded_drop_timer",
1194 sent_cb,
1195 Some(drop_cb),
1196 Ustr::from("embedded-drop-actor"),
1197 );
1198
1199 for _ in 0..6 {
1200 throttler.send(42);
1201 }
1202 let events = clock.borrow_mut().advance_time(10.into(), true);
1203 throttler.send(42);
1204
1205 assert_eq!(events.len(), 1);
1206 assert_eq!(*sent.borrow(), 6);
1207 assert_eq!(*dropped.borrow(), 1);
1208 assert_eq!(throttler.recv_count, 7);
1209 assert_eq!(throttler.sent_count, 6);
1210 assert!(!throttler.is_limiting);
1211 assert_eq!(throttler.clock.borrow().timer_count(), 0);
1212 }
1213
1214 #[rstest]
1215 fn test_large_limit_fast_path_admits_until_limit_then_limits() {
1216 let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
1217 let limit = MAX_INITIAL_TIMESTAMPS_CAPACITY + 1;
1218 let mut throttler = Throttler::<u64, Box<dyn Fn(u64)>>::new(
1219 RateLimit::new(limit, DurationNanos::new(10)),
1220 clock,
1221 "large_limit_timer",
1222 Box::new(|_| ()) as Box<dyn Fn(u64)>,
1223 None,
1224 Ustr::from("large-limit-actor"),
1225 );
1226
1227 for _ in 0..limit {
1228 throttler.send(42);
1229 }
1230 throttler.send(42);
1231
1232 assert_eq!(throttler.used(), 1.0);
1233 assert_eq!(throttler.recv_count, limit + 1);
1234 assert_eq!(throttler.sent_count, limit);
1235 assert_eq!(throttler.qsize(), 1);
1236 assert!(throttler.is_limiting);
1237 assert_eq!(throttler.clock.borrow().timer_count(), 1);
1238 }
1239
1240 #[rstest]
1241 fn test_new_preserves_rate_limit() {
1242 let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
1243 let rate_limit = RateLimit::new(5, DurationNanos::new(10));
1244
1245 let throttler = Throttler::<u64, Box<dyn Fn(u64)>>::new(
1246 rate_limit,
1247 clock,
1248 "rate_limit",
1249 Box::new(|_| ()) as Box<dyn Fn(u64)>,
1250 None,
1251 Ustr::from("rate-limit-actor"),
1252 );
1253
1254 assert_eq!(throttler.rate_limit(), rate_limit);
1255 assert_eq!(throttler.limit(), 5);
1256 assert_eq!(throttler.interval_ns(), DurationNanos::new(10));
1257 }
1258
1259 #[rstest]
1260 fn test_debug_output_includes_identity_and_state() {
1261 let clock: Rc<RefCell<dyn Clock>> = Rc::new(RefCell::new(VirtualClock::new()));
1262 let actor_id = Ustr::from("debug-actor");
1263 let mut throttler = Throttler::<u64, Box<dyn Fn(u64)>>::new(
1264 RateLimit::new(5, DurationNanos::new(10)),
1265 clock,
1266 "debug_timer",
1267 Box::new(|_| ()) as Box<dyn Fn(u64)>,
1268 None,
1269 actor_id,
1270 );
1271
1272 throttler.send(42);
1273
1274 let debug = format!("{throttler:?}");
1275 let timer_name = Ustr::from("debug_timer-debug-actor");
1276
1277 assert!(debug.contains(&format!("actor_id: {actor_id:?}")));
1278 assert!(debug.contains(&format!("timer_name: {timer_name:?}")));
1279 assert!(debug.contains("limit: 5"));
1280 assert!(debug.contains("interval_ns: 10"));
1281 assert!(debug.contains("is_limiting: false"));
1282 assert!(debug.contains("recv_count: 1"));
1283 assert!(debug.contains("sent_count: 1"));
1284 }
1285
1286 #[rstest]
1287 fn test_reset_clears_state_and_cancels_timer(test_throttler_buffered: TestThrottler) {
1288 let throttler = test_throttler_buffered.get_throttler();
1289
1290 for _ in 0..6 {
1291 throttler.send(42);
1292 }
1293 assert_eq!(timer_count_with_prefix(throttler, "buffer_timer"), 1);
1294 assert_eq!(throttler.qsize(), 1);
1295
1296 throttler.reset();
1297
1298 assert_eq!(throttler.qsize(), 0);
1299 assert_eq!(throttler.recv_count, 0);
1300 assert_eq!(throttler.sent_count, 0);
1301 assert!(!throttler.is_limiting);
1302 assert!(throttler.timestamps.is_empty());
1303 assert_eq!(timer_count_with_prefix(throttler, "buffer_timer"), 0);
1304 assert_eq!(throttler.clock.borrow().timer_count(), 0);
1305 }
1306
1307 #[rstest]
1308 fn test_two_throttlers_share_clock_without_timer_collision() {
1309 let clock: Rc<RefCell<VirtualClock>> = Rc::new(RefCell::new(VirtualClock::new()));
1310 let interval = 10u64;
1311
1312 let mk = |base: &str| -> SharedThrottler {
1313 let clock: Rc<RefCell<dyn Clock>> = Rc::clone(&clock) as Rc<RefCell<dyn Clock>>;
1314 Throttler::new(
1315 RateLimit::new(5, DurationNanos::new(interval)),
1316 clock,
1317 base,
1318 Box::new(|_| ()) as Box<dyn Fn(u64)>,
1319 None,
1320 Ustr::from(UUID4::new().as_str()),
1321 )
1322 .to_actor()
1323 };
1324
1325 let t1 = mk("shared_timer");
1326 let t2 = mk("shared_timer");
1327
1328 {
1331 let t1 = access_shared(&t1);
1332
1333 for _ in 0..6 {
1334 t1.send(42);
1335 }
1336 }
1337 {
1338 let t2 = access_shared(&t2);
1339
1340 for _ in 0..6 {
1341 t2.send(42);
1342 }
1343 }
1344
1345 let clock_ref = clock.borrow();
1346 let names = clock_ref.timer_names();
1347 let shared_count = names
1348 .iter()
1349 .filter(|n| n.starts_with("shared_timer"))
1350 .count();
1351 assert_eq!(
1352 shared_count, 2,
1353 "two distinct timers expected, found {names:?}"
1354 );
1355 }
1356
1357 #[rstest]
1358 fn test_try_reserve_then_send_interleaved(test_throttler_buffered: TestThrottler) {
1359 let throttler = test_throttler_buffered.get_throttler();
1360
1361 assert!(throttler.try_reserve(3));
1364 throttler.send(42);
1365
1366 assert_eq!(throttler.recv_count, 4);
1367 assert_eq!(throttler.sent_count, 4);
1368 assert_eq!(throttler.used(), 0.8);
1369 assert!(!throttler.is_limiting);
1370 }
1371
1372 #[rstest]
1373 #[case::buffered(false)]
1374 #[case::drop(true)]
1375 fn test_send_at_unrepresentable_deadline_stays_limited(#[case] drop_mode: bool) {
1376 let clock = Rc::new(RefCell::new(VirtualClock::new()));
1377 clock
1378 .borrow_mut()
1379 .advance_time(UnixNanos::new(u64::MAX - 5), true);
1380 let sent = Rc::new(RefCell::new(Vec::new()));
1381 let dropped = Rc::new(RefCell::new(Vec::new()));
1382
1383 let output_send = {
1384 let sent = Rc::clone(&sent);
1385 Box::new(move |msg| sent.borrow_mut().push(msg)) as Box<dyn Fn(u64)>
1386 };
1387
1388 let output_drop = drop_mode.then(|| {
1389 let dropped = Rc::clone(&dropped);
1390 Box::new(move |msg| dropped.borrow_mut().push(msg)) as Box<dyn Fn(u64)>
1391 });
1392
1393 let mut throttler = Throttler::new(
1394 RateLimit::new(1, DurationNanos::new(10)),
1395 Rc::clone(&clock) as Rc<RefCell<dyn Clock>>,
1396 "overflow_send_timer",
1397 output_send,
1398 output_drop,
1399 Ustr::from("overflow-send-actor"),
1400 );
1401
1402 throttler.send(1);
1403 throttler.send(2);
1404 let events = clock.borrow_mut().advance_time(UnixNanos::max(), true);
1405 throttler.send(3);
1406
1407 assert!(events.is_empty());
1408 assert_eq!(*sent.borrow(), vec![1_u64]);
1409 assert_eq!(
1410 *dropped.borrow(),
1411 if drop_mode { vec![2_u64, 3] } else { vec![] }
1412 );
1413 assert_eq!(throttler.qsize(), if drop_mode { 0 } else { 2 });
1414 assert_eq!(throttler.recv_count(), 3);
1415 assert_eq!(throttler.sent_count(), 1);
1416 assert!(throttler.is_limiting());
1417 assert_eq!(clock.borrow().timer_count(), 0);
1418 }
1419
1420 #[rstest]
1421 fn test_try_reserve_at_unrepresentable_deadline_stays_limited() {
1422 let clock = Rc::new(RefCell::new(VirtualClock::new()));
1423 clock
1424 .borrow_mut()
1425 .advance_time(UnixNanos::new(u64::MAX - 5), true);
1426
1427 let mut throttler = Throttler::new(
1428 RateLimit::new(1, DurationNanos::new(10)),
1429 Rc::clone(&clock) as Rc<RefCell<dyn Clock>>,
1430 "overflow_reserve_timer",
1431 Box::new(|_| ()) as Box<dyn Fn(u64)>,
1432 None,
1433 Ustr::from("overflow-reserve-actor"),
1434 );
1435
1436 assert!(throttler.try_reserve(1));
1437 assert!(!throttler.try_reserve(1));
1438 let events = clock.borrow_mut().advance_time(UnixNanos::max(), true);
1439 assert!(!throttler.try_reserve(1));
1440
1441 assert!(events.is_empty());
1442 assert_eq!(throttler.qsize(), 0);
1443 assert_eq!(throttler.recv_count(), 3);
1444 assert_eq!(throttler.sent_count(), 1);
1445 assert!(throttler.is_limiting());
1446 assert_eq!(clock.borrow().timer_count(), 0);
1447 }
1448
1449 #[rstest]
1450 #[case::drains(2, 0, false)]
1451 #[case::rearm_overflow(3, 1, true)]
1452 fn test_buffered_send_at_maximum_representable_deadline(
1453 #[case] received: u64,
1454 #[case] expected_qsize: usize,
1455 #[case] expected_limiting: bool,
1456 ) {
1457 let clock = Rc::new(RefCell::new(VirtualClock::new()));
1458 clock
1459 .borrow_mut()
1460 .advance_time(UnixNanos::new(u64::MAX - 10), true);
1461 let sent = Rc::new(RefCell::new(Vec::new()));
1462
1463 let output_send = {
1464 let sent = Rc::clone(&sent);
1465 Box::new(move |msg| sent.borrow_mut().push(msg)) as Box<dyn Fn(u64)>
1466 };
1467
1468 let throttler = Throttler::new(
1469 RateLimit::new(1, DurationNanos::new(10)),
1470 Rc::clone(&clock) as Rc<RefCell<dyn Clock>>,
1471 "maximum_deadline_timer",
1472 output_send,
1473 None,
1474 Ustr::from("maximum-deadline-actor"),
1475 )
1476 .to_actor();
1477 let throttler = access_shared(&throttler);
1478 for msg in 1..=received {
1479 throttler.send(msg);
1480 }
1481
1482 let early_events = clock
1483 .borrow_mut()
1484 .advance_time(UnixNanos::new(u64::MAX - 1), true);
1485 let due_events = clock.borrow_mut().advance_time(UnixNanos::max(), true);
1486 assert!(early_events.is_empty());
1487 assert_eq!(due_events.len(), 1);
1488 assert_eq!(due_events[0].ts_event, UnixNanos::max());
1489
1490 let handlers = clock.borrow().match_handlers(due_events);
1491 for handler in handlers {
1492 handler.callback.call(handler.event);
1493 }
1494
1495 assert_eq!(*sent.borrow(), vec![1_u64, 2]);
1496 assert_eq!(throttler.qsize(), expected_qsize);
1497 assert_eq!(throttler.recv_count(), received as usize);
1498 assert_eq!(throttler.sent_count(), 2);
1499 assert_eq!(throttler.is_limiting(), expected_limiting);
1500 assert_eq!(clock.borrow().timer_count(), 0);
1501 }
1502
1503 #[rstest]
1504 fn test_dispose_cancels_timer_and_deregisters_endpoint(test_throttler_buffered: TestThrottler) {
1505 let throttler = test_throttler_buffered.get_throttler();
1506
1507 for _ in 0..6 {
1508 throttler.send(42);
1509 }
1510 let actor_id = throttler.actor_id;
1511 let endpoint_name = format!("{actor_id}_process");
1512 assert_eq!(timer_count_with_prefix(throttler, "buffer_timer"), 1);
1513 assert!(msgbus::has_endpoint(&endpoint_name));
1514
1515 throttler.dispose();
1516
1517 assert_eq!(throttler.clock.borrow().timer_count(), 0);
1518 assert!(
1519 !msgbus::has_endpoint(&endpoint_name),
1520 "dispose must deregister the process endpoint"
1521 );
1522 }
1523
1524 #[rstest]
1525 fn test_try_reserve_then_buffered_sends_drain_in_order_after_window() {
1526 let clock: Rc<RefCell<VirtualClock>> = Rc::new(RefCell::new(VirtualClock::new()));
1527 let sent: Rc<RefCell<Vec<u64>>> = Rc::new(RefCell::new(Vec::new()));
1528 let sent_cb = {
1529 let sent = Rc::clone(&sent);
1530 Box::new(move |msg| sent.borrow_mut().push(msg)) as Box<dyn Fn(u64)>
1531 };
1532 let throttler = Throttler::new(
1533 RateLimit::new(5, DurationNanos::new(10)),
1534 Rc::clone(&clock) as Rc<RefCell<dyn Clock>>,
1535 "reserve_drain_timer",
1536 sent_cb,
1537 None,
1538 Ustr::from(UUID4::new().as_str()),
1539 )
1540 .to_actor();
1541 let throttler = access_shared(&throttler);
1542
1543 assert!(throttler.try_reserve(5));
1544 assert!(!throttler.try_reserve(1));
1545 assert!(throttler.is_limiting);
1546
1547 throttler.send(1);
1548 throttler.send(2);
1549 assert_eq!(throttler.qsize(), 2);
1550 assert!(sent.borrow().is_empty());
1551
1552 {
1555 let mut clock_ref = clock.borrow_mut();
1556 let time_events = clock_ref.advance_time(10.into(), true);
1557 for each_event in clock_ref.match_handlers(time_events) {
1558 drop(clock_ref);
1559 each_event.callback.call(each_event.event);
1560 clock_ref = clock.borrow_mut();
1561 }
1562 }
1563 assert!(throttler.is_limiting);
1564 assert_eq!(throttler.qsize(), 2);
1565 assert!(sent.borrow().is_empty());
1566
1567 throttler.send(3);
1569 assert_eq!(throttler.qsize(), 3);
1570 assert!(sent.borrow().is_empty());
1571
1572 for _ in 0..10 {
1573 if throttler.qsize() == 0 && !throttler.is_limiting {
1574 break;
1575 }
1576 let mut clock_ref = clock.borrow_mut();
1577 let current_time = clock_ref.get_time_ns();
1578 let time_events = clock_ref.advance_time(current_time + DurationNanos::new(10), true);
1579 for each_event in clock_ref.match_handlers(time_events) {
1580 drop(clock_ref);
1581 each_event.callback.call(each_event.event);
1582 clock_ref = clock.borrow_mut();
1583 }
1584 }
1585
1586 assert_eq!(*sent.borrow(), vec![1, 2, 3]);
1587 assert_eq!(throttler.qsize(), 0);
1588 assert!(!throttler.is_limiting);
1589 assert_eq!(throttler.sent_count, 8);
1590 assert_eq!(throttler.clock.borrow().timer_count(), 0);
1591 }
1592
1593 use proptest::prelude::*;
1598
1599 #[derive(Clone, Debug)]
1600 enum ThrottlerInput {
1601 SendMessage(u64),
1602 AdvanceClock(u8),
1603 }
1604
1605 fn throttler_input_strategy() -> impl Strategy<Value = ThrottlerInput> {
1607 prop_oneof![
1608 2 => prop::bool::ANY.prop_map(|_| ThrottlerInput::SendMessage(42)),
1609 8 => prop::num::u8::ANY.prop_map(|v| ThrottlerInput::AdvanceClock(v % 5 + 5)),
1610 ]
1611 }
1612
1613 fn throttler_test_strategy() -> impl Strategy<Value = Vec<ThrottlerInput>> {
1615 prop::collection::vec(throttler_input_strategy(), 10..=150)
1616 }
1617
1618 fn test_throttler_with_inputs(inputs: Vec<ThrottlerInput>, test_throttler: &TestThrottler) {
1619 let test_clock = test_throttler.clock.clone();
1620 let interval = test_throttler.interval;
1621 let throttler = test_throttler.get_throttler();
1622 let mut sent_count = 0;
1623
1624 for input in inputs {
1625 match input {
1626 ThrottlerInput::SendMessage(msg) => {
1627 throttler.send(msg);
1628 sent_count += 1;
1629 }
1630 ThrottlerInput::AdvanceClock(duration) => {
1631 let mut clock_ref = test_clock.borrow_mut();
1632 let current_time = clock_ref.get_time_ns();
1633 let time_events = clock_ref
1634 .advance_time(current_time + DurationNanos::new(u64::from(duration)), true);
1635
1636 for each_event in clock_ref.match_handlers(time_events) {
1637 drop(clock_ref);
1638 each_event.callback.call(each_event.event);
1639 clock_ref = test_clock.borrow_mut();
1640 }
1641 }
1642 }
1643
1644 let buffered_messages = throttler.qsize() > 0;
1649 let now = throttler.clock.borrow().timestamp_ns();
1650 let limit_filled_within_interval = throttler
1651 .timestamps
1652 .get(throttler.limit() - 1)
1653 .is_some_and(|&ts| (now - ts) < interval);
1654 let expected_limiting = buffered_messages && limit_filled_within_interval;
1655 assert_eq!(throttler.is_limiting, expected_limiting);
1656
1657 assert_eq!(sent_count, throttler.sent_count + throttler.qsize());
1659 }
1660
1661 for i in 1..=100u64 {
1665 if throttler.qsize() == 0 {
1666 break;
1667 }
1668 let advance_to = UnixNanos::default() + interval * 100 * i;
1669 let time_events = test_clock.borrow_mut().advance_time(advance_to, true);
1670 let mut clock_ref = test_clock.borrow_mut();
1671 for each_event in clock_ref.match_handlers(time_events) {
1672 drop(clock_ref);
1673 each_event.callback.call(each_event.event);
1674 clock_ref = test_clock.borrow_mut();
1675 }
1676 }
1677 assert_eq!(throttler.qsize(), 0);
1678 }
1679
1680 #[rstest]
1681 fn prop_test() {
1682 proptest!(|(inputs in throttler_test_strategy())| {
1685 let test_throttler = test_throttler_buffered();
1686 test_throttler_with_inputs(inputs, &test_throttler);
1687 });
1688 }
1689
1690 #[rstest]
1691 fn prop_test_dropping() {
1692 proptest!(|(inputs in throttler_test_strategy())| {
1696 let clock = Rc::new(RefCell::new(VirtualClock::new()));
1697 let sent: Rc<RefCell<usize>> = Rc::new(RefCell::new(0));
1698 let dropped: Rc<RefCell<usize>> = Rc::new(RefCell::new(0));
1699
1700 let sent_cb = {
1701 let sent = Rc::clone(&sent);
1702 Box::new(move |_| *sent.borrow_mut() += 1) as Box<dyn Fn(u64)>
1703 };
1704 let drop_cb = {
1705 let dropped = Rc::clone(&dropped);
1706 Box::new(move |_| *dropped.borrow_mut() += 1) as Box<dyn Fn(u64)>
1707 };
1708
1709 let interval = 10u64;
1710 let throttler = Throttler::new(
1711 RateLimit::new(5, DurationNanos::new(interval)),
1712 Rc::clone(&clock) as Rc<RefCell<dyn Clock>>,
1713 "prop_drop_timer",
1714 sent_cb,
1715 Some(drop_cb),
1716 Ustr::from(UUID4::new().as_str()),
1717 )
1718 .to_actor();
1719 let throttler = access_shared(&throttler);
1720
1721 for input in inputs {
1722 match input {
1723 ThrottlerInput::SendMessage(msg) => {
1724 throttler.send(msg);
1725 }
1726 ThrottlerInput::AdvanceClock(duration) => {
1727 let mut clock_ref = clock.borrow_mut();
1728 let current_time = clock_ref.get_time_ns();
1729 let time_events = clock_ref.advance_time(
1730 current_time + DurationNanos::new(u64::from(duration)),
1731 true,
1732 );
1733
1734 for each_event in clock_ref.match_handlers(time_events) {
1735 drop(clock_ref);
1736 each_event.callback.call(each_event.event);
1737 clock_ref = clock.borrow_mut();
1738 }
1739 }
1740 }
1741
1742 let sent_now = *sent.borrow();
1743 let dropped_now = *dropped.borrow();
1744 assert_eq!(sent_now + dropped_now, throttler.recv_count);
1746 assert_eq!(throttler.sent_count, sent_now);
1747 assert!(throttler.qsize() == 0, "drop mode must never buffer");
1748 }
1749 });
1750 }
1751
1752 #[derive(Clone, Debug)]
1753 enum ThrottlerReserveInput {
1754 SendMessage(u64),
1755 TryReserve(u8),
1756 AdvanceClock(u8),
1757 }
1758
1759 fn throttler_reserve_input_strategy() -> impl Strategy<Value = ThrottlerReserveInput> {
1760 prop_oneof![
1761 2 => prop::bool::ANY.prop_map(|_| ThrottlerReserveInput::SendMessage(42)),
1762 2 => prop::num::u8::ANY.prop_map(|v| ThrottlerReserveInput::TryReserve(v % 6 + 1)),
1763 6 => prop::num::u8::ANY.prop_map(|v| ThrottlerReserveInput::AdvanceClock(v % 5 + 5)),
1764 ]
1765 }
1766
1767 #[rstest]
1768 fn prop_test_try_reserve_interleaved() {
1769 proptest!(|(inputs in prop::collection::vec(throttler_reserve_input_strategy(), 10..=150))| {
1774 let test_throttler = test_throttler_buffered();
1775 let test_clock = test_throttler.clock.clone();
1776 let interval = test_throttler.interval;
1777 let throttler = test_throttler.get_throttler();
1778 let mut attempted = 0usize;
1779 let mut reserved = 0usize;
1780
1781 for input in inputs {
1782 match input {
1783 ThrottlerReserveInput::SendMessage(msg) => {
1784 throttler.send(msg);
1785 attempted += 1;
1786 }
1787 ThrottlerReserveInput::TryReserve(n) => {
1788 if throttler.try_reserve(usize::from(n)) {
1789 reserved += usize::from(n);
1790 }
1791 }
1792 ThrottlerReserveInput::AdvanceClock(duration) => {
1793 let mut clock_ref = test_clock.borrow_mut();
1794 let current_time = clock_ref.get_time_ns();
1795 let time_events = clock_ref.advance_time(
1796 current_time + DurationNanos::new(u64::from(duration)),
1797 true,
1798 );
1799
1800 for each_event in clock_ref.match_handlers(time_events) {
1801 drop(clock_ref);
1802 each_event.callback.call(each_event.event);
1803 clock_ref = test_clock.borrow_mut();
1804 }
1805 }
1806 }
1807
1808 assert_eq!(throttler.sent_count + throttler.qsize(), attempted + reserved);
1809 }
1810
1811 for i in 1..=100u64 {
1812 if throttler.qsize() == 0 {
1813 break;
1814 }
1815 let advance_to = UnixNanos::default() + interval * 100 * i;
1816 let time_events = test_clock
1817 .borrow_mut()
1818 .advance_time(advance_to, true);
1819 let mut clock_ref = test_clock.borrow_mut();
1820 for each_event in clock_ref.match_handlers(time_events) {
1821 drop(clock_ref);
1822 each_event.callback.call(each_event.event);
1823 clock_ref = test_clock.borrow_mut();
1824 }
1825 }
1826 assert_eq!(throttler.qsize(), 0);
1827 });
1828 }
1829
1830 #[rstest]
1831 fn test_throttler_process_id_returns_ustr() {
1832 let actor_id = Ustr::from("test_throttler");
1835 let process = ThrottlerProcess::<String, fn(String)>::new(actor_id);
1836
1837 let handler_id: Ustr = process.id();
1839
1840 assert!(handler_id.contains("test_throttler_process"));
1842 assert!(!handler_id.is_empty());
1843
1844 let _type_check: Ustr = handler_id;
1846 }
1847}