Struct TaskSystem 

pub struct TaskSystem { /* private fields */ }

Complete OS-independent scheduler instance.

No instance is stored globally. A runtime owns one pinned TaskSystem and passes explicit object references to the scheduler or exposes them through its trait-FFI facade.

IRQ and remote producers wake through ThreadWakeHandle::wake. The wake path serializes thread state, selects an online destination, and activates the thread under that destination’s IRQ-safe runqueue lock. Like Linux PREEMPT_RT with TTWU_QUEUE disabled, a remote waker waits for switch tail’s on_cpu release before completing that direct activation.

Implementations

impl TaskSystem

pub const fn cpu_topology_len(&self) -> usize

Returns the fixed CPU topology width accepted by affinity masks.

pub fn snapshot(&self, cpu: Pin<&CpuLocal>) -> Result<CpuSnapshot, TaskError>

Captures stable state for deterministic scheduler comparisons.

pub fn online_cpu_count(&self) -> usize

Returns the number of CPUs currently available for placement.

pub fn active_cpu_set(&self) -> CpuSet

Returns the CPUs that currently accept runnable placement.

This is the scheduler’s Linux-style active mask, not the fixed possible CPU topology. Callers that must start a runnable worker immediately must choose its affinity from this snapshot.

impl TaskSystem

pub fn create_cpu_local( &self, cpu: CpuId, ) -> Result<Pin<Box<CpuLocal>>, TaskError>

Allocates one pinned CPU-local scheduler object without publishing it.

pub fn cpu_remote(&self, cpu: CpuId) -> Option<&CpuRemote>

Returns the stable remote-publication endpoint of a placement-active CPU.

pub fn cpu_busy_runtime_ns(&self, cpu: CpuId) -> Result<u64, TaskError>

Returns cumulative non-idle runtime charged by one online CPU.

pub fn bring_cpu_online(&self, cpu: Pin<&mut CpuLocal>) -> Result<(), TaskError>

Completes CPU registration and publishes it in the online root domain.

pub fn take_cpu_offline(&self, cpu: Pin<&mut CpuLocal>) -> Result<(), TaskError>

Removes a quiescent owner CPU from placement and remote publication.

The caller must first migrate or retire every non-idle thread, cancel local task deadlines, and consume the CPU’s scheduler IPI. The packed remote lifecycle closes publication only when its active publisher count is zero, so a successful transition cannot strand an inbox node between queue insertion and its doorbell.

pub fn install_idle_thread( &self, cpu: Pin<&mut CpuLocal>, thread: ThreadId, ) -> Result<(), TaskError>

Installs an idle thread for a CPU; idle is selected only when queues empty.

impl TaskSystem

pub fn dispatch_deadline_overruns( &self, limit: usize, ) -> Result<usize, TaskError>

Runs a bounded, allocation-free batch of deferred Deadline callbacks.

Timer IRQ only publishes pending state. This task-context operation drops the registry lock before invoking any OS extension callback. Callback collection retains one existing thread-core reference at a time instead of allocating temporary storage in a scheduler-adjacent safe point.

Errors

Returns TaskError::UnsafeContext without consuming an event in hard IRQ context, and TaskError::ThreadBusy when another task-work consumer is already active.

impl TaskSystem

pub fn deadline_runtime( &self, thread: ThreadId, ) -> Result<DeadlineRuntimeSnapshot, TaskError>

Returns Deadline budget and PI rescue state for diagnostics and ABI glue.

pub fn deadline_activity( &self, thread: ThreadId, ) -> Result<DeadlineActivitySnapshot, TaskError>

Returns the thread’s GRUB activity, zero-lag, and runqueue ownership.

impl TaskSystem

pub fn deferred_task_work_pending(&self) -> bool

Reports whether a sticky task-work publication awaits the service thread.

pub fn service_deferred_task_work( &self, limit: usize, ) -> Result<DeferredTaskWorkBatch, TaskError>

Runs one bounded task-context pass as the single task-work consumer.

Unrelated work classes are interleaved through a persistent round-robin cursor. Per-thread claim predicates still enforce Deadline callback, exit callback, and record-reaping order. A concurrent or reentrant consumer receives TaskError::ThreadBusy without consuming work.

impl TaskSystem

pub fn enqueue( &self, cpu: Pin<&mut CpuLocal>, thread: ThreadId, ) -> Result<(), TaskError>

Enqueues a ready thread on an affinity-compatible owner CPU.

pub fn start_thread( &self, cpu: Pin<&mut CpuLocal>, thread: ThreadId, ) -> Result<(), TaskError>

Admits a new thread and commits its placement on an allowed active CPU.

Rejected admission does not change lifecycle or placement. Success guarantees either local runqueue admission or an owned remote activation delivery. There is no public state-only runnable transition to complete in a second call.

Ordinary fair work is placed on the least-loaded allowed CPU, including its current non-idle dispatch and migrations not yet consumed by the destination owner. Other classes preserve owner-local placement unless affinity requires a transfer. Remote placement uses the owner-only owner-control inbox and never mutates another CPU’s runqueue.

Errors

Returns an error when the source CPU is offline, the thread is not a new unqueued thread, no allowed CPU is online, or remote delivery cannot be reserved. Failures after admission are runtime invariants.

pub fn dequeue( &self, cpu: Pin<&mut CpuLocal>, thread: ThreadId, ) -> Result<(), TaskError>

Removes a ready thread from its owner run queue for migration or update.

impl TaskSystem

pub fn drain_owner_control( &self, cpu: Pin<&mut CpuLocal>, ) -> Result<OwnerControlDrain, TaskError>

Applies a bounded batch of owner-CPU effective-policy updates.

impl TaskSystem

pub fn mark_exited(&self, thread: ThreadId) -> Result<(), TaskError>

Marks a non-queued thread exited and queues its task-context exit hook.

pub fn dispatch_exit_callbacks(&self, limit: usize) -> Result<usize, TaskError>

Runs pending exit callbacks from an ordinary task-context safe point.

Context-switch tail only proves that the exited stack is inactive; its inherited IRQ and scheduler guards are still live. Calling an OS exit hook there can acquire a sleepable lock and recursively enter the scheduler. This bounded pass claims each callback under the registry lock, invokes it without scheduler locks, and only then makes the record eligible for reaping.

pub fn reap_thread(&self, thread: ThreadId) -> Result<(), TaskError>

Removes an exited registry record and makes its slot reusable.

pub fn reap_thread_handle( &self, handle: ThreadHandle, ) -> Result<(), OwnedThreadReapError>

Atomically removes an exited thread while consuming its owning handle.

Keeping handle alive until registry removal prevents the detached reaper on another CPU from winning between a handle drop and an ID-based reap. Retryable failures return the same handle to the caller.

pub fn reap_unreferenced_exited(&self, limit: usize) -> Result<usize, TaskError>

Reaps exited records for which no external strong handle remains.

This bounded task-context pass is the detached-thread reaper. Joinable threads remain registered because their ThreadHandle contributes a strong reference. Late IRQ wake handles likewise delay resource release until their final reference reaches the task-context reaper.

pub fn release_unpublished_resources(&self, resources: ThreadResources)

Releases a construction transaction that failed before thread registry publication.

Thread-private destruction is a one-way ownership transfer. Only the independent active-mm token may outlive this call through the runtime’s explicit last-CPU readiness edge.

impl TaskSystem

pub fn prepare_park( &self, cpu: Pin<&mut CpuLocal>, current: &ThreadHandle, ) -> Result<ParkPrepare, TaskError>

Publishes PARKING after consuming a wake-before-park notification.

pub fn cancel_park( &self, cpu: Pin<&mut CpuLocal>, current: &ThreadHandle, token: &mut ParkTicket, ) -> Result<(), TaskError>

Cancels a prepared park because an independent grant won the race.

impl TaskSystem

pub fn commit_park( &self, cpu: Pin<&mut CpuLocal>, current: &ThreadHandle, token: &mut ParkTicket, ) -> Result<ParkCommit, TaskError>

Rechecks a prepared park and either cancels it or commits schedule-out.

impl TaskSystem

pub fn exit_current( &self, cpu: Pin<&mut CpuLocal>, current: ThreadHandle, ) -> Result<ScheduleDecision, TaskError>

Atomically prepares and commits current-thread exit.

Runtime integrations that publish OS completion between those phases use the crate-private prepared form instead.

impl TaskSystem

pub fn pi_mutex_lock_slow( &self, lock: PiMutexRef<'_>, waiter: ThreadId, sequence: u64, ) -> Result<PiMutexLockResult, TaskError>

Registers one contender in the mutex-owned PI waiter tree.

pub fn pi_wait_cancel(&self, token: PiWaitToken) -> Result<(), TaskError>

Cancels a committed waiter which has not been selected for claim.

pub fn pi_wait_try_cancel( &self, token: &PiWaitToken, ) -> Result<PiWaitCancelOutcome, TaskError>

Tries to cancel a committed waiter without consuming a published ownerless handoff.

pub fn pi_mutex_release( &self, lock: PiMutexRef<'_>, old_owner: ThreadId, ) -> Result<(), TaskError>

Publishes an ownerless handoff and wakes the current top waiter.

pub fn pi_mutex_claim( &self, token: &PiWaitToken, ) -> Result<PiMutexClaimOutcome, TaskError>

Claims an ownerless handoff selected for this waiter.

impl TaskSystem

pub fn request_thread_affinity( &self, thread: ThreadId, affinity: CpuSet, ) -> Result<ThreadAffinityChange, TaskError>

Publishes one affinity generation and returns its completion owner.

pub fn set_current_affinity( &self, cpu: Pin<&mut CpuLocal>, affinity: CpuSet, ) -> Result<bool, TaskError>

Updates the owner CPU’s running thread without publishing a self inbox.

The caller owns cpu in an IRQ-off scheduler-safe window. A true result means the current thread must schedule out before the operation can return to its caller; switch tail will publish the detached context to the selected destination CPU.

impl TaskSystem

pub fn schedule_if_requested( &self, cpu: Pin<&mut CpuLocal>, current: &ThreadHandle, ) -> Result<SchedulerOutcome, TaskError>

Services sticky scheduler work and switches only for a real preemption.

current must be the architecture-published task identity. The owner runqueue transaction revalidates it against rq->curr before use.

impl TaskSystem

pub fn request_idle_pull( &self, cpu: Pin<&mut CpuLocal>, ) -> Result<bool, TaskError>

Requests one owner-mediated pull from the busiest remote CPU.

The target never locks or mutates the source runqueue. Its pinned request node is published to the source owner-control inbox and the source owner selects and hands off one affinity-compatible thread at a safe point.

pub fn push_rt_deadline( &self, cpu: Pin<&mut CpuLocal>, ) -> Result<Option<ThreadId>, TaskError>

Pushes one queued thread from an overloaded owner to the least loaded CPU.

Selection and dequeue happen only on cpu; the target receives an intrusive handoff and enqueues it in its own safe-point drain.

impl TaskSystem

pub fn charge_current( &self, cpu: Pin<&mut CpuLocal>, runtime_ns: u64, reclaimed_ns: u64, ) -> Result<ChargeOutcome, TaskError>

Charges the current dispatch and reports class budget expiration.

pub fn charge_current_until( &self, cpu: Pin<&mut CpuLocal>, reclaimed_ns: u64, ) -> Result<ChargeOutcome, TaskError>

Charges exactly the unaccounted runtime since the current dispatch began or was last sampled.

pub fn rt_run_queue_may_run( &self, cpu: Pin<&mut CpuLocal>, ) -> Result<bool, TaskError>

Reports Linux !rt_rq_throttled(rq) for the owner runqueue.

impl TaskSystem

pub fn schedule( &self, cpu: Pin<&mut CpuLocal>, current: Option<&ThreadHandle>, ) -> Result<ScheduleDecision, TaskError>

Selects the next thread according to strict class precedence.

current is the architecture-published task identity used only to acquire task-owned scheduler state before the runqueue transaction. None is valid only for an initial dispatch with no rq->curr.

impl TaskSystem

pub fn yield_current( &self, cpu: Pin<&mut CpuLocal>, current: &ThreadHandle, ) -> Result<YieldOutcome, TaskError>

Moves the current thread to its class tail and selects another thread.

current must be the architecture-published task identity. The owner runqueue transaction revalidates it against rq->curr before use.

impl TaskSystem

pub fn thread_state(&self, thread: ThreadId) -> Result<ThreadState, TaskError>

Returns the current state of a live registry entry.

pub fn thread_runtime( &self, thread: ThreadId, ) -> Result<ThreadRuntimeSnapshot, TaskError>

Returns cumulative charged CPU runtime.

Like Linux task_sched_runtime(), a running thread is sampled only after locking its assigned runqueue and updating that runqueue’s clock. A stopped thread returns its already charged value without inventing a scheduler timestamp.

pub fn replace_current_address_space( &self, cpu: Pin<&mut CpuLocal>, address_space: &mut AddressSpaceToken, ) -> Result<AddressSpaceToken, TaskError>

Replaces the current running thread’s opaque address-space token.

The caller must hold the owner CPU’s IRQ-off scheduler-safe window. This operation updates only scheduler metadata; installing the hardware page table and invalidating translations remain runtime responsibilities.

pub fn detach_current_address_space( &self, cpu: Pin<&mut CpuLocal>, ) -> Result<AddressSpaceToken, TaskError>

Detaches the current running thread from its user address space.

The caller must enter the runtime’s lazy kernel address-space state in the same IRQ-off transaction before releasing the returned token.

pub fn thread_handle(&self, thread: ThreadId) -> Result<ThreadHandle, TaskError>

Acquires a strong handle for a generation-valid registry entry.

pub fn thread_extension<'thread>( &self, handle: &'thread ThreadHandle, ) -> Result<Option<ThreadExtensionBorrow<'thread>>, TaskError>

Borrows the opaque OS extension through a generation-valid strong handle.

The borrow cannot outlive handle, which prevents the registry reaper from releasing the extension data while a caller interprets it.

pub fn thread_extension_lease( &self, handle: ThreadHandle, ) -> Result<Option<ThreadExtensionLease>, TaskError>

Acquires an owned lease for callers that looked up a temporary handle.

pub fn set_thread_policy( &self, thread: ThreadId, policy: SchedulePolicy, ) -> Result<(), TaskError>

Replaces a task’s base policy in one synchronous owner-rq transaction.

pub fn thread_affinity(&self, thread: ThreadId) -> Result<CpuSet, TaskError>

Returns a copy of the thread CPU affinity mask.

impl TaskSystem

pub fn create_thread(&self, spec: ThreadSpec) -> Result<ThreadHandle, TaskError>

Creates a thread in the ThreadState::New state.

Deadline threads are admitted immediately and therefore must cover the complete online root domain.

pub fn install_bootstrap_thread( &self, cpu: Pin<&mut CpuLocal>, spec: ThreadSpec, ) -> Result<ThreadHandle, TaskError>

Installs the CPU’s already-running bootstrap execution context.

This operation is used before a CPU is published online and performs no context switch. The runtime must call it exactly once with an empty CpuLocal current slot.

pub fn register_idle_thread( &self, cpu: Pin<&mut CpuLocal>, spec: ThreadSpec, ) -> Result<ThreadHandle, TaskError>

Creates and registers a dedicated CPU idle thread before online publish.

impl TaskSystem

pub fn new(config: TaskSystemConfig) -> Result<Self, TaskError>

Creates an empty scheduler instance for a fixed topology.

Errors

Returns TaskError::InvalidCpuCount for an empty or unrepresentable topology and TaskError::InvalidConfiguration for inconsistent fixed capacities or bandwidth values.

Trait Implementations

impl Debug for TaskSystem

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

Formats the value using the given formatter.