Add some thread pool docs #421
Conversation
tokio-threadpool/src/lib.rs
Outdated
| @@ -3,6 +3,107 @@ | |||
| #![doc(html_root_url = "https://docs.rs/tokio-threadpool/0.1.4")] | |||
| #![deny(warnings, missing_docs, missing_debug_implementations)] | |||
|
|
|||
| // The Tokio thread pool is a thread pool designed to scheduled futures in Tokio | |||
There was a problem hiding this comment.
yeah, i know the tokio thread pool is a thread pool.
better: The tokio thread pool is designed to schedule futures in Tokio-based applications
(present-tense "schedule", hyphenated "Tokio-based")
tokio-threadpool/src/lib.rs
Outdated
| // * Worker threads. | ||
| // * Backup threads. | ||
| // | ||
| // Worker threads are primary threads and are used to schedule futures. These |
There was a problem hiding this comment.
is a "primary thread" something i should know about? Otherwise, this might be clearer as:
"The primary thread pool consists of worker threads and is used to schedule futures using a work-stealing strategy. Back up threads, on the other hand, are intended only to support the blocking API. Threads may transition between these pools.
tokio-threadpool/src/lib.rs
Outdated
| // threads operate using a work-stealing strategy. Backup threads are to support | ||
| // the `blocking` API. Threads will transition between the two sets. | ||
| // | ||
| // The advantage of the work-stealing strategy is minimal cross thread |
tokio-threadpool/src/lib.rs
Outdated
| // # Crate layout | ||
| // | ||
| // The primary type is `Pool`. This struct contains the majority of the pool | ||
| // state. Because worker threads will shutdown and be reestarted, the pool also |
There was a problem hiding this comment.
The primary type, Pool, holds the majority of a thread pool's state, including the state for each worker. Each worker's state is maintained in an instance of worker::Entry.
| // "steal" from that deque. The mpsc channel is used to submit futures while | ||
| // external to the pool. | ||
| // | ||
| // As long as the thread pool has not been shutdown, a worker will run in a |
There was a problem hiding this comment.
this sentence makes me wonder: what happens when the thread pool shuts down?
tokio-threadpool/src/lib.rs
Outdated
| // # Thread pool initialization | ||
| // | ||
| // By default, no threads are spawned on creation. Instead, when new futures are | ||
| // spawned, the pool first checks if there are enough active workeer threads. If |
tokio-threadpool/src/lib.rs
Outdated
| // # Spawning futures | ||
| // | ||
| // The process for spawning a future depends on whether the action is taken from | ||
| // a workere thread or external to the thread pool. |
There was a problem hiding this comment.
"a worker thread"
better: The spawning behavior depends on whether a future was spawned from within a worker or thread or if it was spawned from an external handle.
tokio-threadpool/src/lib.rs
Outdated
| // | ||
| // # Sleeping workers | ||
| // | ||
| // Sleeping workers are tracked using a treiber stack. This results in the |
There was a problem hiding this comment.
i'm not sure if Treiber is a typo or a real word. If it's a real word, perhaps include a reference.
tokio-threadpool/src/lib.rs
Outdated
| // In the first case, the worker will always be notified. However, it could be | ||
| // possible to avoid the notification if the mpsc channel has two or greater | ||
| // number of tasks *after* the task is submitted. In this case, we are able to | ||
| // assume that the worker has preeviously been notified. |
Per review suggestion by @carllerche on tokio-rs#450, this essentially reverts the promotion of these low-level detail sections, as done originally in: 014229f Promote tokio-threadpool crate level comments to rustdoc github: cc tokio-rs#421
* Normalize links to docs.rs/CRATE/M.N/... docs.rs is smart enough to show docs for the latest M.N.P release when M.N is used in the link. For example: https://docs.rs/mio/0.6/mio/struct.Poll.html ..will show mio 0.6.14 and later docs. While using the `M.N.*` (ASTERISK) syntax also works, `M.N` is the more common usage, so standarize a few existing links to that format. * Fix missing or malformed rustdoc links * executor lib rustdoc minor format change * Promote tokio-threadpool crate level comments to rustdoc * Replace hidden tokio::executor::thread_pool docs with deprecation note * Fix typo/simplify util module rustdoc * Reuse some tokio::executor::thread_pool rustdoc for the crate Relates to #421
This patch adds some additional comments to the thread pool implementation.