diff --git a/CHANGELOG.md b/CHANGELOG.md index a2e4ee0..a37c9d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -_No unreleased changes in the pipeline at the moment_ +### Changed + +- Turn `Input::input_buffer()` and `Output::output_buffer()` into read-only + accessors and deprecate `Output::peek_output_buffer()`, moving forward with + the plan set in issue #30 to eventually migrate towards an API naming + convention that matches `std` and other Rust libraries. diff --git a/Cargo.lock b/Cargo.lock index 8f62ec2..6e08c2b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -343,7 +343,7 @@ dependencies = [ [[package]] name = "triple_buffer" -version = "8.1.1" +version = "9.0.0" dependencies = [ "criterion", "crossbeam-utils", diff --git a/Cargo.toml b/Cargo.toml index 72bc224..4c21cdd 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,7 +11,7 @@ name = "triple_buffer" # - Roll an annotated git tag # - Add a github release # -version = "8.1.1" +version = "9.0.0" authors = ["Hadrien G. "] description = "An implementation of triple buffering, useful for sharing frequently updated data between threads" documentation = "https://docs.rs/triple_buffer/" diff --git a/README.md b/README.md index 5a08e22..85f657d 100644 --- a/README.md +++ b/README.md @@ -74,11 +74,11 @@ buf_input.publish(); // Manually fetch the buffer update from the consumer interface buf_output.update(); -// Acquire read-only reference to the output buffer -let output = buf_output.peek_output_buffer(); +// Acquire a read-only reference to the output buffer +let output = buf_output.output_buffer(); assert_eq!(*output, "Hello, "); -// Or acquire mutable reference if necessary +// Or acquire a mutable reference if necessary let output_mut = buf_output.output_buffer_mut(); // Post-process the output value before use diff --git a/benches/benchmarks.rs b/benches/benchmarks.rs index b77e010..5623e02 100644 --- a/benches/benchmarks.rs +++ b/benches/benchmarks.rs @@ -6,7 +6,7 @@ pub fn benchmark(c: &mut Criterion) { { let mut uncontended = c.benchmark_group("uncontended"); - uncontended.bench_function("read output", |b| b.iter(|| *output.peek_output_buffer())); + uncontended.bench_function("read output", |b| b.iter(|| *output.output_buffer())); uncontended.bench_function("clean update", |b| { b.iter(|| { output.update(); @@ -79,7 +79,7 @@ pub fn benchmark(c: &mut Criterion) { || input.write(black_box(0)), || { write_contended - .bench_function("read output", |b| b.iter(|| *output.peek_output_buffer())); + .bench_function("read output", |b| b.iter(|| *output.output_buffer())); write_contended.bench_function("update", |b| { b.iter(|| { output.update(); diff --git a/src/lib.rs b/src/lib.rs index e74b897..8c89891 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -62,11 +62,11 @@ //! // Manually fetch the buffer update from the consumer interface //! buf_output.update(); //! -//! // Acquire read-only reference to the output buffer -//! let output = buf_output.peek_output_buffer(); +//! // Acquire a read-only reference to the output buffer +//! let output = buf_output.output_buffer(); //! assert_eq!(*output, "Hello, "); //! -//! // Or acquire mutable reference if necessary +//! // Or acquire a mutable reference if necessary //! let output_mut = buf_output.output_buffer_mut(); //! //! // Post-process the output value before use @@ -266,33 +266,17 @@ impl Input { /// Query the current value of the input buffer /// - /// This is simply a read-only version of + /// This is a read-only version of /// [`input_buffer_mut()`](Input::input_buffer_mut). Please read the /// documentation of that method for more information on the precautions /// that need to be taken when accessing the input buffer in place. - fn peek_input_buffer(&self) -> &T { - // Access the input buffer directly + pub fn input_buffer(&self) -> &T { + // This is safe because the synchronization protocol ensures that we + // have exclusive access to this buffer. let input_ptr = self.shared.buffers[self.input_idx as usize].get(); unsafe { &*input_ptr } } - /// Access the input buffer directly - /// - /// This is, for now, a deprecated alias to - /// [`input_buffer_mut()`](Input::input_buffer_mut). Please use this method - /// instead. - /// - /// In a future major release of this crate, `input_buffer()` will - /// undergo a breaking change to instead provide read-only access. - /// - /// The aim of this process is to eventually migrate towards the standard - /// `accessor()`/`accessor_mut()` method naming convention that most Rust - /// libraries follow. - #[deprecated = "Please use input_buffer_mut() instead"] - pub fn input_buffer(&mut self) -> &mut T { - self.input_buffer_mut() - } - /// Access the input buffer directly /// /// This advanced interface allows you to update the input buffer in place, @@ -398,7 +382,7 @@ impl Deref for InputPublishGuard<'_, T> { type Target = T; fn deref(&self) -> &T { - self.reference.peek_input_buffer() + self.reference.input_buffer() } } @@ -467,7 +451,18 @@ impl Output { /// Query the current value of the output buffer /// - /// This is simply a read-only version of + /// This is a deprecated compatibility alias to + /// [`output_buffer()`](Self::output_buffer). Please use that method + /// instead, as `peek_output_buffer()` is scheduled for removal in the next + /// major release of `triple-buffer`. + #[deprecated = "Please use output_buffer() instead"] + pub fn peek_output_buffer(&self) -> &T { + self.output_buffer() + } + + /// Query the current value of the output buffer + /// + /// This is a read-only version of /// [`output_buffer_mut()`](Output::output_buffer_mut). Please read the /// documentation of that method for more information on the precautions /// that need to be taken when accessing the output buffer in place. @@ -475,36 +470,13 @@ impl Output { /// In particular, remember that this method does not update the output /// buffer automatically. You need to call [`update()`](Output::update) in /// order to fetch buffer updates from the producer. - pub fn peek_output_buffer(&self) -> &T { - // Access the output buffer directly + pub fn output_buffer(&self) -> &T { + // This is safe because the synchronization protocol ensures that we + // have exclusive access to this buffer. let output_ptr = self.shared.buffers[self.output_idx as usize].get(); unsafe { &*output_ptr } } - /// Access the input buffer directly - /// - /// This is, for now, a deprecated alias to [`output_buffer_mut()`]. Please - /// use this method instead. - /// - /// In a future major release of this crate, `output_buffer()` will undergo - /// a breaking change to instead provide read-only access, like - /// [`peek_output_buffer()`] currently does. At that point, - /// [`peek_output_buffer()`] will be deprecated. - /// - /// Finally, in a later major release [`peek_output_buffer()`] will be - /// removed. - /// - /// The aim of this process is to eventually migrate towards the standard - /// `accessor()`/`accessor_mut()` method naming convention that most Rust - /// libraries follow. - /// - /// [`output_buffer_mut()`]: Output::output_buffer_mut - /// [`peek_output_buffer()`]: Output::peek_output_buffer - #[deprecated = "Please use output_buffer_mut() instead"] - pub fn output_buffer(&mut self) -> &mut T { - self.output_buffer_mut() - } - /// Access the output buffer directly /// /// This advanced interface allows you to modify the contents of the output @@ -1169,7 +1141,7 @@ mod tests { move || { let mut last_value = 0usize; while last_value < TEST_WRITE_COUNT { - match buf_output.peek_output_buffer().get() { + match buf_output.output_buffer().get() { Racey::Consistent(new_value) => { assert!((new_value >= last_value) && (new_value <= TEST_WRITE_COUNT)); last_value = new_value; @@ -1240,7 +1212,7 @@ mod tests { // Check that the output_buffer query works in the initial state assert_eq!( - as_ptr(&buf.output.peek_output_buffer()), + as_ptr(&buf.output.output_buffer()), buf.output.shared.buffers[buf.output.output_idx as usize].get() ); assert_eq!(*buf, initial_buf);