Struct CleanupGroup

Source

pub struct CleanupGroup { /* private fields */ }

Expand description

An owned thread-pool cleanup group.

Create members with CleanupGroup::create_work, CleanupGroup::create_timer, CleanupGroup::create_periodic_timer, and CleanupGroup::create_wait, then release them all with CleanupGroup::close_members. Drop releases any members that are still open, so forgetting to call close_members is safe – it only gives up control over when the teardown blocks.

§Examples

use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::time::Duration;
use windows_threadpool_sys::cleanup_group::CleanupGroup;

let count = Arc::new(AtomicUsize::new(0));
let work_counter = Arc::clone(&count);
let timer_counter = Arc::clone(&count);

let mut group = CleanupGroup::new()?;
{
    let work = group.create_work(move || {
        work_counter.fetch_add(1, Ordering::SeqCst);
    }, None)?;
    let timer = group.create_timer(move |_firing| {
        timer_counter.fetch_add(1, Ordering::SeqCst);
    }, None)?;

    work.submit();
    timer.set_after(Duration::from_millis(1));

    // Wait for the work to have run and the timer to have fired. Note that
    // `timer.wait()` would not do: it waits for callbacks the pool has
    // already queued, and a timer that has not expired yet has none.
    while count.load(Ordering::SeqCst) < 2 {
        std::thread::yield_now();
    }
}

// One call tears down every member of the group.
group.close_members(false);
assert_eq!(count.load(Ordering::SeqCst), 2);

Implementations§

Source §

impl CleanupGroup

Source

pub fn new() -> Result<Self>

Create an empty cleanup group.

§Errors

Returns the error from CreateThreadpoolCleanupGroup.

Source

pub fn create_work<F>( &self, callback: F, env: Option<&CallbackEnviron<'_>>, ) -> Result<WorkMember<'_>>
where F: Fn() + Send + Sync + 'static,

Create a work object owned by this group.

Equivalent to ThreadpoolWork::new, except that the returned member is released by CleanupGroup::close_members rather than by its own drop.

§Errors

Returns the error from CreateThreadpoolWork.

Source

pub fn create_timer<F>( &self, callback: F, env: Option<&CallbackEnviron<'_>>, ) -> Result<TimerMember<'_>>
where F: Fn(&TimerFiring<'_>) + Send + Sync + 'static,

Create a one-shot timer owned by this group.

Equivalent to ThreadpoolTimer::new.

§Errors

Returns the error from CreateThreadpoolTimer.

Source

pub fn create_periodic_timer<F>( &self, period: Duration, callback: F, env: Option<&CallbackEnviron<'_>>, ) -> Result<PeriodicTimerMember<'_>>
where F: Fn(&PeriodicTick<'_>) + Send + Sync + 'static,

Create a periodic timer owned by this group.

Equivalent to ThreadpoolPeriodicTimer::new, including that its ticks may overlap one another.

§Errors

Returns io::ErrorKind::InvalidInput if period is outside ThreadpoolPeriodicTimer::MIN_PERIOD..=ThreadpoolPeriodicTimer::MAX_PERIOD or is not a whole number of milliseconds, or the error from CreateThreadpoolTimer.

Source

pub fn create_wait<F>( &self, handle: WaitableHandle, callback: F, env: Option<&CallbackEnviron<'_>>, ) -> Result<WaitMember<'_>>
where F: Fn(&WaitActivation<'_>) + Send + Sync + 'static,

Create a wait object owned by this group, watching handle.

The group takes ownership of the handle as well as the object, because the pool may still be watching it until the members are released.

Like ThreadpoolWait::new, this takes a WaitableHandle rather than a bare handle, so the group path cannot reach the unsupported wait targets that the individually-owned path rejects.

§Errors

Returns the error from CreateThreadpoolWait.

Source

pub fn close_members(&mut self, cancel_pending: bool)

Release every member of this group.

Waits for executing callbacks to finish. When cancel_pending is true, callbacks that have not started are dropped instead of run; when false, they run first.

Taking &mut self is what makes members unusable afterwards: they borrow the group, so the compiler rejects any later use of one. Calling this twice is harmless – the second call finds no members.

The group remains usable afterwards. New members may be created on it, and they are released by the next call or by Drop, exactly as the first batch was.

Source