Struct FileTreeRuntime

pub struct FileTreeRuntime { /* private fields */ }

UI-owned handle for one provider worker.

The source is constructed and used only on the named worker thread. Request and response channels are each bounded to 256 items. Dropping the handle merely attempts a non-blocking shutdown enqueue; call Self::finish when confirmed termination is required.

Examples

use ailloli_ui_fs_runtime::{FileTreeRuntime, FileTreeWorkerStats};
fn inspect(runtime: &FileTreeRuntime) {
    let _: FileTreeWorkerStats = runtime.stats();
}

Implementations

impl FileTreeRuntime

Worker lifecycle, request, drain, and diagnostic operations.

pub fn spawn( factory: Arc<dyn FileTreeSourceFactory>, ) -> Result<Self, FileTreeRuntimeError>

Starts a named worker and constructs its provider source on that thread.

This call waits synchronously for factory initialization. Both channels have FILE_TREE_QUEUE_CAPACITY items. The first mutation ID is one; native-watch capability is fixed from the created source.

Errors

Returns FileTreeRuntimeError::Spawn if thread creation fails, FileTreeRuntimeError::Source if the factory fails, or FileTreeRuntimeError::ThreadPanicked if initialization disconnects.

Panics

Panics only if FILE_TREE_QUEUE_CAPACITY is changed to zero.

Examples

use std::sync::Arc;
use ailloli_ui_fs::FileTreeSourceFactory;
use ailloli_ui_fs_runtime::{FileTreeRuntime, FileTreeRuntimeError};
let _spawn: fn(Arc<dyn FileTreeSourceFactory>) -> Result<FileTreeRuntime, FileTreeRuntimeError> = FileTreeRuntime::spawn;

pub fn install_wake( &self, wake: Arc<dyn UiWake>, ) -> Result<(), FileTreeRuntimeError>

Installs or replaces the UI-thread wake target for pending responses.

The wake object must be thread-safe because the provider worker invokes it. Already queued responses remain queued if waking fails.

Errors

Returns FileTreeRuntimeError::Wake when late binding cannot notify the installed target about already queued work.

Examples

use std::sync::Arc;
use ailloli_ui_runtime::UiWake;
use ailloli_ui_fs_runtime::{FileTreeRuntime, FileTreeRuntimeError};
fn install(runtime: &FileTreeRuntime, wake: Arc<dyn UiWake>) -> Result<(), FileTreeRuntimeError> {
    runtime.install_wake(wake)
}

pub fn detach_wake(&self)

Removes the current wake target without discarding queued responses.

Examples

use ailloli_ui_fs_runtime::FileTreeRuntime;
fn detach(runtime: &FileTreeRuntime) { runtime.detach_wake(); }

pub fn request_directory( &self, request: DirectoryLoadRequest, ) -> Result<FileTreeEnqueueOutcome, FileTreeRuntimeError>

Non-blockingly enqueues one generation-tagged directory load.

An identical active (node_id, request_id) returns Coalesced; a newer request for the same node supersedes ownership of the older response. Queue failure restores the previous ownership record.

Errors

Returns FileTreeRuntimeError::QueueFull or FileTreeRuntimeError::Closed. Mutex poisoning is recovered.

Examples

use ailloli_ui_fs::DirectoryLoadRequest;
use ailloli_ui_fs_runtime::{FileTreeEnqueueOutcome, FileTreeRuntime, FileTreeRuntimeError};
fn enqueue(runtime: &FileTreeRuntime, request: DirectoryLoadRequest) -> Result<FileTreeEnqueueOutcome, FileTreeRuntimeError> {
    runtime.request_directory(request)
}

pub fn request_watch( &self, limit: usize, ) -> Result<FileTreeEnqueueOutcome, FileTreeRuntimeError>

Non-blockingly requests one provider watch poll.

At most one explicit poll is pending. Repeated calls coalesce, and limit is clamped to 256 (while zero remains zero). Native-watch sources may also poll automatically every 50 milliseconds while idle.

Errors

Returns FileTreeRuntimeError::QueueFull or FileTreeRuntimeError::Closed; failure reopens the coalescing slot.

Examples

use ailloli_ui_fs_runtime::{FileTreeEnqueueOutcome, FileTreeRuntime, FileTreeRuntimeError};
fn poll(runtime: &FileTreeRuntime) -> Result<FileTreeEnqueueOutcome, FileTreeRuntimeError> {
    runtime.request_watch(32)
}

pub fn request_mutation( &self, store: &mut FileTreeStore, mutation: FileTreeMutation, ) -> Result<FileTreeMutationEnqueue, FileTreeRuntimeError>

Marks a store node pending and non-blockingly queues a provider mutation.

Mutations serialize by FileTreeMutation::target_node_id. An identical active mutation coalesces but still returns the current pending-state delta. A different active mutation returns MutationBusy. Send/store/ID failures remove ownership and best-effort undo pending/reserved state.

Errors

Returns queue/closure, busy-target, request-ID exhaustion, or store errors. Provider failures arrive later in FileTreeApplyReport.

Examples

use ailloli_ui_fs::FileTreeStore;
use ailloli_ui_fs_runtime::{FileTreeMutation, FileTreeMutationEnqueue, FileTreeRuntime, FileTreeRuntimeError};
fn enqueue(runtime: &FileTreeRuntime, store: &mut FileTreeStore, mutation: FileTreeMutation) -> Result<FileTreeMutationEnqueue, FileTreeRuntimeError> {
    runtime.request_mutation(store, mutation)
}

pub fn watch_directory(&self, uri: FileUri) -> Result<(), FileTreeRuntimeError>

Non-blockingly requests provider watch enablement for uri.

Configuration requests are not coalesced; acknowledgement is returned in FileTreeApplyReport::watch_configuration.

Errors

Returns FileTreeRuntimeError::QueueFull or Closed.

Examples

use ailloli_ui_fs::FileUri;
use ailloli_ui_fs_runtime::{FileTreeRuntime, FileTreeRuntimeError};
fn watch(runtime: &FileTreeRuntime, uri: FileUri) -> Result<(), FileTreeRuntimeError> {
    runtime.watch_directory(uri)
}

pub fn unwatch_directory( &self, uri: FileUri, ) -> Result<(), FileTreeRuntimeError>

Non-blockingly requests provider watch removal for uri.

Removing an unknown URI is delegated to the provider. Successful worker bookkeeping decrements watched_directories only when it was known.

Errors

Returns FileTreeRuntimeError::QueueFull or Closed.

Examples

use ailloli_ui_fs::FileUri;
use ailloli_ui_fs_runtime::{FileTreeRuntime, FileTreeRuntimeError};
fn unwatch(runtime: &FileTreeRuntime, uri: FileUri) -> Result<(), FileTreeRuntimeError> {
    runtime.unwatch_directory(uri)
}

pub fn drain(&mut self) -> Result<FileTreeRuntimeDrain, FileTreeRuntimeError>

Drains at most 256 ordered responses without applying store effects.

Current directory ownership is cleared only by its matching request ID; any watch response reopens explicit watch polling, and mutation responses release target ownership. remaining requests another UI drain.

Errors

Returns FileTreeRuntimeError::Wake if inbox drain rearming fails. The drained response batch is not returned in that case.

Panics

Panics only if FILE_TREE_UI_DRAIN_BUDGET is changed to zero.

Examples

use ailloli_ui_fs_runtime::{FileTreeRuntime, FileTreeRuntimeDrain, FileTreeRuntimeError};
fn drain(runtime: &mut FileTreeRuntime) -> Result<FileTreeRuntimeDrain, FileTreeRuntimeError> {
    runtime.drain()
}

pub fn drain_into_store( &mut self, store: &mut FileTreeStore, ) -> Result<FileTreeApplyReport, FileTreeRuntimeError>

Drains responses and applies directory/mutation results to store.

Stale directory results are counted and skipped. Watch and mutation provider errors are collected. Successful mutations clear pending state before applying attested inserts, moves, or removals in response order.

Errors

Returns wake or store errors. Earlier effects from the same batch are not rolled back if a later store operation fails.

Examples

use ailloli_ui_fs::FileTreeStore;
use ailloli_ui_fs_runtime::{FileTreeApplyReport, FileTreeRuntime, FileTreeRuntimeError};
fn apply(runtime: &mut FileTreeRuntime, store: &mut FileTreeStore) -> Result<FileTreeApplyReport, FileTreeRuntimeError> {
    runtime.drain_into_store(store)
}

pub fn stats(&self) -> FileTreeWorkerStats

Returns a non-transactional point-in-time worker metrics snapshot.

Examples

use ailloli_ui_fs_runtime::{FileTreeRuntime, FileTreeWorkerStats};
fn inspect(runtime: &FileTreeRuntime) {
    let stats: FileTreeWorkerStats = runtime.stats();
    assert!(stats.request_queue_max_depth >= stats.request_queue_depth);
}

pub const fn supports_native_watch(&self) -> bool

Returns the source capability captured during worker initialization.

Examples

use ailloli_ui_fs_runtime::FileTreeRuntime;
fn inspect(runtime: &FileTreeRuntime) {
    let supports_watch: bool = runtime.supports_native_watch();
    let _ = supports_watch;
}

pub fn reconcile_scheduler(&self) -> FileTreeReconcileScheduler

Creates a fresh empty UI scheduler matching the provider watch mode.

No expansion state is shared with prior scheduler values.

Examples

use ailloli_ui_fs_runtime::{FileTreeReconcileScheduler, FileTreeRuntime};
fn scheduler(runtime: &FileTreeRuntime) -> FileTreeReconcileScheduler {
    runtime.reconcile_scheduler()
}

pub fn inbox_stats(&self) -> UiInboxStats

Snapshots response-inbox depth, capacity, wake, and delivery counters.

Examples

use ailloli_ui_fs_runtime::FileTreeRuntime;
use ailloli_ui_runtime::UiInboxStats;
fn inspect(runtime: &FileTreeRuntime) {
    let _: UiInboxStats = runtime.inbox_stats();
}

pub fn finish(self) -> Result<(), FileTreeRuntimeError>

Requests shutdown, drains responses, and joins within two seconds.

A full request queue is retried every five milliseconds while response draining prevents a blocked worker send. A disconnected request channel is treated as shutdown sent. Unapplied drained responses are discarded.

Errors

Returns ThreadPanicked when join observes a panic, or FinishTimeout after two seconds. On timeout the consumed value is dropped and its join handle detaches; shutdown is attempted once more by Drop.

Panics

Panics if FILE_TREE_UI_DRAIN_BUDGET is zero or if the worker join handle is absent after it reports that it is finished.

Examples

use ailloli_ui_fs_runtime::{FileTreeRuntime, FileTreeRuntimeError};
let _finish: fn(FileTreeRuntime) -> Result<(), FileTreeRuntimeError> = FileTreeRuntime::finish;

Trait Implementations

impl Drop for FileTreeRuntime

Performs a best-effort non-blocking shutdown request on handle destruction.

fn drop(&mut self)

Enqueues shutdown if capacity permits; never waits or joins.