Struct ExternalCpuDomain 

pub struct ExternalCpuDomain { /* private fields */ }

Caller-supplied descriptor for one externally managed CPU resource domain.

The descriptor retains the supplied executor without replacing its pool or changing its affinity claim. Registration and process-CPU-set validation are performed later by crate::CpuBackend.

Examples

use std::num::NonZeroUsize;
use std::sync::Arc;
use tenferro_cpu::{
    CpuContext, CpuDomainOwnership, CpuId, CpuSet,
    ExternalCpuDomain, ResolvedCpuPlacement,
};
use tenferro_tensor::CpuDomainId;

let domain = ExternalCpuDomain::new(
    CpuDomainId::new(7),
    ResolvedCpuPlacement::AllAllowed {
        cpus: CpuSet::new([CpuId::new(0)])?,
    },
    Arc::new(CpuContext::with_threads(1)?),
    NonZeroUsize::new(1).unwrap(),
)?;
assert_eq!(domain.ownership(), CpuDomainOwnership::ExternalManaged);

Implementations

impl ExternalCpuDomain

pub fn new( id: CpuDomainId, placement: ResolvedCpuPlacement, executor: Arc<dyn CpuDomainExecutor>, thread_budget: NonZeroUsize, ) -> Result<Self, ExternalCpuDomainError>

Construct one externally managed CPU resource-domain descriptor.

The executor is retained for the complete descriptor lifetime. The placement’s CPU set is the domain’s identity for resource exclusion: two domains whose sets overlap never execute at the same time. It does not alter the executor’s affinity capability, and tenferro makes no promise about where threads created by an external provider run.

Examples

use std::num::NonZeroUsize;
use std::sync::Arc;
use tenferro_cpu::{
    CpuContext, CpuId, CpuSet, ExternalCpuDomain,
    ResolvedCpuPlacement,
};
use tenferro_tensor::CpuDomainId;

let domain = ExternalCpuDomain::new(
    CpuDomainId::new(3),
    ResolvedCpuPlacement::AllAllowed {
        cpus: CpuSet::new([CpuId::new(0)])?,
    },
    Arc::new(CpuContext::with_threads(1)?),
    NonZeroUsize::new(1).unwrap(),
)?;
assert_eq!(domain.id(), CpuDomainId::new(3));

Errors

Returns ExternalCpuDomainError::EmptyPlacementCpuSet for an empty resolved CPU set, ExternalCpuDomainError::ZeroExecutorWorkers when the executor reports no workers, or ExternalCpuDomainError::ThreadBudgetExceedsWorkerCount when thread_budget is greater than the executor’s worker count.

pub fn new_caller_managed( id: CpuDomainId, executor: Arc<dyn CpuDomainExecutor>, thread_budget: NonZeroUsize, ) -> Result<Self, ExternalCpuDomainError>

Construct a caller-managed domain without declaring a CPU set.

The caller owns admission between distinct caller-managed domains. tenferro retains executor, rejects concurrent public entry into this domain, and never constructs or shuts down another executor.

Examples

use std::num::NonZeroUsize;
use std::sync::Arc;
use tenferro_cpu::{
    CpuAdmissionMode, ExternalCpuDomain, RayonCpuDomainExecutor,
};
use tenferro_tensor::CpuDomainId;

let pool = Arc::new(rayon::ThreadPoolBuilder::new().num_threads(2).build()?);
let executor = Arc::new(RayonCpuDomainExecutor::new(Arc::clone(&pool)));
let domain = ExternalCpuDomain::new_caller_managed(
    CpuDomainId::new(9),
    executor,
    NonZeroUsize::new(2).unwrap(),
)?;
assert_eq!(domain.admission_mode(), CpuAdmissionMode::CallerManaged);
assert!(domain.placement().is_none());

Errors

Returns ExternalCpuDomainError::ZeroExecutorWorkers when the executor reports no workers, or ExternalCpuDomainError::ThreadBudgetExceedsWorkerCount when thread_budget exceeds the executor worker count.

pub fn id(&self) -> CpuDomainId

Return the caller-stable identity of this CPU domain.

Examples

use tenferro_cpu::ExternalCpuDomain;
use tenferro_tensor::CpuDomainId;

let _id: fn(&ExternalCpuDomain) -> CpuDomainId = ExternalCpuDomain::id;

pub fn placement(&self) -> Option<&ResolvedCpuPlacement>

Return the declared resolved placement, if this domain uses CPU-set admission.

Examples

use std::num::NonZeroUsize;
use std::sync::Arc;
use tenferro_cpu::{CpuContext, ExternalCpuDomain};
use tenferro_tensor::CpuDomainId;

let domain = ExternalCpuDomain::new_caller_managed(
    CpuDomainId::new(1),
    Arc::new(CpuContext::with_threads(1)?),
    NonZeroUsize::MIN,
)?;
assert!(domain.placement().is_none());

pub fn cpus(&self) -> Option<&CpuSet>

Return the logical CPUs declared for CPU-set admission.

Examples

use std::num::NonZeroUsize;
use std::sync::Arc;
use tenferro_cpu::{CpuContext, ExternalCpuDomain};
use tenferro_tensor::CpuDomainId;

let domain = ExternalCpuDomain::new_caller_managed(
    CpuDomainId::new(1),
    Arc::new(CpuContext::with_threads(1)?),
    NonZeroUsize::MIN,
)?;
assert!(domain.cpus().is_none());

pub fn admission_mode(&self) -> CpuAdmissionMode

Return this domain’s admission contract.

Examples

use std::num::NonZeroUsize;
use std::sync::Arc;
use tenferro_cpu::{CpuAdmissionMode, CpuContext, ExternalCpuDomain};
use tenferro_tensor::CpuDomainId;

let domain = ExternalCpuDomain::new_caller_managed(
    CpuDomainId::new(1),
    Arc::new(CpuContext::with_threads(1)?),
    NonZeroUsize::MIN,
)?;
assert_eq!(domain.admission_mode(), CpuAdmissionMode::CallerManaged);

pub fn thread_budget(&self) -> NonZeroUsize

Return the nonzero thread budget requested for tenferro work.

Examples

use std::num::NonZeroUsize;
use tenferro_cpu::ExternalCpuDomain;

let _budget: fn(&ExternalCpuDomain) -> NonZeroUsize =
    ExternalCpuDomain::thread_budget;

pub fn ownership(&self) -> CpuDomainOwnership

Return the external ownership diagnostic.

Examples

use tenferro_cpu::{CpuDomainOwnership, ExternalCpuDomain};

let _ownership: fn(&ExternalCpuDomain) -> CpuDomainOwnership =
    ExternalCpuDomain::ownership;

pub fn executor_capabilities(&self) -> CpuDomainExecutorCapabilities

Return the supplied executor’s immutable capability descriptor.

Examples

use tenferro_cpu::{CpuDomainExecutorCapabilities, ExternalCpuDomain};

let _capabilities: fn(&ExternalCpuDomain) -> CpuDomainExecutorCapabilities =
    ExternalCpuDomain::executor_capabilities;

Trait Implementations

impl Debug for ExternalCpuDomain

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.