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 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318
//! A generic double-buffer. //! //! # Description //! //! A generic double-buffer for anything that implements `Clone`. //! //! # Usage //! //! `DoubleBuffered` implements `Default` so long as the type being double-buffered //! does. //! //! ```rust //! use dubble::DoubleBuffered; //! let mut my_buf = DoubleBuffered::<i32>::default(); //! ``` //! //! Otherwise, you can use a `Fn() -> T` to construct the value in each buffer. //! ```rust //! # use dubble::DoubleBuffered; //! let mut my_buf = DoubleBuffered::construct_with(Vec::<i32>::new); //! ``` //! //! A longer example usage is shown below. //! //! ```rust //! # use dubble::DoubleBuffered; //! // creating a buffer using a closure to initialise the buffers //! let mut my_buf = DoubleBuffered::construct_with(|| //! { //! let mut s = String::new(); //! s.push_str("hello,"); //! s //! }); //! //! // writing to the buffer //! { //! // creates a mutable reference to the write buffer //! let mut wb = my_buf.write(); //! wb.push_str(" world!"); //! } //! //! // NB: DoubleBuffer implements DerefMut, so we could also use the //! // `push_str` method of `String` directly, like so. //! my_buf.push_str(" Hello again!"); //! //! // reading from the buffer //! // note: the read half of the buffer should not have updated yet //! assert!(my_buf.read() == "hello,"); //! //! // updating the buffer //! // other half of the buffer has been updated //! // NB: DoubleBuffer implements Deref, so we could use the dereference operator //! // here as well //! my_buf.update(); //! assert!(*my_buf == "hello, world! Hello again!"); //! ``` //! //! # Notes //! //! ## `Default` //! //! `DoubleBuffered` implements `Default` so long as the type being buffered //! implements it. For example, if you needed a double-buffered `i32`: //! //! ``` //! use dubble::DoubleBuffered; //! let my_buf: DoubleBuffered<i32> = DoubleBuffered::default(); //! ``` //! //! ## `Deref` and `DerefMut` //! //! An important note on the `impl`s for each of these is that `Deref` will //! dereference to the *read* buffer while `DerefMut` will dereference to the //! *write* buffer. So, if you did `*my_buf = 3` followed by `assert(*my_buf == 3)`, //! you'd find that the assertion would fail. //! //! ```rust,should_panic //! # use dubble::DoubleBuffered; //! # let mut my_buf: DoubleBuffered<i32> = DoubleBuffered::default(); //! *my_buf = 3; //! assert!(*my_buf == 3); //! ``` //! //! In other words, `Deref` behaves as if you had called `my_buf.read()`, and //! `DerefMut` behaves as if you had called `my_buf.write()`. //! use std::ops:: { Deref, DerefMut, Index, IndexMut }; /// Represents something that is double-buffered. The type being buffered must /// be `Clone`, so that the read buffer can be updated with the contents of the /// write buffer during the update. /// /// See the module-level documentation for more information. pub struct DoubleBuffered<T: Clone> { rbuf: T, wbuf: T, } impl<T: Clone> DoubleBuffered<T> { /// Initialises the double-buffer with the value. Both buffers are initialised /// with the same value. pub fn new(value: T) -> Self { Self { rbuf: value.clone(), wbuf: value.clone(), } } /// Uses `constructor` to construct each buffer. It's handy to pass things /// like `Vec::new` into here. `DoubleBuffered` also implements default /// if the wrapped type does, so you could also do /// `DoubleBuffered<Vec<T>>::default()` pub fn construct_with<F: Fn() -> T>(constructor: F) -> Self { Self { rbuf: constructor(), wbuf: constructor(), } } /// Returns an immutable reference to the read buffer. pub fn read(&self) -> &T { &self.rbuf } /// Returns a mutable reference to the write buffer. /// Note that changes made through this reference will not be reflected /// until after `update` is called. /// /// This might seem a little weird; "why not just go `my_buf.write(stuff)`"?. /// The reason is so that you can update the elements of a collection without /// having to build a clone of the collection. For example: /// /// ```rust /// # use dubble::DoubleBuffered; /// let mut my_buf: DoubleBuffered<Vec<i32>> = DoubleBuffered::default(); /// let mut wb = my_buf.write(); /// wb.push(4); /// ``` /// /// Compared to the other potential form: /// /// ```rust,not_run /// # use dubble::DoubleBuffered; /// # let mut my_buf: DoubleBuffered<Vec<i32>> = DoubleBuffered::default(); /// let mut wb = my_buf.read().clone(); /// wb.push(5); /// // my_buf.write(wb); /// ``` /// /// Notice that you have to create a copy and modify it. pub fn write(&mut self) -> &mut T { &mut self.wbuf } /// Copies the write buffer into the read buffer. pub fn update(&mut self) { self.rbuf = self.wbuf.clone(); } /// Writes the value to the write buffer, and then immediately updates the /// read buffer. pub fn upsert(&mut self, value: T) { *self.write() = value; self.update(); } /// Returns the read buffer. This does not update the read buffer with the /// contents of the write buffer beforehand. You could think of this like /// "quit without saving" in a word processor. pub fn unbuffer_read(self) -> T { self.rbuf } /// Returns the write buffer. pub fn unbuffer_write(self) -> T { self.wbuf } } impl<T: Clone> Deref for DoubleBuffered<T> { type Target = T; fn deref(&self) -> &T { self.read() } } impl<T: Clone> DerefMut for DoubleBuffered<T> { fn deref_mut(&mut self) -> &mut T { self.write() } } impl<T: Default + Clone> Default for DoubleBuffered<T> { /// Use the default constructor for the type. fn default() -> Self { Self::construct_with(T::default) } } impl<I, T: Index<I> + Clone> Index<I> for DoubleBuffered<T> { type Output = <T as Index<I>>::Output; fn index(&self, index: I) -> &Self::Output { &self.rbuf[index] } } impl<I, T: IndexMut<I> + Clone> IndexMut<I> for DoubleBuffered<T> { fn index_mut(&mut self, index: I) -> &mut Self::Output { &mut self.wbuf[index] } } #[cfg(test)] mod tests { use super::*; #[test] fn basic_int() { // create a db int let mut db = DoubleBuffered::<i32>::default(); *db.write() = 3; // read buffer should not update until told to do so. assert!(*db.read() == 0); db.update(); assert!(*db.read() == 3); // check the same thing again *db.write() = 4; assert!(*db.read() == 3); db.update(); assert!(*db.read() == 4); } #[test] fn basic_string() { let mut db = DoubleBuffered::construct_with(String::new); assert!(*db.read() == String::new()); *db.write() = "hello, world".to_string(); db.update(); assert!(*db.read() == String::from("hello, world")); } #[test] fn basic_int_using_deref() { // the same test as basic_int, but making use of the Deref traits // create a db int let mut db = DoubleBuffered::<i32>::default(); *db = 3; // read buffer should not update until told to do so. assert!(*db == 0); db.update(); assert!(*db == 3); // check the same thing again *db = 4; assert!(*db == 3); db.update(); assert!(*db == 4); } #[test] fn vec_i32() { let mut db = DoubleBuffered::<Vec<i32>>::default(); // using deref and index db.push(0); db.update(); assert!(db[0] == 0); // read view should not change db[0] = 1; assert!(db[0] == 0); // should now be updated db.update(); assert!(db[0] == 1); } }