|
3 | 3 | //! A [`Hive`](crate::hive::Hive) is populated by bees: |
4 | 4 | //! * The [`Worker`]s process the tasks submitted to the `Hive`. |
5 | 5 | //! * The [`Queen`] creates a new `Worker` for each thread in the `Hive`. |
| 6 | +//! * [`QueenMut`] can be used to implement a stateful queen - it must be wrapped in a |
| 7 | +//! [`QueenCell`] to make it thread-safe. |
| 8 | +//! |
| 9 | +//! It is easiest to use the [`prelude`] when implementing your bees: |
| 10 | +//! |
| 11 | +//! ``` |
| 12 | +//! use beekeeper::bee::prelude::*; |
| 13 | +//! ``` |
6 | 14 | //! |
7 | 15 | //! # Worker |
8 | 16 | //! |
|
18 | 26 | //! |
19 | 27 | //! The `Worker` trait has a single method, [`apply`](crate::bee::Worker::apply), which |
20 | 28 | //! takes an input of type `Input` and a [`Context`] and returns a `Result` containing an either an |
21 | | -//! `Output` or an [`ApplyError`]. |
| 29 | +//! `Output` or an [`ApplyError`]. Note that `Worker::apply()` takes a `&mut self` parameter, |
| 30 | +//! meaning that it can modify its own state. |
| 31 | +//! |
| 32 | +//! If a fatal error occurs during processing of the task, the worker should return |
| 33 | +//! [`ApplyError::Fatal`]. |
| 34 | +//! |
| 35 | +//! If the task instead fails due to a transient error, the worker should return |
| 36 | +//! [`ApplyError::Retryable`]. If the `retry` feature is enabled, then a task that fails with a |
| 37 | +//! `ApplyError::Retryable` error will be retried, otherwise the error is converted to `Fatal`. |
22 | 38 | //! |
23 | 39 | //! The `Context` contains information about the task, including: |
24 | 40 | //! * The task ID. Each task submitted to a `Hive` is assigned an ID that is unique within |
|
29 | 45 | //! periodically check the cancellation flag by calling |
30 | 46 | //! [`Context::is_cancelled()`](crate::bee::context::Context::is_cancelled). If the cancellation |
31 | 47 | //! flag is set, the worker may terminate early by returning [`ApplyError::Cancelled`]. |
32 | | -//! * If the `retry` feature is enabled, the `Context` also contains the retry |
33 | | -//! [`attempt`](crate::bee::context::Context::attempt), which starts at `0` the first time the task |
34 | | -//! is attempted and increments by `1` for each subsequent retry attempt. |
35 | | -//! |
36 | | -//! If a fatal error occurs during processing of the task, the worker should return |
37 | | -//! [`ApplyError::Fatal`]. |
| 48 | +//! * The retry [`attempt`](crate::bee::context::Context::attempt), which starts at `0` the first |
| 49 | +//! time the task is attempted. If the `retry` feature is enabled and the task fails with |
| 50 | +//! [`ApplyError::Retryable], this value increments by `1` for each subsequent retry attempt. |
38 | 51 | //! |
39 | | -//! If the task instead fails due to a transient error, the worker should return |
40 | | -//! [`ApplyError::Retryable`]. If the `retry` feature is enabled, then a task that fails with a |
41 | | -//! `ApplyError::Retryable` error will be retried, otherwise the error is converted to `Fatal`. |
| 52 | +//! The `Context` also provides the ability to submit new tasks to the `Hive` using the |
| 53 | +//! [`submit`](crate::bee::Context::submit) method. The IDs of submitted subtasks are stored in the |
| 54 | +//! `Context` and are returned in a field of the [`Outcome`](crate::hive::Outcome) that results |
| 55 | +//! from the parent task. |
42 | 56 | //! |
43 | 57 | //! A `Worker` should not panic. However, if it must execute code that may panic, it can do so |
44 | 58 | //! within a closure passed to [`Panic::try_call`](crate::panic::Panic::try_call) and convert an |
|
85 | 99 | //! A queen is defined by implementing the [`Queen`] trait. A single `Queen` instance is used to |
86 | 100 | //! create the `Worker` instances for each worker thread in a `Hive`. |
87 | 101 | //! |
88 | | -//! It is often not necessary to manually implement the `Queen` trait. For exmaple, if your `Worker` |
| 102 | +//! If you need for the queen to have mutable state, you can instead implement [`QueenMut`], whose |
| 103 | +//! [`create`](crate::bee::QueenMut::create) method takes `&mut self` as a parameter. When |
| 104 | +//! creating a `Hive`, the `QueenMut` must be wrapped in a [`QueenCell`] to make it thread-safe. |
| 105 | +//! |
| 106 | +//! It is often not necessary to manually implement the `Queen` trait. For example, if your `Worker` |
89 | 107 | //! implements `Default`, then you can use [`DefaultQueen`] implicitly by calling |
90 | 108 | //! [`OpenBuilder::with_worker_default`](crate::hive::OpenBuilder::with_worker_default). Similarly, |
91 | 109 | //! if your `Worker` implements `Clone`, then you can use [`CloneQueen`] |
92 | 110 | //! implicitly by calling [`OpenBuilder::with_worker`](crate::hive::OpenBuilder::with_worker). |
93 | 111 | //! |
94 | 112 | //! A `Queen` should never panic when creating `Worker`s. |
95 | 113 | //! |
96 | | -//! # Implementation Notes |
97 | | -//! |
98 | | -//! It is easiest to use the [`prelude`] when implementing your bees: |
99 | | -//! |
100 | | -//! ``` |
101 | | -//! use beekeeper::bee::prelude::*; |
102 | | -//! ``` |
103 | | -//! |
104 | | -//! Note that both `Queen::create()` and `Worker::apply()` receive `&mut self`, meaning that they |
105 | | -//! can modify their own state. |
106 | | -//! |
107 | 114 | //! The state of a `Hive`'s `Queen` may be interrogated either |
108 | 115 | //! [during](crate::hive::Hive::queen) or [after](crate::hive::Hive::try_into_husk) the |
109 | 116 | //! life of the `Hive`. However, `Worker`s may never be accessed directly. Thus, it is often |
|
0 commit comments