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, CpuPlacementGuarantee, 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(),
    CpuPlacementGuarantee::AdvisoryDeclared,
)?;
assert_eq!(domain.ownership(), CpuDomainOwnership::ExternalManaged);

Implementations

impl ExternalCpuDomain

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

Construct one externally managed CPU resource-domain descriptor.

The executor is retained for the complete descriptor lifetime. Exact and advisory placement values remain caller declarations and do not alter the executor’s affinity capability.

Examples

use std::num::NonZeroUsize;
use std::sync::Arc;
use tenferro_cpu::{
    CpuContext, CpuId, CpuPlacementGuarantee, 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(),
    CpuPlacementGuarantee::ExactDeclared,
)?;
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 placement_guarantee(&self) -> Option<CpuPlacementGuarantee>

Return whether cooperative placement is an exact or advisory declaration.

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_guarantee().is_none());

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.