pax_global_header00006660000000000000000000000064143700563400014514gustar00rootroot0000000000000052 comment=052113009e7a515a40a8d7c13cfae3465ec49562 threadfin-0.1.2/000077500000000000000000000000001437005634000134605ustar00rootroot00000000000000threadfin-0.1.2/.editorconfig000066400000000000000000000002251437005634000161340ustar00rootroot00000000000000[*] indent_style = space indent_size = 4 charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true [*.{yaml,yml}] indent_size = 2 threadfin-0.1.2/.github/000077500000000000000000000000001437005634000150205ustar00rootroot00000000000000threadfin-0.1.2/.github/dependabot.yml000066400000000000000000000002211437005634000176430ustar00rootroot00000000000000version: 2 updates: - package-ecosystem: cargo directory: "/" schedule: interval: daily time: "11:00" open-pull-requests-limit: 10 threadfin-0.1.2/.github/release-drafter.yml000066400000000000000000000005141437005634000206100ustar00rootroot00000000000000categories: - title: "Security" label: security - title: "Added" labels: - feature - enhancement - title: "Fixed" label: bug - title: "Dependency Updates" label: dependencies change-template: '- $TITLE (#$NUMBER) @$AUTHOR' no-changes-template: '- No changes' template: | ## Changed $CHANGES threadfin-0.1.2/.github/workflows/000077500000000000000000000000001437005634000170555ustar00rootroot00000000000000threadfin-0.1.2/.github/workflows/ci.yml000066400000000000000000000024251437005634000201760ustar00rootroot00000000000000name: ci on: push: branches: [master] pull_request: jobs: test: strategy: matrix: include: - runner: ubuntu-latest target: x86_64-unknown-linux-gnu - runner: macos-11 target: x86_64-apple-darwin - runner: windows-latest target: x86_64-pc-windows-msvc runs-on: ${{ matrix.runner }} timeout-minutes: 10 env: RUST_BACKTRACE: 1 steps: - uses: actions/checkout@v2 - uses: actions-rs/toolchain@v1 with: profile: minimal toolchain: "1.46.0" target: ${{ matrix.target }} default: true - run: cargo test --target ${{ matrix.target }} cross-compile: strategy: matrix: include: - runner: ubuntu-latest target: armv5te-unknown-linux-gnueabi - runner: ubuntu-latest target: mipsel-unknown-linux-gnu runs-on: ${{ matrix.runner }} timeout-minutes: 10 env: RUST_BACKTRACE: 1 steps: - uses: actions/checkout@v2 - uses: actions-rs/toolchain@v1 with: profile: minimal toolchain: "1.46.0" target: ${{ matrix.target }} default: true - run: cargo build --target ${{ matrix.target }} threadfin-0.1.2/.github/workflows/release-management.yaml000066400000000000000000000003561437005634000234770ustar00rootroot00000000000000name: release management on: push: branches: [master] jobs: update-draft-release: runs-on: ubuntu-latest steps: - uses: toolmantim/release-drafter@v5 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} threadfin-0.1.2/.github/workflows/release.yml000066400000000000000000000004611437005634000212210ustar00rootroot00000000000000name: release on: release: types: [published] jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Publish to crates.io run: cargo publish --token "${CARGO_TOKEN}" --no-verify env: CARGO_TOKEN: ${{ secrets.CARGO_TOKEN }} threadfin-0.1.2/.github/workflows/sponsors.yml000066400000000000000000000011611437005634000214650ustar00rootroot00000000000000name: Update Sponsors README on: schedule: - cron: '42 3 */2 * *' jobs: update: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: JamesIves/github-sponsors-readme-action@1.0.5 with: token: ${{ secrets.SPONSORS_PAT }} minimum: 1000 file: 'README.md' template: >- {{{ login }}} - uses: stefanzweifel/git-auto-commit-action@v4 with: commit_message: Update sponsors list in README threadfin-0.1.2/.gitignore000066400000000000000000000000231437005634000154430ustar00rootroot00000000000000/target Cargo.lock threadfin-0.1.2/Cargo.toml000066400000000000000000000011551437005634000154120ustar00rootroot00000000000000[package] name = "threadfin" version = "0.1.2" description = "A thread pool for running multiple tasks on a configurable group of threads." authors = ["Stephen M. Coakley "] license = "MIT" keywords = ["threadpool", "thread", "pool", "parallel", "async"] categories = ["concurrency"] repository = "https://github.com/sagebind/threadfin" documentation = "https://docs.rs/threadfin/" readme = "README.md" edition = "2018" [dependencies] crossbeam-channel = "0.5" num_cpus = "1" once_cell = ">=1.0, <=1.14" waker-fn = "1" [dev-dependencies] futures-timer = "3" [workspace] members = ["benchmarks"] threadfin-0.1.2/LICENSE000066400000000000000000000020631437005634000144660ustar00rootroot00000000000000MIT License Copyright (c) 2021 Stephen M. Coakley Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. threadfin-0.1.2/README.md000066400000000000000000000047101437005634000147410ustar00rootroot00000000000000# Threadfin A thread pool for running multiple tasks on a configurable group of threads. [![Crates.io](https://img.shields.io/crates/v/threadfin.svg)](https://crates.io/crates/threadfin) [![Documentation](https://docs.rs/threadfin/badge.svg)](https://docs.rs/threadfin) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Minimum supported Rust version](https://img.shields.io/badge/rustc-1.51+-yellow.svg)](#minimum-supported-rust-version) [![Build](https://github.com/sagebind/threadfin/workflows/ci/badge.svg)](https://github.com/sagebind/threadfin/actions) Extra features: - Dynamic pool size based on load - Support for async tasks - Tasks return a handle which can be joined or awaited for the return value - Optional common process-wide thread pool ## Async support Threadfin supports asynchronous usage via futures, and allows you to mix and match both synchronous and asynchronous tasks within a single thread pool. ## Examples ```rust // Create a new pool. let pool = threadfin::builder().size(8).build(); // Schedule some work. let compute_task = pool.execute(|| { // Some expensive computation 2 + 2 }); // Do something in the meantime. println!("Waiting for result..."); // Wait for the task to complete and get the result. let sum = compute_task.join(); println!("Sum: 2 + 2 = {}", sum); ``` ## Installation Install via Cargo by adding to your Cargo.toml file: ```toml [dependencies] threadfin = "0.1" ``` ### Minimum supported Rust version The minimum supported Rust version (or MSRV) for Threadfin is stable Rust 1.46 or greater, meaning we only guarantee that Threadfin will compile if you use a rustc version of at least 1.46. It might compile with older versions but that could change at any time. This version is explicitly tested in CI and may only be bumped in new minor versions. Any changes to the supported minimum version will be called out in the release notes. ## Other libraries - [threadpool](https://github.com/rust-threadpool/rust-threadpool) - [scoped_threadpool](https://github.com/kimundi/scoped-threadpool-rs) - [rusty_pool](https://github.com/robinfriedli/rusty_pool) - [rayon](https://github.com/rayon-rs/rayon) ## Sponsors Special thanks to sponsors of my open-source work! da-moon ## License Licensed under the MIT license. See the [LICENSE](LICENSE) file for details. threadfin-0.1.2/benchmarks/000077500000000000000000000000001437005634000155755ustar00rootroot00000000000000threadfin-0.1.2/benchmarks/Cargo.toml000066400000000000000000000004741437005634000175320ustar00rootroot00000000000000[package] name = "threadfin-benchmarks" version = "0.0.0" authors = ["Stephen M. Coakley "] license = "MIT" edition = "2018" [dependencies.threadfin] path = ".." [dev-dependencies] criterion = "0.3" num_cpus = "1" rusty_pool = "0.7" threadpool = "1" [[bench]] name = "pool" harness = false threadfin-0.1.2/benchmarks/benches/000077500000000000000000000000001437005634000172045ustar00rootroot00000000000000threadfin-0.1.2/benchmarks/benches/pool.rs000066400000000000000000000030411437005634000205210ustar00rootroot00000000000000use criterion::*; fn criterion_benchmark(c: &mut Criterion) { let threads = num_cpus::get().max(1); let tasks = 1000; let mut group = c.benchmark_group("pool"); group.sample_size(10); group.bench_function("threadfin", |b| { b.iter_batched( || threadfin::ThreadPool::builder().size(threads).build(), |pool| { for _ in 0..tasks { pool.execute(|| { let _ = black_box(8 + 9); }); } pool.join(); }, BatchSize::LargeInput, ); }); group.bench_function("threadpool", |b| { b.iter_batched( || threadpool::ThreadPool::new(threads), |pool| { for _ in 0..tasks { pool.execute(|| { let _ = black_box(8 + 9); }); } pool.join(); }, BatchSize::LargeInput, ); }); group.bench_function("rusty_pool", |b| { b.iter_batched( || rusty_pool::ThreadPool::new(threads, threads, std::time::Duration::ZERO), |pool| { for _ in 0..tasks { pool.execute(|| { let _ = black_box(8 + 9); }); } pool.shutdown_join(); }, BatchSize::LargeInput, ); }); } criterion_group!(benches, criterion_benchmark); criterion_main!(benches); threadfin-0.1.2/benchmarks/src/000077500000000000000000000000001437005634000163645ustar00rootroot00000000000000threadfin-0.1.2/benchmarks/src/lib.rs000066400000000000000000000000001437005634000174660ustar00rootroot00000000000000threadfin-0.1.2/build.rs000066400000000000000000000006561437005634000151340ustar00rootroot00000000000000use std::env; fn main() { let target = env::var("TARGET").unwrap(); if target.starts_with("x86_64") || target.starts_with("i686") || target.starts_with("aarch64") || target.starts_with("powerpc64") || target.starts_with("sparc64") || target.starts_with("mips64el") || target.starts_with("riscv64") { println!("cargo:rustc-cfg=threadfin_has_atomic64"); } } threadfin-0.1.2/rustfmt.toml000066400000000000000000000002721437005634000160620ustar00rootroot00000000000000edition = "2018" imports_layout = "HorizontalVertical" merge_imports = true overflow_delimited_expr = true struct_lit_single_line = false use_field_init_shorthand = true version = "Two" threadfin-0.1.2/src/000077500000000000000000000000001437005634000142475ustar00rootroot00000000000000threadfin-0.1.2/src/common.rs000066400000000000000000000031121437005634000161020ustar00rootroot00000000000000use crate::{Builder, CommonAlreadyInitializedError, ThreadPool}; use once_cell::sync::OnceCell; static COMMON: OnceCell = OnceCell::new(); /// Get a shared reference to a common thread pool for the entire process. /// /// # Examples /// /// ``` /// let result = threadfin::common().execute(|| 2 + 2).join(); /// /// assert_eq!(result, 4); /// ``` pub fn common() -> &'static ThreadPool { COMMON.get_or_init(|| common_builder().build()) } /// Configure the common thread pool. /// /// This should be done near the start of your program before any other code /// uses the common pool, as this function will return an error if the common /// pool has already been initialized. /// /// Only programs should use this function! Libraries should not use this /// function and instead allow the running program to configure the common pool. /// If you need a customized pool in a library then you should use a separate /// pool instance. /// /// # Examples /// /// ``` /// threadfin::configure_common(|builder| builder /// .size(3) /// .queue_limit(1024)) /// .unwrap(); /// /// assert_eq!(threadfin::common().threads(), 3); /// ``` pub fn configure_common(f: F) -> Result<(), CommonAlreadyInitializedError> where F: FnOnce(Builder) -> Builder, { let mut was_initialized = true; COMMON.get_or_init(|| { was_initialized = false; f(common_builder()).build() }); if was_initialized { Err(CommonAlreadyInitializedError::new()) } else { Ok(()) } } fn common_builder() -> Builder { Builder::default().name("common-pool") } threadfin-0.1.2/src/error.rs000066400000000000000000000027151437005634000157530ustar00rootroot00000000000000use std::{error::Error, fmt}; /// An error returned when a task could not be executed because a thread pool /// was full. /// /// Contains the original task that failed to be submitted. This allows you to /// try the submission again later or take some other action. pub struct PoolFullError(pub(crate) T); impl PoolFullError { /// Extracts the inner task that could not be executed. pub fn into_inner(self) -> T { self.0 } } impl Error for PoolFullError {} impl fmt::Debug for PoolFullError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str("PoolFullError(..)") } } impl fmt::Display for PoolFullError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str("thread pool is full") } } /// An error returned when attempting to configure the common thread pool after /// it has already been initialized. pub struct CommonAlreadyInitializedError(()); impl CommonAlreadyInitializedError { pub(crate) fn new() -> Self { Self(()) } } impl Error for CommonAlreadyInitializedError {} impl fmt::Debug for CommonAlreadyInitializedError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str("CommonAlreadyInitializedError") } } impl fmt::Display for CommonAlreadyInitializedError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.write_str("common thread pool already initialized") } } threadfin-0.1.2/src/lib.rs000066400000000000000000000024551437005634000153710ustar00rootroot00000000000000//! A thread pool for running multiple tasks on a configurable group of threads. //! //! Extra features: //! //! - Dynamic pool size based on load //! - Support for async tasks //! - Tasks return a handle which can be joined or awaited for the return value //! - Optional common process-wide thread pool //! //! ## Async support //! //! Threadfin supports asynchronous usage via futures, and allows you to mix and //! match both synchronous and asynchronous tasks within a single thread pool. //! //! ## Examples //! //! ``` //! // Create a new pool. //! let pool = threadfin::builder().size(8).build(); //! //! // Schedule some work. //! let compute_task = pool.execute(|| { //! // Some expensive computation //! 2 + 2 //! }); //! //! // Do something in the meantime. //! println!("Waiting for result..."); //! //! // Wait for the task to complete and get the result. //! let sum = compute_task.join(); //! println!("Sum: 2 + 2 = {}", sum); //! ``` mod common; mod error; mod pool; mod task; mod wakers; mod worker; pub use crate::{ common::*, error::*, pool::{Builder, PerCore, SizeConstraint, ThreadPool}, task::Task, }; /// Get a builder for creating a customized thread pool. /// /// A shorthand for [`ThreadPool::builder`]. #[inline] pub fn builder() -> Builder { ThreadPool::builder() } threadfin-0.1.2/src/pool.rs000066400000000000000000000674061437005634000156030ustar00rootroot00000000000000//! Implementation of the thread pool itself. use std::{ fmt, future::Future, ops::{Range, RangeInclusive, RangeTo, RangeToInclusive}, sync::{ atomic::{AtomicUsize, Ordering}, Arc, Condvar, Mutex, }, thread, time::{Duration, Instant}, }; use crossbeam_channel::{bounded, unbounded, Receiver, Sender}; use once_cell::sync::Lazy; use crate::{ error::PoolFullError, task::{Coroutine, Task}, worker::{Listener, Worker}, }; #[cfg(threadfin_has_atomic64)] type AtomicCounter = std::sync::atomic::AtomicU64; #[cfg(not(threadfin_has_atomic64))] type AtomicCounter = std::sync::atomic::AtomicU32; /// A value describing a size constraint for a thread pool. /// /// Any size constraint can be wrapped in [`PerCore`] to be made relative to the /// number of available CPU cores on the current system. /// /// See [`Builder::size`] for details. pub trait SizeConstraint { /// Get the minimum number of threads to be in the thread pool. fn min(&self) -> usize; /// Get the maximum number of threads to be in the thread pool. fn max(&self) -> usize; } impl SizeConstraint for usize { fn min(&self) -> usize { *self } fn max(&self) -> usize { *self } } impl SizeConstraint for Range { fn min(&self) -> usize { self.start } fn max(&self) -> usize { self.end } } impl SizeConstraint for RangeInclusive { fn min(&self) -> usize { *self.start() } fn max(&self) -> usize { *self.end() } } impl SizeConstraint for RangeTo { fn min(&self) -> usize { 0 } fn max(&self) -> usize { self.end } } impl SizeConstraint for RangeToInclusive { fn min(&self) -> usize { 0 } fn max(&self) -> usize { self.end } } /// Modifies a size constraint to be per available CPU core. /// /// # Examples /// /// ``` /// # use threadfin::PerCore; /// // one thread per core /// let size = PerCore(1); /// /// // four threads per core /// let size = PerCore(4); /// /// // at least 1 thread per core and at most 2 threads per core /// let size = PerCore(1..2); /// ``` pub struct PerCore(pub T); static CORE_COUNT: Lazy = Lazy::new(|| num_cpus::get().max(1)); impl From for PerCore { fn from(size: T) -> Self { Self(size) } } impl SizeConstraint for PerCore { fn min(&self) -> usize { *CORE_COUNT * self.0.min() } fn max(&self) -> usize { *CORE_COUNT * self.0.max() } } /// A builder for constructing a customized [`ThreadPool`]. /// /// # Examples /// /// ``` /// let custom_pool = threadfin::builder() /// .name("my-pool") /// .size(2) /// .build(); /// ``` #[derive(Debug)] pub struct Builder { name: Option, size: Option<(usize, usize)>, stack_size: Option, queue_limit: Option, worker_concurrency_limit: usize, keep_alive: Duration, } impl Default for Builder { fn default() -> Self { Self { name: None, size: None, stack_size: None, queue_limit: None, worker_concurrency_limit: 16, keep_alive: Duration::from_secs(60), } } } impl Builder { /// Set a custom thread name for threads spawned by this thread pool. /// /// # Panics /// /// Panics if the name contains null bytes (`\0`). /// /// # Examples /// /// ``` /// let pool = threadfin::builder().name("my-pool").build(); /// ``` pub fn name>(mut self, name: T) -> Self { let name = name.into(); if name.as_bytes().contains(&0) { panic!("thread pool name must not contain null bytes"); } self.name = Some(name); self } /// Set the number of threads to be managed by this thread pool. /// /// If a `usize` is supplied, the pool will have a fixed number of threads. /// If a range is supplied, the lower bound will be the core pool size while /// the upper bound will be a maximum pool size the pool is allowed to burst /// up to when the core threads are busy. /// /// Any size constraint can be wrapped in [`PerCore`] to be made relative to /// the number of available CPU cores on the current system. /// /// If not set, a reasonable size will be selected based on the number of /// CPU cores on the current system. /// /// # Examples /// /// ``` /// // Create a thread pool with exactly 2 threads. /// let pool = threadfin::builder().size(2).build(); /// ``` /// /// ``` /// // Create a thread pool with no idle threads, but will spawn up to 4 /// // threads lazily when there's work to be done. /// let pool = threadfin::builder().size(0..4).build(); /// /// // Or equivalently: /// let pool = threadfin::builder().size(..4).build(); /// ``` /// /// ``` /// use threadfin::PerCore; /// /// // Create a thread pool with two threads per core. /// let pool = threadfin::builder().size(PerCore(2)).build(); /// ``` /// /// # Panics /// /// Panics if an invalid range is supplied with a lower bound larger than /// the upper bound, or if the upper bound is 0. pub fn size(mut self, size: S) -> Self { let (min, max) = (size.min(), size.max()); if min > max { panic!("thread pool minimum size cannot be larger than maximum size"); } if max == 0 { panic!("thread pool maximum size must be non-zero"); } self.size = Some((min, max)); self } /// Set the size of the stack (in bytes) for threads in this thread pool. /// /// The actual stack size may be greater than this value if the platform /// enforces a larger minimum stack size. /// /// The stack size if not specified will be the default size for new Rust /// threads, currently 2 MiB. This can also be overridden by setting the /// `RUST_MIN_STACK` environment variable if not specified in code. /// /// # Examples /// /// ``` /// // Worker threads will have a stack size of at least 32 KiB. /// let pool = threadfin::builder().stack_size(32 * 1024).build(); /// ``` pub fn stack_size(mut self, size: usize) -> Self { self.stack_size = Some(size); self } /// Set a maximum number of pending tasks allowed to be submitted before /// blocking. /// /// If set to zero, queueing will be disabled and attempting to execute a /// new task will block until an idle worker thread can immediately begin /// executing the task or a new worker thread can be created to execute the /// task. /// /// If not set, no limit is enforced. pub fn queue_limit(mut self, limit: usize) -> Self { self.queue_limit = Some(limit); self } /// Set a duration for how long to keep idle worker threads alive. /// /// If the pool has more than the minimum configured number of threads and /// threads remain idle for more than this duration, they will be terminated /// until the minimum thread count is reached. pub fn keep_alive(mut self, duration: Duration) -> Self { self.keep_alive = duration; self } /// Set a limit on the number of concurrent tasks that can be run by a /// single worker thread. /// /// When executing asynchronous tasks, if the underlying future being /// executed yields, that worker thread can begin working on new tasks /// concurrently while waiting on the prior task to resume. This allows for /// a primitive M:N scheduling model that supports running significantly /// more futures concurrently than the number of threads in the thread pool. /// /// To prevent a worker thread from over-committing to too many tasks at /// once (which could result in extra latency if a task wakes but its /// assigned worker is too busy with other tasks) worker threads limit /// themselves to a maximum number of concurrent tasks. This method allows /// you to customize that limit. /// /// The default limit if not specified is 16. pub fn worker_concurrency_limit(mut self, limit: usize) -> Self { self.worker_concurrency_limit = limit; self } /// Create a thread pool according to the configuration set with this /// builder. pub fn build(self) -> ThreadPool { let size = self.size.unwrap_or_else(|| { let size = PerCore(1..2); (size.min(), size.max()) }); let shared = Shared { min_threads: size.0, max_threads: size.1, thread_count: Default::default(), running_tasks_count: Default::default(), completed_tasks_count: Default::default(), panicked_tasks_count: Default::default(), keep_alive: self.keep_alive, shutdown_cvar: Condvar::new(), }; let pool = ThreadPool { thread_name: self.name, stack_size: self.stack_size, concurrency_limit: self.worker_concurrency_limit, queue: self.queue_limit.map(bounded).unwrap_or_else(unbounded), immediate_queue: bounded(0), shared: Arc::new(shared), }; for _ in 0..size.0 { let result = pool.spawn_thread(None); assert!(result.is_ok()); } pool } } /// A thread pool for running multiple tasks on a configurable group of threads. /// /// Thread pools can improve performance when executing a large number of /// concurrent tasks since the expensive overhead of spawning threads is /// minimized as threads are re-used for multiple tasks. Thread pools are also /// useful for controlling and limiting parallelism. /// /// Dropping the thread pool will prevent any further tasks from being scheduled /// on the pool and detaches all threads in the pool. If you want to block until /// all pending tasks have completed and the pool is entirely shut down, then /// use one of the available [`join`](ThreadPool::join) methods. /// /// # Pool size /// /// Every thread pool has a minimum and maximum number of worker threads that it /// will spawn for executing tasks. This range is known as the _pool size_, and /// affects pool behavior in the following ways: /// /// - **Minimum size**: A guaranteed number of threads that will always be /// created and maintained by the thread pool. Threads will be eagerly created /// to meet this minimum size when the pool is created, and at least this many /// threads will be kept running in the pool until the pool is shut down. /// - **Maximum size**: A limit on the number of additional threads to spawn to /// execute more work. /// /// # Queueing /// /// If a new or existing worker thread is unable to immediately start processing /// a submitted task, that task will be placed in a queue for worker threads to /// take from when they complete their current tasks. Queueing is only used when /// it is not possible to directly handoff a task to an existing thread and /// spawning a new thread would exceed the pool's configured maximum size. /// /// By default, thread pools are configured to use an _unbounded_ queue which /// can hold an unlimited number of pending tasks. This is a sensible default, /// but is not desirable in all use-cases and can be changed with /// [`Builder::queue_limit`]. /// /// # Monitoring /// /// Each pool instance provides methods for gathering various statistics on the /// pool's usage, such as number of current number of threads, tasks completed /// over time, and queued tasks. While these methods provide the most up-to-date /// numbers upon invocation, they should not be used for controlling program /// behavior since they can become immediately outdated due to the live nature /// of the pool. pub struct ThreadPool { thread_name: Option, stack_size: Option, concurrency_limit: usize, queue: (Sender, Receiver), immediate_queue: (Sender, Receiver), shared: Arc, } impl Default for ThreadPool { fn default() -> Self { Self::new() } } impl ThreadPool { /// Create a new thread pool with the default configuration. /// /// If you'd like to customize the thread pool's behavior then use /// [`ThreadPool::builder`]. #[inline] pub fn new() -> Self { Self::builder().build() } /// Get a builder for creating a customized thread pool. #[inline] pub fn builder() -> Builder { Builder::default() } /// Get the number of threads currently running in the thread pool. pub fn threads(&self) -> usize { *self.shared.thread_count.lock().unwrap() } /// Get the number of tasks queued for execution, but not yet started. /// /// This number will always be less than or equal to the configured /// [`queue_limit`](Builder::queue_limit), if any. /// /// Note that the number returned may become immediately outdated after /// invocation. /// /// # Examples /// /// ``` /// use std::{thread::sleep, time::Duration}; /// /// // Create a pool with just one thread. /// let pool = threadfin::builder().size(1).build(); /// /// // Nothing is queued yet. /// assert_eq!(pool.queued_tasks(), 0); /// /// // Start a slow task. /// let task = pool.execute(|| { /// sleep(Duration::from_millis(100)); /// }); /// /// // Wait a little for the task to start. /// sleep(Duration::from_millis(10)); /// assert_eq!(pool.queued_tasks(), 0); /// /// // Enqueue some more tasks. /// let count = 4; /// for _ in 0..count { /// pool.execute(|| { /// // work to do /// }); /// } /// /// // The tasks should still be in the queue because the slow task is /// // running on the only thread. /// assert_eq!(pool.queued_tasks(), count); /// # pool.join(); /// ``` #[inline] pub fn queued_tasks(&self) -> usize { self.queue.0.len() } /// Get the number of tasks currently running. /// /// Note that the number returned may become immediately outdated after /// invocation. /// /// # Examples /// /// ``` /// use std::{thread::sleep, time::Duration}; /// /// let pool = threadfin::ThreadPool::new(); /// /// // Nothing is running yet. /// assert_eq!(pool.running_tasks(), 0); /// /// // Start a task. /// let task = pool.execute(|| { /// sleep(Duration::from_millis(100)); /// }); /// /// // Wait a little for the task to start. /// sleep(Duration::from_millis(10)); /// assert_eq!(pool.running_tasks(), 1); /// /// // Wait for the task to complete. /// task.join(); /// assert_eq!(pool.running_tasks(), 0); /// ``` #[inline] pub fn running_tasks(&self) -> usize { self.shared.running_tasks_count.load(Ordering::Relaxed) } /// Get the number of tasks completed (successfully or otherwise) by this /// pool since it was created. /// /// Note that the number returned may become immediately outdated after /// invocation. /// /// # Examples /// /// ``` /// let pool = threadfin::ThreadPool::new(); /// assert_eq!(pool.completed_tasks(), 0); /// /// pool.execute(|| 2 + 2).join(); /// assert_eq!(pool.completed_tasks(), 1); /// /// pool.execute(|| 2 + 2).join(); /// assert_eq!(pool.completed_tasks(), 2); /// ``` #[inline] #[allow(clippy::useless_conversion)] pub fn completed_tasks(&self) -> u64 { self.shared.completed_tasks_count.load(Ordering::Relaxed).into() } /// Get the number of tasks that have panicked since the pool was created. /// /// Note that the number returned may become immediately outdated after /// invocation. /// /// # Examples /// /// ``` /// use std::{thread::sleep, time::Duration}; /// /// let pool = threadfin::ThreadPool::new(); /// assert_eq!(pool.panicked_tasks(), 0); /// /// let task = pool.execute(|| { /// panic!("this task panics"); /// }); /// /// while !task.is_done() { /// sleep(Duration::from_millis(100)); /// } /// /// assert_eq!(pool.panicked_tasks(), 1); /// ``` #[inline] #[allow(clippy::useless_conversion)] pub fn panicked_tasks(&self) -> u64 { self.shared.panicked_tasks_count.load(Ordering::SeqCst).into() } /// Submit a closure to be executed by the thread pool. /// /// If all worker threads are busy, but there are less threads than the /// configured maximum, an additional thread will be created and added to /// the pool to execute this task. /// /// If all worker threads are busy and the pool has reached the configured /// maximum number of threads, the task will be enqueued. If the queue is /// configured with a limit, this call will block until space becomes /// available in the queue. /// /// # Examples /// /// ``` /// let pool = threadfin::ThreadPool::new(); /// let task = pool.execute(|| { /// 2 + 2 // some expensive computation /// }); /// /// // do something in the meantime /// /// // now wait for the result /// let sum = task.join(); /// assert_eq!(sum, 4); /// ``` pub fn execute(&self, closure: F) -> Task where T: Send + 'static, F: FnOnce() -> T + Send + 'static, { let (task, coroutine) = Task::from_closure(closure); self.execute_coroutine(coroutine); task } /// Submit a future to be executed by the thread pool. /// /// If all worker threads are busy, but there are less threads than the /// configured maximum, an additional thread will be created and added to /// the pool to execute this task. /// /// If all worker threads are busy and the pool has reached the configured /// maximum number of threads, the task will be enqueued. If the queue is /// configured with a limit, this call will block until space becomes /// available in the queue. /// /// # Thread locality /// /// While the given future must implement [`Send`] to be moved into a thread /// in the pool to be processed, once the future is assigned a thread it /// will stay assigned to that single thread until completion. This improves /// cache locality even across `.await` points in the future. /// /// ``` /// let pool = threadfin::ThreadPool::new(); /// let task = pool.execute_future(async { /// 2 + 2 // some asynchronous code /// }); /// /// // do something in the meantime /// /// // now wait for the result /// let sum = task.join(); /// assert_eq!(sum, 4); /// ``` pub fn execute_future(&self, future: F) -> Task where T: Send + 'static, F: Future + Send + 'static, { let (task, coroutine) = Task::from_future(future); self.execute_coroutine(coroutine); task } /// Attempts to execute a closure on the thread pool without blocking. /// /// If the pool is at its max thread count and the task queue is full, the /// task is rejected and an error is returned. The original closure can be /// extracted from the error. /// /// # Examples /// /// One use for this method is implementing backpressure by executing a /// closure on the current thread if a pool is currently full. /// /// ``` /// let pool = threadfin::ThreadPool::new(); /// /// // Try to run a closure in the thread pool. /// let result = pool.try_execute(|| 2 + 2) /// // If successfully submitted, block until the task completes. /// .map(|task| task.join()) /// // If the pool was full, invoke the closure here and now. /// .unwrap_or_else(|error| error.into_inner()()); /// /// assert_eq!(result, 4); /// ``` pub fn try_execute(&self, closure: F) -> Result, PoolFullError> where T: Send + 'static, F: FnOnce() -> T + Send + 'static, { let (task, coroutine) = Task::from_closure(closure); self.try_execute_coroutine(coroutine) .map(|_| task) .map_err(|coroutine| PoolFullError(coroutine.into_inner_closure())) } /// Attempts to execute a future on the thread pool without blocking. /// /// If the pool is at its max thread count and the task queue is full, the /// task is rejected and an error is returned. The original future can be /// extracted from the error. pub fn try_execute_future(&self, future: F) -> Result, PoolFullError> where T: Send + 'static, F: Future + Send + 'static, { let (task, coroutine) = Task::from_future(future); self.try_execute_coroutine(coroutine) .map(|_| task) .map_err(|coroutine| PoolFullError(coroutine.into_inner_future())) } fn execute_coroutine(&self, coroutine: Coroutine) { if let Err(coroutine) = self.try_execute_coroutine(coroutine) { // Cannot fail because we hold a reference to both the channel // sender and receiver and it cannot be closed here. self.queue.0.send(coroutine).unwrap(); } } fn try_execute_coroutine(&self, coroutine: Coroutine) -> Result<(), Coroutine> { // First, try to pass the coroutine to an idle worker currently polling // for work. This is the most favorable scenario for a task to begin // processing. if let Err(e) = self.immediate_queue.0.try_send(coroutine) { // Error means no workers are currently polling the queue. debug_assert!(!e.is_disconnected()); // If possible, spawn an additional thread to handle the task. if let Err(e) = self.spawn_thread(Some(e.into_inner())) { // Finally as a last resort, enqueue the task into the queue, // but only if it isn't full. if let Err(e) = self.queue.0.try_send(e.unwrap()) { return Err(e.into_inner()); } } } Ok(()) } /// Shut down this thread pool and block until all existing tasks have /// completed and threads have stopped. pub fn join(self) { self.join_internal(None); } /// Shut down this thread pool and block until all existing tasks have /// completed and threads have stopped, or until the given timeout passes. /// /// Returns `true` if the thread pool shut down fully before the timeout. pub fn join_timeout(self, timeout: Duration) -> bool { self.join_deadline(Instant::now() + timeout) } /// Shut down this thread pool and block until all existing tasks have /// completed and threads have stopped, or the given deadline passes. /// /// Returns `true` if the thread pool shut down fully before the deadline. pub fn join_deadline(self, deadline: Instant) -> bool { self.join_internal(Some(deadline)) } fn join_internal(self, deadline: Option) -> bool { // Closing this channel will interrupt any idle workers and signal to // all workers that the pool is shutting down. drop(self.queue.0); let mut thread_count = self.shared.thread_count.lock().unwrap(); while *thread_count > 0 { // If a deadline is set, figure out how much time is remaining and // wait for that amount. if let Some(deadline) = deadline { if let Some(timeout) = deadline.checked_duration_since(Instant::now()) { thread_count = self .shared .shutdown_cvar .wait_timeout(thread_count, timeout) .unwrap() .0; } else { return false; } } // If a deadline is not set, wait forever. else { thread_count = self.shared.shutdown_cvar.wait(thread_count).unwrap(); } } true } /// Spawn an additional thread into the thread pool, if possible. /// /// If an initial thunk is given, it will be the first thunk the thread /// executes once ready for work. fn spawn_thread(&self, initial_task: Option) -> Result<(), Option> { struct WorkerListener { shared: Arc, } impl Listener for WorkerListener { fn on_task_started(&mut self) { self.shared .running_tasks_count .fetch_add(1, Ordering::Relaxed); } fn on_task_completed(&mut self, panicked: bool) { self.shared .running_tasks_count .fetch_sub(1, Ordering::Relaxed); self.shared .completed_tasks_count .fetch_add(1, Ordering::Relaxed); if panicked { self.shared .panicked_tasks_count .fetch_add(1, Ordering::SeqCst); } } fn on_idle(&mut self) -> bool { // Check if the worker should shut down by seeing if we are over // the minimum worker count. *self.shared.thread_count.lock().unwrap() > self.shared.min_threads } } impl Drop for WorkerListener { fn drop(&mut self) { if let Ok(mut count) = self.shared.thread_count.lock() { *count = count.saturating_sub(1); self.shared.shutdown_cvar.notify_all(); } } } // Lock the thread count to prevent race conditions when determining // whether new threads can be created. let mut thread_count = self.shared.thread_count.lock().unwrap(); // We've reached the configured limit for threads, do nothing. if *thread_count >= self.shared.max_threads { return Err(initial_task); } // Configure the thread based on the thread pool configuration. let mut builder = thread::Builder::new(); if let Some(name) = self.thread_name.as_ref() { builder = builder.name(name.clone()); } if let Some(size) = self.stack_size { builder = builder.stack_size(size); } *thread_count += 1; let worker = Worker::new( initial_task, self.queue.1.clone(), self.immediate_queue.1.clone(), self.concurrency_limit, self.shared.keep_alive, WorkerListener { shared: self.shared.clone(), }, ); // We can now safely unlock the thread count since the worker struct // will decrement the count again if it is dropped. drop(thread_count); builder.spawn(move || worker.run()).unwrap(); Ok(()) } } impl fmt::Debug for ThreadPool { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("ThreadPool") .field("queued_tasks", &self.queued_tasks()) .field("running_tasks", &self.running_tasks()) .field("completed_tasks", &self.completed_tasks()) .finish() } } /// Thread pool state shared by the owner and the worker threads. struct Shared { min_threads: usize, max_threads: usize, thread_count: Mutex, running_tasks_count: AtomicUsize, completed_tasks_count: AtomicCounter, panicked_tasks_count: AtomicCounter, keep_alive: Duration, shutdown_cvar: Condvar, } threadfin-0.1.2/src/task.rs000066400000000000000000000322071437005634000155630ustar00rootroot00000000000000//! Implementation of a task, as well as underlying primitives used to drive //! their execution. use std::{ any::Any, fmt, future::Future, panic::{catch_unwind, resume_unwind, AssertUnwindSafe}, pin::Pin, sync::{Arc, Mutex}, task::{Context, Poll, Waker}, thread, time::{Duration, Instant}, }; /// A type of future representing the result of a background computation in a /// thread pool. Tasks are returned when submitting a closure or future to a /// thread pool. /// /// Tasks implement [`Future`], so you can `.await` their completion /// asynchronously. Or, you can wait for their completion synchronously using /// the various [`join`](Task::join) methods provided. /// /// Dropping a task detaches the running task, but does not cancel it. The task /// will continue to run on the thread pool until completion, but there will no /// longer be any way to check its completion or to retrieve its returned value. /// /// # Examples /// /// Creating a task: /// /// ``` /// use threadfin::ThreadPool; /// /// let pool = ThreadPool::new(); /// /// let task = pool.execute(|| { /// // do some work /// }); /// ``` /// /// Blocking on a task: /// /// ``` /// use threadfin::ThreadPool; /// /// let pool = ThreadPool::new(); /// /// let task = pool.execute(|| { /// // some expensive computation /// 2 + 2 /// }); /// /// // do something in the meantime /// /// // now block on the result /// let sum = task.join(); /// assert_eq!(sum, 4); /// ``` /// /// Awaiting a task asynchronously: /// /// ``` /// # threadfin::common().execute_future(async { /// use threadfin::ThreadPool; /// /// let pool = ThreadPool::new(); /// /// let task = pool.execute(|| { /// // some expensive, synchronous computation /// 2 + 2 /// }); /// /// // do something in the meantime /// /// // now await on the result /// let sum = task.await; /// assert_eq!(sum, 4); /// # }).join(); /// ``` /// /// Detaching a task: /// /// ``` /// use std::sync::{Arc, atomic::{AtomicBool, Ordering}}; /// use std::thread::sleep; /// use std::time::Duration; /// use threadfin::ThreadPool; /// /// let pool = Arc::new(ThreadPool::new()); /// let completed = Arc::new(AtomicBool::from(false)); /// /// // Clone the shared values to be used inside the task. /// let pool_clone = pool.clone(); /// let completed_clone = completed.clone(); /// /// pool.execute(move || { /// let _inner_task = pool_clone.execute(move || { /// // Short delay simulating some work. /// sleep(Duration::from_millis(100)); /// /// // Set as complete. /// completed_clone.store(true, Ordering::SeqCst); /// }); /// /// // Inner task is detached, but will still complete. /// }); /// /// // Give the task some time to complete. /// sleep(Duration::from_millis(1000)); /// /// // Inner task completed even though it was detached. /// assert_eq!(completed.load(Ordering::SeqCst), true); /// ``` pub struct Task { inner: Arc>>, } struct Inner { result: Option>, waker: Option, } impl Task { /// Create a new task from a closure. pub(crate) fn from_closure(closure: F) -> (Self, Coroutine) where F: FnOnce() -> T + Send + 'static, T: Send + 'static, { let task = Self::pending(); let coroutine = Coroutine { might_yield: false, waker: crate::wakers::empty_waker(), poller: Box::new(ClosurePoller { closure: Some(closure), result: None, task: task.inner.clone(), }), }; (task, coroutine) } /// Create a new asynchronous task from a future. pub(crate) fn from_future(future: F) -> (Self, Coroutine) where F: Future + Send + 'static, T: Send + 'static, { let task = Self::pending(); let coroutine = Coroutine { might_yield: true, waker: crate::wakers::empty_waker(), poller: Box::new(FuturePoller { future, result: None, task: task.inner.clone(), }), }; (task, coroutine) } fn pending() -> Self { Self { inner: Arc::new(Mutex::new(Inner { result: None, waker: None, })), } } /// Check if the task is done yet. /// /// If this method returns true, then calling [`join`](Task::join) will not /// block. pub fn is_done(&self) -> bool { self.inner.lock().unwrap().result.is_some() } /// Block the current thread until the task completes and return the value /// the task produced. /// /// # Panics /// /// If the underlying task panics, the panic will propagate to this call. pub fn join(self) -> T { match self.join_catch() { Ok(value) => value, Err(e) => resume_unwind(e), } } fn join_catch(self) -> thread::Result { let mut inner = self.inner.lock().unwrap(); if let Some(result) = inner.result.take() { result } else { inner.waker = Some(crate::wakers::current_thread_waker()); drop(inner); loop { thread::park(); if let Some(result) = self.inner.lock().unwrap().result.take() { break result; } } } } /// Block the current thread until the task completes or a timeout is /// reached. /// /// # Panics /// /// If the underlying task panics, the panic will propagate to this call. pub fn join_timeout(self, timeout: Duration) -> Result { self.join_deadline(Instant::now() + timeout) } /// Block the current thread until the task completes or a timeout is /// reached. /// /// # Panics /// /// If the underlying task panics, the panic will propagate to this call. pub fn join_deadline(self, deadline: Instant) -> Result { match { let mut inner = self.inner.lock().unwrap(); if let Some(result) = inner.result.take() { result } else { inner.waker = Some(crate::wakers::current_thread_waker()); drop(inner); loop { if let Some(timeout) = deadline.checked_duration_since(Instant::now()) { thread::park_timeout(timeout); } else { return Err(self); } if let Some(result) = self.inner.lock().unwrap().result.take() { break result; } } } } { Ok(value) => Ok(value), Err(e) => resume_unwind(e), } } } impl Future for Task { type Output = T; fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { let mut inner = self.inner.lock().unwrap(); match inner.result.take() { Some(Ok(value)) => Poll::Ready(value), Some(Err(e)) => resume_unwind(e), None => { inner.waker = Some(cx.waker().clone()); Poll::Pending } } } } impl fmt::Debug for Task { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { f.debug_struct("Task") .field("done", &self.is_done()) .finish() } } /// The worker side of an allocated task, which provides methods for running the /// underlying future to completion. pub(crate) struct Coroutine { might_yield: bool, waker: Waker, poller: Box, } impl Coroutine { /// Determine whether this task might yield. This can be used for /// optimizations if you know for certain a waker will never be used. pub(crate) fn might_yield(&self) -> bool { self.might_yield } /// Get the unique memory address for this coroutine. pub(crate) fn addr(&self) -> usize { &*self.poller as *const dyn CoroutinePoller as *const () as usize } /// Set the waker to use with this task. pub(crate) fn set_waker(&mut self, waker: Waker) { self.waker = waker; } /// Run the coroutine until it yields or completes. /// /// Once this function returns `Complete` it should not be called again. Doing /// so may panic, return weird results, or cause other problems. pub(crate) fn run(&mut self) -> RunResult { let mut cx = Context::from_waker(&self.waker); self.poller.run(&mut cx) } /// Complete the task with the final value produced by this coroutine and /// notify any listeners on this task that the task's state has updated. /// /// Must not be called unless `run` has returned `Complete`. This method may /// panic or cause other strange behavior otherwise. /// /// You must call this yourself when the task completes. It won't be called /// automatically! pub(crate) fn complete(mut self) { self.poller.complete(); } /// Unwrap the original closure the coroutine was created from. Panics if /// the coroutine was not created from a closure. pub(crate) fn into_inner_closure(self) -> F where F: FnOnce() -> T + Send + 'static, T: Send + 'static, { self .poller .into_any() .downcast::>() .unwrap() .closure .take() .unwrap() } /// Unwrap the original future the coroutine was created from. Panics if the /// coroutine was not created from a future. pub(crate) fn into_inner_future(self) -> F where F: Future + Send + 'static, T: Send + 'static, { self .poller .into_any() .downcast::>() .unwrap() .future } } #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) enum RunResult { /// The coroutine has yielded. You should call `run` on the coroutine again /// once the waker associated with the coroutine is called. Yield, /// The coroutine and its associated task has completed. You should call /// [`Coroutine::complete`] to wake any consumers of the task to receive the /// task result. Complete { panicked: bool }, } /// Inner implementation of a coroutine. This trait is used to erase the return /// value from the coroutine type as well as to abstract over futures and /// synchronous closures. Bundling all the required operations into this trait /// also allows us to minimize the number of heap allocations per task. trait CoroutinePoller: Send + 'static { fn run(&mut self, cx: &mut Context) -> RunResult; fn complete(&mut self); fn into_any(self: Box) -> Box; } struct ClosurePoller { closure: Option, result: Option>, task: Arc>>, } impl CoroutinePoller for ClosurePoller where F: FnOnce() -> T + Send + 'static, T: Send + 'static, { fn run(&mut self, _cx: &mut Context) -> RunResult { let closure = self .closure .take() .expect("closure already ran to completion"); let result = catch_unwind(AssertUnwindSafe(closure)); let panicked = result.is_err(); self.result = Some(result); RunResult::Complete { panicked, } } fn complete(&mut self) { if let Some(result) = self.result.take() { let mut task = self.task.lock().unwrap(); task.result = Some(result); if let Some(waker) = task.waker.as_ref() { waker.wake_by_ref(); }; } } fn into_any(self: Box) -> Box { self } } struct FuturePoller { future: F, result: Option>, task: Arc>>, } impl CoroutinePoller for FuturePoller where F: Future + Send + 'static, T: Send + 'static, { fn run(&mut self, cx: &mut Context) -> RunResult { // Safety: This struct is only ever used inside a box, so we know that // neither self nor this future will move. let future = unsafe { Pin::new_unchecked(&mut self.future) }; match catch_unwind(AssertUnwindSafe(|| future.poll(cx))) { Ok(Poll::Pending) => RunResult::Yield, Ok(Poll::Ready(value)) => { self.result = Some(Ok(value)); RunResult::Complete { panicked: false, } } Err(e) => { self.result = Some(Err(e)); RunResult::Complete { panicked: true, } } } } fn complete(&mut self) { if let Some(result) = self.result.take() { let mut task = self.task.lock().unwrap(); task.result = Some(result); if let Some(waker) = task.waker.as_ref() { waker.wake_by_ref(); }; } } fn into_any(self: Box) -> Box { self } } threadfin-0.1.2/src/wakers.rs000066400000000000000000000010571437005634000161140ustar00rootroot00000000000000use std::{ task::Waker, thread::{self, Thread}, }; use once_cell::sync::Lazy; /// Creates a dummy waker that does nothing. pub(crate) fn empty_waker() -> Waker { static WAKER: Lazy = Lazy::new(|| waker_fn::waker_fn(move || {})); WAKER.clone() } /// Creates a waker that unparks the current thread. pub(crate) fn current_thread_waker() -> Waker { thread_waker(thread::current()) } /// Creates a waker that unparks a thread. pub(crate) fn thread_waker(thread: Thread) -> Waker { waker_fn::waker_fn(move || thread.unpark()) } threadfin-0.1.2/src/worker.rs000066400000000000000000000156111437005634000161320ustar00rootroot00000000000000use std::{collections::HashMap, time::Duration}; use crossbeam_channel::{unbounded, Receiver, Select, Sender}; use crate::task::{Coroutine, RunResult}; /// A type which receives notifications from a worker. pub(crate) trait Listener { fn on_task_started(&mut self) {} fn on_task_completed(&mut self, _panicked: bool) {} fn on_idle(&mut self) -> bool { true } } /// A worker thread which belongs to a thread pool and executes tasks. pub(crate) struct Worker { keep_alive: Duration, concurrency_limit: usize, /// An initial task this worker should be run before polling for new work. initial_task: Option, /// Pending tasks being run by this worker. Any task that yields without /// being immediately complete is moved to this location to be polled again. pending_tasks: HashMap, /// Queue of new tasks to run. The worker pulls more tasks from this queue /// when idle. queue: Receiver, immediate_queue: Receiver, /// Channel used to receive notifications from wakers for pending tasks. wake_notifications: (Sender, Receiver), /// Set to true when the worker is running and wants to consume more work. active: bool, /// Receiver of various worker events. listener: L, } impl Worker { /// Create a new worker. pub(crate) fn new( initial_task: Option, queue: Receiver, immediate_queue: Receiver, concurrency_limit: usize, keep_alive: Duration, listener: L, ) -> Self { Self { keep_alive, concurrency_limit, initial_task, pending_tasks: HashMap::new(), queue, immediate_queue, wake_notifications: unbounded(), active: false, listener, } } /// Run the worker on the current thread until the work queue is closed. pub(crate) fn run(mut self) { self.active = true; if let Some(coroutine) = self.initial_task.take() { self.run_now_or_reschedule(coroutine); } // Main worker loop, keep running until the pool shuts down and pending // tasks complete. while self.active || !self.pending_tasks.is_empty() { match self.poll_work() { PollResult::Work(coroutine) => self.run_now_or_reschedule(coroutine), PollResult::Wake(id) => self.run_pending_by_id(id), PollResult::ShutDown => self.active = false, PollResult::Timeout => { // If this worker doesn't have an pending tasks, then we can // potentially shut down the worker due to inactivity. if self.pending_tasks.is_empty() { // If the listener tells us we ought to shut down, then // do so. if self.listener.on_idle() { self.active = false; } } } } } } /// Poll for the next work item the worker should work on. fn poll_work(&mut self) -> PollResult { let mut queue_id = None; let mut immediate_queue_id = None; let mut wake_id = None; let mut select = Select::new(); // As long as we haven't reached our concurrency limit, poll for // additional work. if self.active && self.pending_tasks.len() < self.concurrency_limit { queue_id = Some(select.recv(&self.queue)); immediate_queue_id = Some(select.recv(&self.immediate_queue)); } // If we have pending tasks, poll for waker notifications as well. if !self.pending_tasks.is_empty() { wake_id = Some(select.recv(&self.wake_notifications.1)); } match select.select_timeout(self.keep_alive) { Ok(op) if Some(op.index()) == queue_id => { if let Ok(coroutine) = op.recv(&self.queue) { PollResult::Work(coroutine) } else { PollResult::ShutDown } } Ok(op) if Some(op.index()) == immediate_queue_id => { if let Ok(coroutine) = op.recv(&self.immediate_queue) { PollResult::Work(coroutine) } else { PollResult::ShutDown } } Ok(op) if Some(op.index()) == wake_id => { PollResult::Wake(op.recv(&self.wake_notifications.1).unwrap()) } Ok(_) => unreachable!(), Err(_) => PollResult::Timeout, } } fn run_now_or_reschedule(&mut self, mut coroutine: Coroutine) { // If it is possible for this task to yield, we need to prepare a new // waker to receive notifications with. if coroutine.might_yield() { let sender = self.wake_notifications.0.clone(); let coroutine_addr = coroutine.addr(); coroutine.set_waker(waker_fn::waker_fn(move || { let _ = sender.send(coroutine_addr); })); } self.listener.on_task_started(); if let RunResult::Complete { panicked, } = coroutine.run() { self.listener.on_task_completed(panicked); coroutine.complete(); } else { // This should never happen if the task promised not to yield! debug_assert!(coroutine.might_yield()); // Task yielded, so we'll need to reschedule the task to be polled // again when its waker is called. We do this by storing the future // in a collection local to this worker where we can retrieve it // again. // // The benefit of doing it this way instead of sending the future // back through the queue is that the future gets executed (almost) // immediately once it wakes instead of being put behind a queue of // _new_ tasks. self.pending_tasks.insert(coroutine.addr(), coroutine); } } fn run_pending_by_id(&mut self, id: usize) { if let Some(coroutine) = self.pending_tasks.get_mut(&id) { if let RunResult::Complete { panicked, } = coroutine.run() { self.listener.on_task_completed(panicked); // Task is complete, we can de-allocate it and complete it. self.pending_tasks.remove(&id).unwrap().complete(); } } } } enum PollResult { /// New work has arrived for this worker. Work(Coroutine), /// An existing pending task has woken. Wake(usize), /// No activity occurred within the time limit. Timeout, /// The thread pool has been shut down. ShutDown, } threadfin-0.1.2/tests/000077500000000000000000000000001437005634000146225ustar00rootroot00000000000000threadfin-0.1.2/tests/tests.rs000066400000000000000000000124171437005634000163370ustar00rootroot00000000000000use std::{panic::catch_unwind, thread, time::Duration}; use futures_timer::Delay; use threadfin::ThreadPool; fn single_thread() -> ThreadPool { ThreadPool::builder().size(0..1).build() } #[test] #[should_panic(expected = "thread pool name must not contain null bytes")] fn name_with_null_bytes_panics() { ThreadPool::builder().name("uh\0oh").build(); } #[test] #[allow(clippy::reversed_empty_ranges)] #[should_panic(expected = "thread pool minimum size cannot be larger than maximum size")] fn invalid_size_panics() { ThreadPool::builder().size(2..1); } #[test] #[should_panic(expected = "thread pool maximum size must be non-zero")] fn invalid_size_zero_panics() { ThreadPool::builder().size(0); } #[test] fn execute() { let pool = single_thread(); let result = pool.execute(|| 2 + 2).join(); assert_eq!(result, 4); } #[test] fn execute_future() { let pool = single_thread(); let result = pool.execute_future(async { 2 + 2 }).join(); assert_eq!(result, 4); } #[test] fn task_join_timeout() { let pool = single_thread(); let result = pool .execute(|| thread::sleep(Duration::from_secs(5))) .join_timeout(Duration::from_millis(10)); assert!(result.is_err()); } #[test] fn futures_that_yield_are_run_concurrently() { let pool = single_thread(); assert_eq!(pool.running_tasks(), 0); let first = pool .try_execute_future(Delay::new(Duration::from_millis(400))) .unwrap(); // Even though there's only one worker thread, it should become idle quickly // and start polling for more work, because a delay future yields // immediately and doesn't wake for a while. thread::sleep(Duration::from_millis(100)); assert_eq!(pool.running_tasks(), 1); let second = pool .try_execute_future(Delay::new(Duration::from_millis(200))) .unwrap(); thread::sleep(Duration::from_millis(100)); // Now both tasks are running, but there's still only 1 worker thread! assert_eq!(pool.running_tasks(), 2); assert_eq!(pool.threads(), 1); first.join(); second.join(); // Both tasks completed. assert_eq!(pool.completed_tasks(), 2); } #[test] fn try_execute_under_core_count() { let pool = ThreadPool::builder().size(1).build(); // Give some time for thread to start... thread::sleep(Duration::from_millis(100)); assert_eq!(pool.threads(), 1); assert!(pool.try_execute(|| 2 + 2).is_ok()); } #[test] fn try_execute_over_core_count() { let pool = ThreadPool::builder().size(0..1).build(); assert!(pool.try_execute(|| 2 + 2).is_ok()); } #[test] fn try_execute_over_limit() { let pool = ThreadPool::builder().size(0..1).queue_limit(0).build(); assert!(pool.try_execute(|| 2 + 2).is_ok()); assert!(pool.try_execute(|| 2 + 2).is_err()); fn task() -> usize { 2 + 2 } // The returned function in the error is identical to the function given. let error = pool.try_execute(task).unwrap_err(); assert_eq!(error.into_inner() as usize, task as usize); } #[test] fn name() { let pool = ThreadPool::builder().name("foo").build(); let name = pool .execute(|| thread::current().name().unwrap().to_owned()) .join(); assert_eq!(name, "foo"); } #[test] #[should_panic(expected = "oh no!")] fn panic_propagates_to_task() { let pool = single_thread(); pool.execute(|| panic!("oh no!")).join(); } #[test] fn panic_count() { let pool = single_thread(); assert_eq!(pool.panicked_tasks(), 0); let task = pool.execute(|| panic!("oh no!")); let _ = catch_unwind(move || { task.join(); }); assert_eq!(pool.panicked_tasks(), 1); } #[test] fn thread_count() { let pool = ThreadPool::builder().size(0..1).build(); assert_eq!(pool.threads(), 0); pool.execute(|| 2 + 2).join(); assert_eq!(pool.threads(), 1); let pool_with_starting_threads = ThreadPool::builder().size(1).build(); // Give some time for thread to start... thread::sleep(Duration::from_millis(50)); assert_eq!(pool_with_starting_threads.threads(), 1); } #[test] fn idle_shutdown() { let pool = ThreadPool::builder() .size(0..1) .keep_alive(Duration::from_millis(100)) .build(); assert_eq!(pool.threads(), 0, "pool starts out empty"); pool.execute(|| 2 + 2).join(); assert_eq!(pool.threads(), 1, "one thread was added"); thread::sleep(Duration::from_millis(200)); assert_eq!( pool.threads(), 0, "thread became idle and terminated after timeout" ); } #[test] fn join() { // Just a dumb test to make sure join doesn't do anything strange. ThreadPool::default().join(); } #[test] fn join_timeout_expiring() { let pool = ThreadPool::builder().size(1).build(); assert_eq!(pool.threads(), 1); // Schedule a slow task on the only thread. We have to keep the task // around, because dropping it could cancel the task. let _task = pool.execute(|| thread::sleep(Duration::from_millis(500))); // Joining should time out since there's one task still running longer // than our join timeout. assert!(!pool.join_timeout(Duration::from_millis(10))); } #[test] fn configure_common_after_init_returns_error() { threadfin::common(); // init assert!(threadfin::configure_common(|b| b).is_err()); }