Struct CallbackEnviron 

pub struct CallbackEnviron<'pool> { /* private fields */ }

Equivalent to InitializeThreadpoolEnvironment / DestroyThreadpoolEnvironment.

Wraps [TP_CALLBACK_ENVIRON_V3] with a guaranteed-valid initial state and a typed mutation surface. Construct with CallbackEnviron::new (or Default), mutate with the set_* methods, then pass to a thread-pool object creation function via CallbackEnviron::as_mut_ptr.

Drop models DestroyThreadpoolEnvironment, which is currently a no-op in the SDK but marks the lifecycle boundary.

Pool lifetime

An environment that names a ThreadpoolPool borrows it, so this sequence – which would otherwise create an object from a dangling pool value – does not compile:

use windows_threadpool_sys::callback_env::CallbackEnviron;
use windows_threadpool_sys::pool::ThreadpoolPool;

let mut env = CallbackEnviron::new();
{
    let pool = ThreadpoolPool::new().expect("create pool");
    env.set_pool(&pool);
} // `pool` is dropped here
let _ptr = env.as_mut_ptr(); // error: `pool` does not live long enough

Implementations

impl<'pool> CallbackEnviron<'pool>

pub fn new() -> Self

Returns a properly initialized callback environment.

Equivalent to InitializeThreadpoolEnvironment: sets Version = ENVIRON_VERSION, CallbackPriority = TP_CALLBACK_PRIORITY_NORMAL, and Size = sizeof(TP_CALLBACK_ENVIRON_V3), with all other fields zeroed or None.

pub fn set_pool(&mut self, pool: &'pool ThreadpoolPool)

Equivalent to SetThreadpoolCallbackPool.

Callbacks created with this environment run on pool instead of the process-default pool.

The environment genuinely borrows the pool for as long as it names it, so the pool cannot be dropped while this environment is still usable. That borrow is what makes the setter sound: until an object is created the pool has no member keeping it alive, so CloseThreadpool on a freshly created pool frees it immediately – and an environment still naming it would then hand that dangling value to CreateThreadpool*. The borrow forbids exactly that.

Objects created from the environment copy its contents rather than retaining the borrow, but they do not need it: creating an object binds it to the pool, and CloseThreadpool then releases the pool only after every bound object is freed (its documented behaviour), so a live object can never observe a freed pool however the two are dropped. Declaring the pool before the objects it serves therefore controls only when teardown blocks, not memory safety – see ThreadpoolPool.

Use CallbackEnviron::clear_pool to go back to the default pool.

pub fn clear_pool(&mut self)

Clear the pool selection, so objects created with this environment use the process-default pool again.

This only clears the selection. Any ThreadpoolPool the environment named is borrowed, not owned, so it is neither dropped nor closed, and the environment keeps its 'pool lifetime – the borrow is released when the environment itself is dropped, not here.

pub unsafe fn set_cleanup_group( &mut self, group: PTP_CLEANUP_GROUP, cancel_callback: PTP_CLEANUP_GROUP_CANCEL_CALLBACK, )

Equivalent to SetThreadpoolCallbackCleanupGroup.

Prefer CleanupGroup, which creates its own members and upholds every requirement below for you. This raw seam exists for handing the environment to a cleanup group this crate does not own.

Safety

This takes a raw PTP_CLEANUP_GROUP, so the caller must guarantee that:

• group is a live cleanup group from CreateThreadpoolCleanupGroup, or 0 to clear the setting;
• it outlives every object created with this environment; and
• once CloseThreadpoolCleanupGroupMembers releases those objects, they are neither used nor closed again. This crate’s individually-owned callback objects close themselves on drop, so putting one of those in a foreign cleanup group would close it twice. Use CleanupGroup to get members that are released by the group instead.

pub fn set_priority(&mut self, priority: CallbackPriority)

Equivalent to SetThreadpoolCallbackPriority.

Takes the crate’s closed CallbackPriority rather than the open Win32 TP_CALLBACK_PRIORITY alias, so only the three priorities the API actually defines can reach native object creation.

pub fn set_runs_long(&mut self)

Equivalent to SetThreadpoolCallbackRunsLong.

Hints to the thread pool that this callback may run for a long time, allowing the pool to spawn additional threads.

pub unsafe fn set_library(&mut self, dll: *mut c_void)

Equivalent to SetThreadpoolCallbackLibrary.

Safety

dll must be a valid HMODULE that remains loaded for the lifetime of all thread-pool objects created with this environment.

pub fn as_mut_ptr(&mut self) -> *mut TP_CALLBACK_ENVIRON_V3

Returns a mutable pointer to the inner [TP_CALLBACK_ENVIRON_V3].

For passing to thread-pool object creation functions.

pub fn as_inner(&self) -> &TP_CALLBACK_ENVIRON_V3

Returns a shared reference to the inner [TP_CALLBACK_ENVIRON_V3].

Trait Implementations

impl Default for CallbackEnviron<'_>

fn default() -> Self

Returns the “default value” for a type.

impl Drop for CallbackEnviron<'_>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.