[−][src]Struct rusty_pool::ThreadPool
Simple self growing / shrinking ThreadPool
implementation based on crossbeam's
multi-producer multi-consumer channels.
This ThreadPool
has two different pool sizes; a core pool size filled with
threads that live for as long as the channel and a max pool size which describes
the maximum amount of worker threads that may live at the sime time.
Those additional non-core threads have a specific keep_alive time described when
creating the ThreadPool
that defines how long such threads may be idle for
without receiving any work before giving up and terminating their work loop.
This ThreadPool
does not spawn any threads until a task is submitted to it.
Then it will create a new thread for each task until the core pool size is full.
After that a new thread will only be created upon an execute()
call if the
current pool is lower than the max pool size and there are no idle threads.
When creating a new worker this ThreadPool
always re-checks whether the new worker
is still required before spawing a thread and passing it the submitted task in case
an idle thread has opened up in the meantime or another thread has already created
the worker. If the re-check failed for a core worker the pool will try creating a
new non-core worker before deciding no new worker is needed.
Locks are only used for the join functions to lock the Condvar
, apart from that
this ThreadPool
implementation fully relies on crossbeam and atomic operations.
This ThreadPool
decides whether it is currently idle (and should fast-return
join attemps) by comparing the total worker count to the idle worker count, which
are two u32
values stored in one AtomicU64
making sure that if both are updated
they may be updated in a single atomic operation.
The thread pool and its crossbeam channel can be destroyed by using the shutdown function, however that does not stop tasks that are already running but will terminate the thread the next time it will try to fetch work from the channel.
Methods
impl ThreadPool
[src]
pub fn new(core_size: u32, max_size: u32, keep_alive: Duration) -> Self
[src]
Construct a new ThreadPool with the specified core pool size, max pool size and keep_alive time for non-core threads. This function does not spawn any threads.
core_size
specifies the amount of threads to keep alive for as long as
the ThreadPool
exists and its channel remains connected.
max_size
specifies the maximum number of worker threads that may exist
at the same time.
keep_alive
specifies the duration for which to keep non-core pool
worker threads alive while they do not receive any work.
Panics
This function will panic if max_size is 0 or lower than core_size.
pub fn get_current_worker_count(&self) -> u32
[src]
Get the number of live workers, includes all workers waiting for work or executing tasks.
This counter is incremented when creating a new worker even before re-checking whether the worker is still needed. Once the worker count is updated the previous value returned by the atomic operation is analysed to check whether it still represents a value that would require a new worker. If that is not the case this counter will be decremented and the worker will never spawn a thread and start its working loop. Else this counter is decremented when a worker reaches the end of its working loop, which for non-core threads might happen if it does not receive any work during its keep alive time, for core threads this only happens once the channel is disconnected.
pub fn get_idle_worker_count(&self) -> u32
[src]
Get the number of workers currently waiting for work. Those threads are currently
polling from the crossbeam receiver. Core threads wait indefinitely and might remain
in this state until the ThreadPool
is dropped. The remaining threads give up after
waiting for the specified keep_alive time.
pub fn execute<T: FnOnce() + Send + 'static>(&self, task: T)
[src]
Send a new task to the worker threads. This function is responsible for sending the message through the channel and creating new workers if needed. If the current worker count is lower than the core pool size this function will always create a new worker. If the current worker count is equal to or greater than the core pool size this function only creates a new worker if the worker count is below the max pool size and there are no idle threads.
After constructing the worker but before spawning its thread this function checks again whether the new worker is still needed by analysing the old value returned by atomically incrementing the worker counter and checking if the worker is still needed or if another thread has already created it, for non-core threads this additionally checks whether there are idle threads now. When the recheck condition still applies the new worker will receive the task directly as first task and start executing. If trying to create a new core worker failed the next step is to try creating a non-core worker instead. When all checks still fail the task will simply be sent to the main channel instead.
Panics
This function might panic if try_execute
returns an error when either the crossbeam channel has been
closed unexpectedly or the execute
function was somehow invoked after the ThreadPool
was shut down.
Neither cases should occur under normal curcumstances using safe code, as shutting down the ThreadPool
consumes ownership and the crossbeam channel is never dropped unless dropping the ThreadPool
.
pub fn try_execute<T: FnOnce() + Send + 'static>(
&self,
task: T
) -> Result<(), ExecuteError<Box<dyn FnOnce() + Send + 'static>>>
[src]
&self,
task: T
) -> Result<(), ExecuteError<Box<dyn FnOnce() + Send + 'static>>>
Send a new task to the worker threads. This function is responsible for sending the message through the channel and creating new workers if needed. If the current worker count is lower than the core pool size this function will always create a new worker. If the current worker count is equal to or greater than the core pool size this function only creates a new worker if the worker count is below the max pool size and there are no idle threads.
After constructing the worker but before spawning its thread this function checks again whether the new worker is still needed by analysing the old value returned by atomically incrementing the worker counter and checking if the worker is still needed or if another thread has already created it, for non-core threads this additionally checks whether there are idle threads now. When the recheck condition still applies the new worker will receive the task directly as first task and start executing. If trying to create a new core worker failed the next step is to try creating a non-core worker instead. When all checks still fail the task will simply be sent to the main channel instead.
Errors
This function might return the ChannelClosedError
variant of the ExecuteError
enum
if the sender was dropped unexpectedly (very unlikely) or the ThreadPoolClosedError
variant
if this function is somehow called after the ThreadPool
has been shut down (extremely unlikely).
pub fn join(&self)
[src]
Blocks the current thread until there aren't any non-idle threads anymore.
This includes work started after calling this function.
This function blocks until the next time this ThreadPool
completes all of its work,
except if all threads are idle at the time of calling this function, in which case
it will fast-return.
This utilizes a Condvar
that is notified by workers when they coplete a job and notice
that the channel is currently empty and it was the last thread to finish the current
generation of work (i.e. when incrementing the idle worker counter brings the value
up to the total worker counter, meaning it's the last thread to become idle).
pub fn join_timeout(&self, time_out: Duration)
[src]
Blocks the current thread until there aren't any non-idle threads anymore or until the
specified time_out Duration passes, whichever happens first.
This includes work started after calling this function.
This function blocks until the next time this ThreadPool
completes all of its work,
(or until the time_out is reached) except if all threads are idle at the time of calling
this function, in which case it will fast-return.
This utilizes a Condvar
that is notified by workers when they coplete a job and notice
that the channel is currently empty and it was the last thread to finish the current
generation of work (i.e. when incrementing the idle worker counter brings the value
up to the total worker counter, meaning it's the last thread to become idle).
pub fn shutdown(self)
[src]
Destroy this ThreadPool
by claiming ownership and dropping the value,
causing the Sender
to drop thus disconnecting the channel.
Threads in this pool that are currently executing a task will finish what
they're doing until they check the channel, discovering that it has been
disconnected from the sender and thus terminate their work loop.
pub fn shutdown_join(self)
[src]
Destroy this ThreadPool
by claiming ownership and dropping the value,
causing the Sender
to drop thus disconnecting the channel.
Threads in this pool that are currently executing a task will finish what
they're doing until they check the channel, discovering that it has been
disconnected from the sender and thus terminate their work loop.
This function additionally joins all workers after dropping the pool to
wait for all work to finish.
Blocks the current thread until there aren't any non-idle threads anymore.
This function blocks until this ThreadPool
completes all of its work,
except if all threads are idle at the time of calling this function, in which case
the join will fast-return.
The join utilizes a Condvar
that is notified by workers when they coplete a job and notice
that the channel is currently empty and it was the last thread to finish the current
generation of work (i.e. when incrementing the idle worker counter brings the value
up to the total worker counter, meaning it's the last thread to become idle).
pub fn shutdown_join_timeout(self, timeout: Duration)
[src]
Destroy this ThreadPool
by claiming ownership and dropping the value,
causing the Sender
to drop thus disconnecting the channel.
Threads in this pool that are currently executing a task will finish what
they're doing until they check the channel, discovering that it has been
disconnected from the sender and thus terminate their work loop.
This function additionally joins all workers after dropping the pool to
wait for all work to finish.
Blocks the current thread until there aren't any non-idle threads anymore or until the
specified time_out Duration passes, whichever happens first.
This function blocks until this ThreadPool
completes all of its work,
(or until the time_out is reached) except if all threads are idle at the time of calling
this function, in which case the join will fast-return.
The join utilizes a Condvar
that is notified by workers when they coplete a job and notice
that the channel is currently empty and it was the last thread to finish the current
generation of work (i.e. when incrementing the idle worker counter brings the value
up to the total worker counter, meaning it's the last thread to become idle).
Auto Trait Implementations
impl !RefUnwindSafe for ThreadPool
impl Send for ThreadPool
impl Sync for ThreadPool
impl Unpin for ThreadPool
impl !UnwindSafe for ThreadPool
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,