feat: update docs

Author: QEDK

Cargo.toml

@@ -23,7 +23,7 @@ lto = "fat"
 codegen-units = 1
 
 [dev-dependencies]
-criterion = { version = "0.7", features = ["html_reports"] }
+criterion = { version = "0.7" }
 
 [[bench]]
 name = "bench"

README.md

@@ -9,7 +9,7 @@ this to write Rust programs with low-latency message passing.
 Add this to your `Cargo.toml`:
 ```TOML
 [dependencies]
-fq = "0.0.2"
+fq = "0.0.3"
 ```
 
 ## Quickstart
@@ -35,30 +35,35 @@ receiver.join().expect("The receiver thread has panicked");
 ```
 
 ## Examples
-See the [examples](examples) directory for more usage examples.
+See the [examples](examples/README.md) directory for more usage examples.
 
 ## How does it work?
-The ring buffer structure allows for a contigous data structure. The idea is that if we are able to get extreme
+The ring buffer structure allows for a contiguous data structure. The idea is that if we are able to get extreme
 cache locality, we can improve performance by reducing cache misses. This is also the reason why if you use
-smart pointers like `Box<T>`, performance *may* degrade since cache locality gets affected. For very large
+smart pointers like `Box<T>`, performance *may* degrade since cache locality gets degraded. For very large
 `T` types, you are more limited by `memcpy()` performance and less from queue implementations. As such,
-ring buffers can be considered strongly optimized for data of a few word sizes with some non-linear
+ring buffers can be considered strongly optimized for data of a few word sizes with some non-linear performance
 degradation for larger sizes. Additional optimizations are provided for CPUs that support `sse` and `prfchw`
-flags. As and when Rust `std` provides more relevant instructions, they will be added. This is simply a
+instructions. As and when Rust `std` provides more relevant instructions, they will be added. This is simply a
 high-level explanation of some of the techniques employed by this crate, you can read the code to gain a better
 understanding of what's happening under the hood.
 
+## Profiles
+The crate is fully synchronous and runtime-agnostic. We are heavily reliant on `std` for memory management, so
+it's unlikely that we will support `#[no_std]` runtimes anytime soon. You should be using the `release` or
+`maxperf` profiles for optimal performance.
+
 ## Principles
 * This crate will always prioritize message throughput over memory usage.
-* This crate will always support generic types only.
+* This crate will always support generic types.
 * This crate will always provide a wait-free **and** lock-free API.
 * This crate will use unsafe Rust where possible for maximal throughput.
 
 ## Benchmarks
 Benchmarks are strictly difficult due to the nature of the program, it's somewhat simple to do a same-CPU
 bench but performance will still be affected based on the core type and cache contention. Benchmarks are
-provided in the [benchmark](benchmark) directory and can be run with `cargo bench`. Contributions via PRs for
-additional benchmarks are welcome.
+provided in the [benches](benches/bench.rs) directory and can be run with `cargo bench`. Contributions via
+PRs for additional benchmarks are welcome.
 
 ## License
 Licensed under either of:
@@ -67,9 +72,8 @@ Licensed under either of:
 at your option.
 
 ### Contribution
-Unless you explicitly state otherwise, any contribution intentionally submitted
-for inclusion in the work by you, as defined in the LGPL-3.0 license, shall be dual licensed as above, without any
-additional terms or conditions.
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you,
+as defined in the LGPL-3.0 license, shall be dual licensed as above, without any additional terms or conditions.
 
 ## Acknowledgements
-Inspired from previous works like [fastqueue2](https://github.com/andersc/fastqueue2), [rigtorp](https://rigtorp.se/ringbuffer) and [rtrb](https://github.com/mgeier/rtrb).
+Inspired from the previous works of [fastqueue2](https://github.com/andersc/fastqueue2), [rigtorp](https://rigtorp.se/ringbuffer) and [rtrb](https://github.com/mgeier/rtrb).

examples/README.md

@@ -0,0 +1,4 @@
+## Examples
+The directory provides two simple implementations using `fq`:
+1. A basic example demonstrating the usage of the queue with `std` threads.
+2. Another example using `tokio` threads.

src/lib.rs

@@ -210,11 +210,11 @@ impl<T> Producer<T> {
         unsafe {
             let next_index = next_head & self.queue.0.mask.0;
             let next_slot = self.queue.0.buffer.0.add(next_index);
-            #[cfg(target_feature = "sse")]
+            #[cfg(all(target_arch = "x86_64", target_feature = "sse"))]
             {
                 prefetch_read(next_slot as *const u8);
             }
-            #[cfg(target_feature = "prfchw")]
+            #[cfg(any(target_arch = "x86", target_feature = "prfchw"))]
             {
                 prefetch_write(next_slot as *const u8);
             }
@@ -258,6 +258,7 @@ impl<T> Producer<T> {
     /// ```
     /// use fq::FastQueue;
     /// let (mut producer, mut consumer) = FastQueue::new(2);
+    /// assert_eq!(consumer.len(), 0);
     /// producer.push(42).unwrap();
     /// assert_eq!(consumer.len(), 1);
     /// ```
@@ -275,8 +276,9 @@ impl<T> Producer<T> {
     /// ```
     /// use fq::FastQueue;
     /// let (mut producer, mut consumer) = FastQueue::new(2);
+    /// assert!(consumer.is_empty());
     /// producer.push(42).unwrap();
-    /// assert_eq!(consumer.is_empty(), false);
+    /// assert!(!consumer.is_empty());
     /// ```
     #[inline(always)]
     pub fn is_empty(&self) -> bool {
@@ -289,8 +291,10 @@ impl<T> Producer<T> {
     /// ```
     /// use fq::FastQueue;
     /// let (mut producer, mut consumer) = FastQueue::<usize>::new(2);
-    /// producer.push(42).unwrap();
+    /// producer.push(42).unwrap(); // ⚠️ Prefer handling the error over using unwrap()
     /// assert_eq!(producer.is_full(), false);
+    /// producer.push(43).unwrap();
+    /// assert_eq!(producer.is_full(), true);
     /// ```
     #[inline(always)]
     pub fn is_full(&self) -> bool {
@@ -398,6 +402,7 @@ impl<T> Consumer<T> {
     /// ```
     /// use fq::FastQueue;
     /// let (mut producer, mut consumer) = FastQueue::new(2);
+    /// assert_eq!(consumer.len(), 0);
     /// producer.push(42).unwrap();
     /// assert_eq!(consumer.len(), 1);
     /// ```
@@ -415,6 +420,7 @@ impl<T> Consumer<T> {
     /// ```
     /// use fq::FastQueue;
     /// let (mut producer, mut consumer) = FastQueue::new(2);
+    /// assert_eq!(consumer.is_empty(), true);
     /// producer.push(42).unwrap();
     /// assert_eq!(consumer.is_empty(), false);
     /// ```
@@ -424,6 +430,7 @@ impl<T> Consumer<T> {
     }
 }
 
+/// Helper function to prefetch read operation on supported architectures.
 #[cfg(any(
     target_arch = "x86",
     all(target_arch = "x86_64", target_feature = "sse")
@@ -441,6 +448,7 @@ fn prefetch_read(p: *const u8) {
     }
 }
 
+/// Helper function to prefetch a write operation on supported architectures.
 #[cfg(any(
     target_arch = "x86",
     all(target_arch = "x86_64", target_feature = "prfchw")
@@ -479,10 +487,11 @@ impl<T> Iterator for Consumer<T> {
         self.pop()
     }
 
+    /// Provides a size hint (may be stale)
     #[inline(always)]
     fn size_hint(&self) -> (usize, Option<usize>) {
-        let len = self.len();
-        (len, Some(len))
+        // (lower bound, upper bound)
+        (self.len(), None)
     }
 }