fix tests

Author: jdidion

CHANGELOG.md

@@ -15,6 +15,7 @@ The general theme of this release is performance improvement by eliminating thre
     * `BeeBuilder` and `FullBuilder` are intermediate types that generally should not be instantiated directly.
   * `beekeeper::bee::Queen::create` now takes `&self` rather than `&mut self`. There is a new type, `beekeeper::bee::QueenMut`, with a `create(&mut self)` method, and needs to be wrapped in a `beekeeper::bee::QueenCell` to implement the `Queen` trait. This enables the `Hive` to create new workers without locking in the case of a `Queen` that does not need mutable state.
   * `beekeeper::bee::Context` now takes a generic parameter that must be input type of the `Worker`.
+  * `beekeeper::hive::Hive::try_into_husk` now has an `urgent` parameter to indicate whether queued tasks should be abandoned when shutting down the hive (`true`) or if they should be allowed to finish processing (`false`).
 * Features
   * Added the `TaskQueues` trait, which enables `Hive` to be specialized for different implementations of global (i.e., sending tasks from the `Hive` to worker threads) and local (i.e., worker thread-specific) queues.
     * `ChannelTaskQueues` implements the existing behavior, using a channel for sending tasks.

Cargo.toml

@@ -39,7 +39,7 @@ name = "perf"
 harness = false
 
 [features]
-default = ["affinity", "batching", "retry"]
+default = ["batching", "retry"]
 affinity = ["dep:core_affinity"]
 batching = []
 retry = []

README.md

@@ -108,7 +108,8 @@ There are multiple methods in each group that differ by how the task results (ca
 * The methods with the `_unordered` suffix instead return an unordered iterator, which may be
   more performant than the ordered iterator
 * The methods with the `_send` suffix accept a channel `Sender` and send the `Outcome`s to that
-  channel as they are completed
+  channel as they are completed.
+    * Note that, for these methods, the `tx` parameter is of type `Borrow<Sender<_>>`, which allows you to pass in either a value or a reference. Passing a value causes the `Sender` to be dropped after the call, while passing a reference allows you to use the same `Sender` for multiple `_send` calls. Note that in the later case, you need to explicitly drop the sender (e.g., `drop(tx)`), pass it by value to the last `_send` call, or be careful about how you obtain outcomes from the `Receiver` as methods such as `recv` and `iter` will block until the `Sender` is dropped. You should *not* pass clones of the `Sender` to `_send` methods as this results in slightly worse performance and still has the requirement that you manually drop the original `Sender` value.
 * The methods with the `_store` suffix store the `Outcome`s in the `Hive`; these may be
   retrieved later using the [`Hive::take_stored()`](https://docs.rs/beekeeper/latest/beekeeper/hive/struct.Hive.html#method.take_stored) method, using
   one of the `remove*` methods (which requires

src/atomic.rs

@@ -142,6 +142,7 @@ macro_rules! atomic_int {
 }
 
 atomic!(bool);
+atomic_int!(u8);
 atomic_int!(u32);
 atomic_int!(u64);
 atomic_int!(usize);
@@ -458,6 +459,7 @@ mod tests {
         };
     }
 
+    test_numeric_type!(AtomicU8);
     test_numeric_type!(AtomicU32);
     test_numeric_type!(AtomicU64);
     test_numeric_type!(AtomicUsize);

src/bee/queen.rs

@@ -78,7 +78,7 @@ impl<Q: QueenMut> From<Q> for QueenCell<Q> {
 ///     type Output = u8;
 ///     type Error = ();
 ///
-///     fn apply(&mut self, input: u8, _: &Context) -> WorkerResult<Self> {
+///     fn apply(&mut self, input: u8, _: &Context<Self::Input>) -> WorkerResult<Self> {
 ///         Ok(self.0.saturating_add(input))
 ///     }
 /// }
@@ -88,7 +88,7 @@ impl<Q: QueenMut> From<Q> for QueenCell<Q> {
 /// impl Queen for MyQueen {
 ///     type Kind = MyWorker;
 ///
-///     fn create(&mut self) -> Self::Kind {
+///     fn create(&self) -> Self::Kind {
 ///         MyWorker::default()
 ///     }
 /// }

src/hive/builder/mod.rs

@@ -1,5 +1,4 @@
-//! There are a few different builder types. All builders implement the `BuilderConfig` trait,
-//! which provides methods to set configuration parameters.
+//! There are a few different builder types.
 //!
 //! * Open: has no type parameters; can only set config parameters. Has methods to create
 //!   typed builders.
@@ -13,6 +12,33 @@
 //!   Bee  /
 //!    |  /
 //!   Full
+//!
+//! All builders implement the `BuilderConfig` trait, which provides methods to set configuration
+//! parameters. The configuration options available:
+//! * [`Builder::num_threads`]: number of worker threads that will be spawned by the built `Hive`.
+//!     * [`Builder::with_default_num_threads`] will set `num_threads` to the global default value.
+//!     * [`Builder::with_thread_per_core`] will set `num_threads` to the number of available CPU
+//!       cores.
+//! * [`Builder::thread_name`]: thread name for each of the threads spawned by the built `Hive`. By
+//!   default, threads are unnamed.
+//! * [`Builder::thread_stack_size`]: stack size (in bytes) for each of the threads spawned by the
+//!   built `Hive`. See the
+//!   [`std::thread`](https://doc.rust-lang.org/stable/std/thread/index.html#stack-size)
+//!   documentation for details on the default stack size.
+//!
+//! The following configuration options are available when the `retry` feature is enabled:
+//! * [`Builder::max_retries`]: maximum number of times a `Worker` will retry an
+//!   [`ApplyError::Retryable`](crate::bee::ApplyError#Retryable) before giving up.
+//! * [`Builder::retry_factor`]: [`Duration`](std::time::Duration) factor for exponential backoff
+//!   when retrying an `ApplyError::Retryable` error.
+//! * [`Builder::with_default_retries`] sets the retry options to the global defaults, while
+//!   [`Builder::with_no_retries`] disabled retrying.
+//!
+//! The following configuration options are available when the `affinity` feature is enabled:
+//! * [`Builder::core_affinity`]: List of CPU core indices to which the threads should be pinned.
+//!     * [`Builder::with_default_core_affinity`] will set the list to all CPU core indices, though
+//!       only the first `num_threads` indices will be used.
+//!
 mod bee;
 mod channel;
 mod full;

src/hive/builder/open.rs

@@ -4,51 +4,33 @@ use crate::hive::Config;
 
 /// A builder for a [`Hive`](crate::hive::Hive).
 ///
-/// Calling [`Builder::new()`] creates an unconfigured `Builder`, while calling
-/// [`Builder::default()`] creates a `Builder` with fields preset to the global default values.
+/// Calling [`OpenBuilder::empty()`] creates an unconfigured `Builder`, while calling
+/// [`OpenBuilder::default()`] creates a `Builder` with fields preset to the global default values.
 /// Global defaults can be changed using the
 /// [`beekeeper::hive::set_*_default`](crate::hive#functions) functions.
 ///
-/// The configuration options available:
-/// * [`Builder::num_threads`]: number of worker threads that will be spawned by the built `Hive`.
-///     * [`Builder::with_default_num_threads`] will set `num_threads` to the global default value.
-///     * [`Builder::with_thread_per_core`] will set `num_threads` to the number of available CPU
-///       cores.
-/// * [`Builder::thread_name`]: thread name for each of the threads spawned by the built `Hive`. By
-///   default, threads are unnamed.
-/// * [`Builder::thread_stack_size`]: stack size (in bytes) for each of the threads spawned by the
-///   built `Hive`. See the
-///   [`std::thread`](https://doc.rust-lang.org/stable/std/thread/index.html#stack-size)
-///   documentation for details on the default stack size.
+/// See the [module documentation](crate::hive::builder) for details on the available configuration
+/// options.
 ///
-/// The following configuration options are available when the `retry` feature is enabled:
-/// * [`Builder::max_retries`]: maximum number of times a `Worker` will retry an
-///   [`ApplyError::Retryable`](crate::bee::ApplyError#Retryable) before giving up.
-/// * [`Builder::retry_factor`]: [`Duration`](std::time::Duration) factor for exponential backoff
-///   when retrying an `ApplyError::Retryable` error.
-/// * [`Builder::with_default_retries`] sets the retry options to the global defaults, while
-///   [`Builder::with_no_retries`] disabled retrying.
+/// This builder needs to be specialized to both the `Queen` and `TaskQueues` types. You can do
+/// this in either order.
 ///
-/// The following configuration options are available when the `affinity` feature is enabled:
-/// * [`Builder::core_affinity`]: List of CPU core indices to which the threads should be pinned.
-///     * [`Builder::with_default_core_affinity`] will set the list to all CPU core indices, though
-///       only the first `num_threads` indices will be used.
-///
-/// To create the [`Hive`], call one of the `build*` methods:
-/// * [`Builder::build`] requires a [`Queen`] instance.
-/// * [`Builder::build_default`] requires a [`Queen`] type that implements [`Default`].
-/// * [`Builder::build_with`] requires a [`Worker`] instance that implements [`Clone`].
-/// * [`Builder::build_with_default`] requires a [`Worker`] type that implements [`Default`].
+/// * Calling one of the `with_queen*` methods returns a `BeeBuilder` specialized to a `Queen`.
+/// * Calling `with_worker` or `with_worker_default` returns a `BeeBuilder` specialized to a
+///   `CloneQueen` or `DefaultQueen` (respectively) for a specific `Worker` type.
+/// * Calling `with_channel_queues` or `with_workstealing_queues` returns a `ChannelBuilder` or
+///   `WorkstealingBuilder` specialized to a `TaskQueues` type.
 ///
 /// # Examples
 ///
 /// Build a [`Hive`] that uses a maximum of eight threads simultaneously and each thread has
 /// a 8 MB stack size:
 ///
 /// ```
+/// # use beekeeper::hive::{Builder, OpenBuilder};
 /// type MyWorker = beekeeper::bee::stock::ThunkWorker<()>;
 ///
-/// let hive = beekeeper::hive::Builder::empty()
+/// let hive = OpenBuilder::empty()
 ///     .num_threads(8)
 ///     .thread_stack_size(8_000_000)
 ///     .with_worker_default::<MyWorker>()
@@ -70,8 +52,8 @@ impl OpenBuilder {
     /// # Examples
     ///
     /// ```
-    /// # use beekeeper::hive::{Builder, Hive};
-    /// # use beekeeper::bee::{Context, Queen, Worker, WorkerResult};
+    /// # use beekeeper::hive::{Builder, ChannelBuilder, Hive};
+    /// # use beekeeper::bee::{Context, QueenMut, Worker, WorkerResult};
     ///
     /// #[derive(Debug)]
     /// struct CounterWorker {
@@ -95,7 +77,7 @@ impl OpenBuilder {
     ///     type Output = String;
     ///     type Error = ();
     ///
-    ///     fn apply(&mut self, input: Self::Input, _: &Context) -> WorkerResult<Self> {
+    ///     fn apply(&mut self, input: Self::Input, _: &Context<usize>) -> WorkerResult<Self> {
     ///         self.input_count += 1;
     ///         self.input_sum += input;
     ///         let s = format!(
@@ -111,7 +93,7 @@ impl OpenBuilder {
     ///     num_workers: usize
     /// }
     ///
-    /// impl Queen for CounterQueen {
+    /// impl QueenMut for CounterQueen {
     ///     type Kind = CounterWorker;
     ///
     ///     fn create(&mut self) -> Self::Kind {
@@ -121,16 +103,17 @@ impl OpenBuilder {
     /// }
     ///
     /// # fn main() {
-    /// let hive = Builder::new()
+    /// let hive = ChannelBuilder::empty()
     ///     .num_threads(8)
     ///     .thread_stack_size(4_000_000)
-    ///     .build(CounterQueen::default());
+    ///     .with_queen_mut_default::<CounterQueen>()
+    ///     .build();
     ///
     /// for i in 0..100 {
     ///     hive.apply_store(i);
     /// }
-    /// let husk = hive.try_into_husk().unwrap();
-    /// assert_eq!(husk.queen().num_workers, 8);
+    /// let husk = hive.try_into_husk(false).unwrap();
+    /// assert_eq!(husk.queen().get().num_workers, 8);
     /// # }
     /// ```
     pub fn with_queen<Q: Queen, I: Into<Q>>(self, queen: I) -> BeeBuilder<Q> {
@@ -155,7 +138,7 @@ impl OpenBuilder {
     /// # Examples
     ///
     /// ```
-    /// # use beekeeper::hive::{Builder, OutcomeIteratorExt};
+    /// # use beekeeper::hive::{Builder, ChannelBuilder, OutcomeIteratorExt};
     /// # use beekeeper::bee::{Context, Worker, WorkerResult};
     ///
     /// #[derive(Debug, Clone)]
@@ -173,24 +156,25 @@ impl OpenBuilder {
     ///     type Output = isize;
     ///     type Error = ();
     ///
-    ///     fn apply(&mut self, input: Self::Input, _: &Context) -> WorkerResult<Self> {
+    ///     fn apply(&mut self, input: Self::Input, _: &Context<Self::Input>) -> WorkerResult<Self> {
     ///         let (operand, operator) = input;
     ///         let value = match operator % 4 {
-    ///             0 => operand + self.config(Token),
-    ///             1 => operand - self.config(Token),
-    ///             2 => operand * self.config(Token),
-    ///             3 => operand / self.config(Token),
+    ///             0 => operand + self.0,
+    ///             1 => operand - self.0,
+    ///             2 => operand * self.0,
+    ///             3 => operand / self.0,
     ///             _ => unreachable!(),
     ///         };
     ///         Ok(value)
     ///     }
     /// }
     ///
     /// # fn main() {
-    /// let hive = Builder::new()
+    /// let hive = ChannelBuilder::empty()
     ///     .num_threads(8)
     ///     .thread_stack_size(4_000_000)
-    ///     .build_with(MathWorker(5isize));
+    ///     .with_worker(MathWorker(5isize))
+    ///     .build();
     ///
     /// let sum: isize = hive
     ///     .map((0..100).zip((0..4).cycle()))
@@ -212,7 +196,7 @@ impl OpenBuilder {
     /// # Examples
     ///
     /// ```
-    /// # use beekeeper::hive::{Builder, OutcomeIteratorExt};
+    /// # use beekeeper::hive::{Builder, ChannelBuilder, OutcomeIteratorExt};
     /// # use beekeeper::bee::{Context, Worker,  WorkerResult};
     /// # use std::num::NonZeroIsize;
     ///
@@ -224,24 +208,25 @@ impl OpenBuilder {
     ///     type Output = isize;
     ///     type Error = ();
     ///
-    ///     fn apply(&mut self, input: Self::Input, _: &Context) -> WorkerResult<Self> {
+    ///     fn apply(&mut self, input: Self::Input, _: &Context<Self::Input>) -> WorkerResult<Self> {
     ///         let (operand, operator) = input;
     ///         let result = match operator % 4 {
-    ///             0 => self.config(Token) + operand.get(),
-    ///             1 => self.config(Token) - operand.get(),
-    ///             2 => self.config(Token) * operand.get(),
-    ///             3 => self.config(Token) / operand.get(),
+    ///             0 => self.0 + operand.get(),
+    ///             1 => self.0 - operand.get(),
+    ///             2 => self.0 * operand.get(),
+    ///             3 => self.0 / operand.get(),
     ///             _ => unreachable!(),
     ///         };
     ///         Ok(result)
     ///     }
     /// }
     ///
     /// # fn main() {
-    /// let hive = Builder::new()
+    /// let hive = ChannelBuilder::empty()
     ///     .num_threads(8)
     ///     .thread_stack_size(4_000_000)
-    ///     .build_with_default::<MathWorker>();
+    ///     .with_worker_default::<MathWorker>()
+    ///     .build();
     ///
     /// let sum: isize = hive
     ///     .map((1..=100).map(|i| NonZeroIsize::new(i).unwrap()).zip((0..4).cycle()))