limq 0.4.0

Queue with a controller for monitoring queue elements
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

use std::{cmp, collections::VecDeque};

use super::{BufQStats, CheckErr, Controller};


/// A [`Controller`] for queue of `Vec<u8>` that can optionally limit the
/// queue length as well as total buffer size.
pub struct BufLim {
  cur_len: usize,
  max_len: Option<usize>,
  len_hwm: usize,
  cur_size: usize,
  max_size: Option<usize>,
  size_hwm: usize
}

impl BufLim {
  /// Create a new object for limiting a buffers queue to a configured length
  /// and size.
  ///
  /// # Panics
  /// `max_len` must not be `0`.  `max_size` must not be `0`.
  #[must_use]
  pub fn new(max_len: Option<usize>, max_size: Option<usize>) -> Self {
    assert!(!matches!(max_len, Some(0)), "zero-length limit");
    assert!(!matches!(max_size, Some(0)), "zero-size limit");
    Self {
      cur_len: 0,
      max_len,
      len_hwm: 0,
      cur_size: 0,
      max_size,
      size_hwm: 0
    }
  }

  /// Return the current total size of all buffers in queue.
  #[must_use]
  pub const fn size(&self) -> usize {
    self.cur_size
  }

  /// Return the current maximum queue length configuration.
  #[must_use]
  pub const fn get_max_len(&self) -> Option<usize> {
    self.max_len
  }

  /// Return the current maximum total buffer size configuration.
  #[must_use]
  pub const fn get_max_size(&self) -> Option<usize> {
    self.max_size
  }

  /// # Panics
  /// `max_len` must not be `0`.
  pub fn set_max_len(&mut self, max_len: Option<usize>) {
    assert!(!matches!(max_len, Some(0)), "zero-length limit");
    self.max_len = max_len;
  }

  /// # Panics
  /// `max_size` must not be `0`.
  pub fn set_max_size(&mut self, max_size: Option<usize>) {
    assert!(!matches!(max_size, Some(0)), "zero-size limit");
    self.max_size = max_size;
  }

  /// Return queue statistics.
  #[must_use]
  pub const fn stats(&self) -> BufQStats {
    BufQStats {
      len: self.cur_len,
      len_hwm: self.len_hwm,
      size: self.cur_size,
      size_hwm: self.size_hwm
    }
  }

  /// Set length and size high-water marks to the current length/size values.
  pub const fn reset_hwm(&mut self) {
    self.len_hwm = self.cur_len;
    self.size_hwm = self.cur_size;
  }

  /// Set length and size high-water marks to `0`.
  pub const fn clear_hwm(&mut self) {
    self.len_hwm = 0;
    self.size_hwm = 0;
  }
}

impl Controller for BufLim {
  type Item = Vec<u8>;

  fn size_hint(&self) -> Option<usize> {
    self.max_len
  }

  fn is_full(&self, q: &VecDeque<Self::Item>) -> bool {
    self.max_len.is_some_and(|max_len| q.len() >= max_len)
      || self
        .max_size
        .is_some_and(|max_size| self.cur_size >= max_size)
  }

  fn is_overflow(&self, q: &VecDeque<Self::Item>) -> bool {
    self.max_len.is_some_and(|max_len| q.len() > max_len)
      || self
        .max_size
        .is_some_and(|max_size| self.cur_size > max_size)
  }

  fn check(
    &self,
    q: &VecDeque<Self::Item>,
    n: &Self::Item
  ) -> Result<(), CheckErr> {
    if let Some(max_len) = self.max_len {
      if q.len() + 1 > max_len {
        return Err(CheckErr::WontFit);
      }
    }
    if let Some(max_size) = self.max_size {
      if n.len() > max_size {
        return Err(CheckErr::CantFit);
      }
      if self.cur_size + n.len() > max_size {
        return Err(CheckErr::WontFit);
      }
    }
    Ok(())
  }

  fn reg(&mut self, q: &VecDeque<Self::Item>, n: &Self::Item) {
    self.cur_len += 1;

    self.len_hwm = cmp::max(self.len_hwm, q.len());

    // At this point it has been determined that the new buffer will not
    // overflow the queue.  Register the buffer size and return true to tell
    // caller to add the buffer.
    self.cur_size += n.len();

    self.size_hwm = cmp::max(self.size_hwm, self.cur_size);
  }

  fn dereg(&mut self, n: &Self::Item) {
    self.cur_len -= 1;
    self.cur_size -= n.len();
  }
}

// vim: set ft=rust et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :