pub struct FileTreeStore { /* private fields */ }Expand description
UI-independent, session-persistent filesystem tree cache.
The store performs no filesystem I/O. Provider results and watch events are applied explicitly, while stable IDs retain UI state across reconciliation. It is not internally synchronized; coordinators own mutation ordering.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
assert_eq!((store.len(), store.revision(), store.generation()), (1, 0, 1));Implementations§
Source§impl FileTreeStore
impl FileTreeStore
Sourcepub fn new(
root_uri: FileUri,
root_metadata: FileMetadata,
) -> Result<Self, FileTreeStoreError>
pub fn new( root_uri: FileUri, root_metadata: FileMetadata, ) -> Result<Self, FileTreeStoreError>
Creates a one-node store with default cache limits.
The root receives ID 1, revision starts at 0, generation at 1, and
directory state at DirectoryLoadState::Unloaded. Metadata is stored
verbatim; a non-directory root is accepted but cannot be loaded.
§Errors
Construction is currently infallible; the result type reserves future initialization/exhaustion checks.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
assert_eq!(store.root().get(), 1);Sourcepub fn with_limits(
root_uri: FileUri,
root_metadata: FileMetadata,
limits: FileTreeStoreLimits,
) -> Result<Self, FileTreeStoreError>
pub fn with_limits( root_uri: FileUri, root_metadata: FileMetadata, limits: FileTreeStoreLimits, ) -> Result<Self, FileTreeStoreError>
Creates a one-node store with caller-supplied soft eviction limits.
Limits are stored verbatim, including zeros or extremely large durations; they do not reject or trim the root.
§Errors
Construction is currently infallible; the result type reserves future initialization/exhaustion checks.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileTreeStoreLimits, FileUri};
use std::time::Duration;
let limits = FileTreeStoreLimits { max_nodes: 0, max_payload_bytes: 0, collapsed_ttl: Duration::ZERO };
let store = FileTreeStore::with_limits(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory), limits)?;
assert_eq!(store.limits(), limits);Sourcepub const fn root(&self) -> FileTreeNodeId
pub const fn root(&self) -> FileTreeNodeId
Returns the original root ID, even if the root node was later removed.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
assert_eq!(store.root().get(), 1);Sourcepub const fn revision(&self) -> u64
pub const fn revision(&self) -> u64
Returns the current monotone revision.
Only non-empty successful commits increment it; it never wraps.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
assert_eq!(store.revision(), 0);Sourcepub const fn generation(&self) -> u64
pub const fn generation(&self) -> u64
Returns the correlation generation for directory requests.
It starts at 1 and changes only through Self::invalidate_generation.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
assert_eq!(store.generation(), 1);Sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Returns the number of currently retained nodes.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
assert_eq!(store.len(), 1);Sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns whether no nodes remain.
A new store is never empty, but public attested removal can remove the root.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
store.apply_attested_remove(store.root())?;
assert!(store.is_empty());Sourcepub fn node(&self, id: FileTreeNodeId) -> Option<&FileTreeNode>
pub fn node(&self, id: FileTreeNodeId) -> Option<&FileTreeNode>
Borrows a live node by ID, or returns None for missing/reserved/removed IDs.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
assert!(store.node(store.root()).is_some());Sourcepub fn node_id(&self, uri: &FileUri) -> Option<FileTreeNodeId>
pub fn node_id(&self, uri: &FileUri) -> Option<FileTreeNodeId>
Returns the live node ID indexed by an exactly equal URI.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let uri = FileUri::parse("file:///")?;
let store = FileTreeStore::new(uri.clone(), FileMetadata::new(FileKind::Directory))?;
assert_eq!(store.node_id(&uri), Some(store.root()));Sourcepub fn reserve_node_id(&mut self) -> Result<FileTreeNodeId, FileTreeStoreError>
pub fn reserve_node_id(&mut self) -> Result<FileTreeNodeId, FileTreeStoreError>
Reserves an opaque identity for an inline create draft. Cancelling the
draft consumes the identity permanently; successful provider I/O must
commit it with Self::apply_attested_insert_reserved.
Reservation changes no revision and creates no node.
§Errors
Returns FileTreeStoreError::IdentifierExhausted when the monotone ID
counter has no successor.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
let id = store.reserve_node_id()?;
assert_eq!(id.get(), 2);
assert!(store.node(id).is_none());Sourcepub fn discard_reserved_node_id(
&mut self,
id: FileTreeNodeId,
) -> Result<(), FileTreeStoreError>
pub fn discard_reserved_node_id( &mut self, id: FileTreeNodeId, ) -> Result<(), FileTreeStoreError>
Releases a draft reservation without making its identity reusable.
§Errors
Returns FileTreeStoreError::InvalidReservedNodeId if id is not an
active reservation or was already discarded/committed.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
let id = store.reserve_node_id()?;
store.discard_reserved_node_id(id)?;
assert!(store.discard_reserved_node_id(id).is_err());Sourcepub const fn limits(&self) -> FileTreeStoreLimits
pub const fn limits(&self) -> FileTreeStoreLimits
Returns the soft cache limits stored at construction.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileTreeStoreLimits, FileUri};
let store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
assert_eq!(store.limits(), FileTreeStoreLimits::default());Sourcepub fn diagnostics(&self) -> FileTreeStoreDiagnostics
pub fn diagnostics(&self) -> FileTreeStoreDiagnostics
Returns cumulative counters plus freshly computed live size estimates.
Computing the payload estimate is linear in retained node count. It sums
node struct size, rendered URI length, identity bytes, and child-vector
capacity; it excludes maps, file contents, and allocator overhead.
Component accumulation is saturating, but the final cross-node sum and
the provider/value identity-length sum use ordinary usize addition.
§Panics
In debug builds, theoretical usize overflow in either ordinary sum
panics; optimized builds wrap. Reaching that bound normally requires
more allocated memory than the process can address.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
assert_eq!(store.diagnostics().nodes, 1);Sourcepub fn touch(
&mut self,
id: FileTreeNodeId,
now: Instant,
) -> Result<(), FileTreeStoreError>
pub fn touch( &mut self, id: FileTreeNodeId, now: Instant, ) -> Result<(), FileTreeStoreError>
Updates a node’s cache recency to the caller-supplied instant.
This emits no delta, changes no revision, and does not change the instant at which a collapsed node became collapsed.
§Errors
Returns FileTreeStoreError::MissingNode for an absent ID.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
use std::time::Instant;
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
store.touch(store.root(), Instant::now())?;
assert_eq!(store.revision(), 0);Sourcepub fn set_expanded(
&mut self,
id: FileTreeNodeId,
expanded: bool,
) -> Result<FileTreeStoreDelta, FileTreeStoreError>
pub fn set_expanded( &mut self, id: FileTreeNodeId, expanded: bool, ) -> Result<FileTreeStoreDelta, FileTreeStoreError>
Sets expansion and updates collapse/recency cache timestamps.
A repeated value returns an empty delta at the current revision. A change
emits one FileTreeDelta::Updated. Expanding clears collapsed_at;
collapsing records Instant::now.
§Errors
Returns FileTreeStoreError::MissingNode or, after state mutation,
FileTreeStoreError::RevisionExhausted if revision cannot advance.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
assert_eq!(store.set_expanded(store.root(), true)?.revision(), 1);
assert!(store.node(store.root()).unwrap().is_expanded());Sourcepub fn set_selected(
&mut self,
id: FileTreeNodeId,
selected: bool,
) -> Result<FileTreeStoreDelta, FileTreeStoreError>
pub fn set_selected( &mut self, id: FileTreeNodeId, selected: bool, ) -> Result<FileTreeStoreDelta, FileTreeStoreError>
Sets selection, touches cache recency, and emits an update when changed.
§Errors
Returns FileTreeStoreError::MissingNode or, after state mutation,
FileTreeStoreError::RevisionExhausted.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
store.set_selected(store.root(), true)?;
assert!(store.node(store.root()).unwrap().is_selected());Sourcepub fn set_focused(
&mut self,
id: FileTreeNodeId,
focused: bool,
) -> Result<FileTreeStoreDelta, FileTreeStoreError>
pub fn set_focused( &mut self, id: FileTreeNodeId, focused: bool, ) -> Result<FileTreeStoreDelta, FileTreeStoreError>
Sets focus, touches cache recency, and emits an update when changed.
§Errors
Returns FileTreeStoreError::MissingNode or, after state mutation,
FileTreeStoreError::RevisionExhausted.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
store.set_focused(store.root(), true)?;
assert!(store.node(store.root()).unwrap().is_focused());Sourcepub fn set_pending_operation(
&mut self,
id: FileTreeNodeId,
pending: bool,
) -> Result<FileTreeStoreDelta, FileTreeStoreError>
pub fn set_pending_operation( &mut self, id: FileTreeNodeId, pending: bool, ) -> Result<FileTreeStoreDelta, FileTreeStoreError>
Sets provider-operation pending state and emits an update when changed.
Pending nodes are pinned against subtree eviction. A repeated value is a revision-preserving no-op.
§Errors
Returns FileTreeStoreError::MissingNode or, after state mutation,
FileTreeStoreError::RevisionExhausted.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
store.set_pending_operation(store.root(), true)?;
assert!(store.node(store.root()).unwrap().has_pending_operation());Sourcepub fn evict_expired(
&mut self,
now: Instant,
) -> Result<FileTreeStoreDelta, FileTreeStoreError>
pub fn evict_expired( &mut self, now: Instant, ) -> Result<FileTreeStoreDelta, FileTreeStoreError>
Evicts descendants of expired collapsed directories while retaining the collapsed directory node and its minimal metadata. Pinned descendants make the whole candidate ineligible.
Candidates are processed oldest-collapse first. While over a soft node
or payload limit, eligible subtrees may be evicted before their TTL;
otherwise only expired candidates are removed. Removal is iterative and
emits descendant FileTreeDelta::Removed changes followed by a retained
parent’s DirectoryLoadState::Unloaded change. No I/O occurs.
§Errors
Returns FileTreeStoreError::RevisionExhausted after eviction state
has changed if a non-empty delta cannot advance the revision.
§Panics
Panics only if the internal cache/node index becomes inconsistent while an eligible candidate is being evicted.
§Examples
use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileTreeStore, FileTreeStoreLimits, FileUri};
use std::time::{Duration, Instant};
let limits = FileTreeStoreLimits { max_nodes: 1, max_payload_bytes: usize::MAX, collapsed_ttl: Duration::from_secs(300) };
let mut store = FileTreeStore::with_limits(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory), limits)?;
store.apply_attested_insert(store.root(), FileEntry::new(FileUri::parse("file:///a")?, FileMetadata::new(FileKind::File)), None)?;
store.evict_expired(Instant::now())?;
assert_eq!(store.len(), 1);Sourcepub fn next_cache_maintenance_due(&self, now: Instant) -> Option<Instant>
pub fn next_cache_maintenance_due(&self, now: Instant) -> Option<Instant>
Earliest time at which an evictable collapsed subtree needs cache maintenance. Capacity pressure is immediate; ordinary cache entries use their configured TTL. Pinned subtrees are excluded so a host timer cannot spin on work that is forbidden to evict.
Returns None when there is no collapsed, non-empty, unpinned candidate.
Under capacity pressure the returned instant is exactly now; otherwise
it is the earliest collapse instant plus the configured TTL.
§Panics
May panic if adding an extremely large FileTreeStoreLimits::collapsed_ttl
to an Instant exceeds the platform instant range.
§Examples
use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileTreeStore, FileTreeStoreLimits, FileUri};
use std::time::{Duration, Instant};
let limits = FileTreeStoreLimits { max_nodes: 1, max_payload_bytes: usize::MAX, collapsed_ttl: Duration::from_secs(300) };
let mut store = FileTreeStore::with_limits(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory), limits)?;
store.apply_attested_insert(store.root(), FileEntry::new(FileUri::parse("file:///a")?, FileMetadata::new(FileKind::File)), None)?;
let now = Instant::now();
assert_eq!(store.next_cache_maintenance_due(now), Some(now));Sourcepub fn apply_attested_insert(
&mut self,
parent: FileTreeNodeId,
entry: FileEntry,
identity: Option<FileIdentity>,
) -> Result<FileTreeStoreDelta, FileTreeStoreError>
pub fn apply_attested_insert( &mut self, parent: FileTreeNodeId, entry: FileEntry, identity: Option<FileIdentity>, ) -> Result<FileTreeStoreDelta, FileTreeStoreError>
Applies a successful provider-side create without rescanning its parent.
A new node is appended with unloaded directory state and no UI flags.
parent need only exist; directory kind/load state is a caller contract.
If the URI already exists anywhere, only that node’s metadata is updated:
parent and the supplied identity are ignored. A matching watcher echo
is remembered in a bounded 256-entry queue.
§Errors
Returns FileTreeStoreError::IdentifierExhausted,
FileTreeStoreError::MissingNode, or
FileTreeStoreError::RevisionExhausted. An allocated ID is consumed
even if parent validation fails; revision exhaustion can follow mutation.
§Examples
use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
let uri = FileUri::parse("file:///new.txt")?;
store.apply_attested_insert(store.root(), FileEntry::new(uri.clone(), FileMetadata::new(FileKind::File)), None)?;
assert!(store.node_id(&uri).is_some());Sourcepub fn apply_attested_insert_reserved(
&mut self,
parent: FileTreeNodeId,
id: FileTreeNodeId,
entry: FileEntry,
identity: Option<FileIdentity>,
) -> Result<FileTreeStoreDelta, FileTreeStoreError>
pub fn apply_attested_insert_reserved( &mut self, parent: FileTreeNodeId, id: FileTreeNodeId, entry: FileEntry, identity: Option<FileIdentity>, ) -> Result<FileTreeStoreDelta, FileTreeStoreError>
Applies a successful provider-side create using the identity reserved for its inline UI draft.
The reservation is consumed before parent/URI processing and is never
restored on a later error. Existing-URI behavior matches
Self::apply_attested_insert and can consume the reserved ID without
creating a new node.
§Errors
Returns FileTreeStoreError::InvalidReservedNodeId,
FileTreeStoreError::MissingNode, or
FileTreeStoreError::RevisionExhausted.
§Examples
use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
let id = store.reserve_node_id()?;
let uri = FileUri::parse("file:///draft.txt")?;
store.apply_attested_insert_reserved(store.root(), id, FileEntry::new(uri, FileMetadata::new(FileKind::File)), None)?;
assert!(store.node(id).is_some());Sourcepub fn apply_attested_remove(
&mut self,
id: FileTreeNodeId,
) -> Result<FileTreeStoreDelta, FileTreeStoreError>
pub fn apply_attested_remove( &mut self, id: FileTreeNodeId, ) -> Result<FileTreeStoreDelta, FileTreeStoreError>
Applies a successful provider-side removal immediately.
The node is detached and its full subtree is removed iteratively in
descendant-before-parent delta order. Active requests/cache/URI/identity
indexes are cleared. Removing the root is allowed and leaves the store
empty while Self::root still returns its old ID. One watcher echo is
retained for deduplication.
§Errors
Returns FileTreeStoreError::MissingNode or, after removal,
FileTreeStoreError::RevisionExhausted.
§Examples
use ailloli_ui_fs::{FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
store.apply_attested_remove(store.root())?;
assert!(store.is_empty());Sourcepub fn apply_attested_move(
&mut self,
id: FileTreeNodeId,
to: FileUri,
identity: Option<FileIdentity>,
) -> Result<FileTreeStoreDelta, FileTreeStoreError>
pub fn apply_attested_move( &mut self, id: FileTreeNodeId, to: FileUri, identity: Option<FileIdentity>, ) -> Result<FileTreeStoreDelta, FileTreeStoreError>
Applies a successful provider-side rename/move while preserving the logical node ID and all retained UI state.
The destination parent URI must already be retained. A supplied identity
replaces the old one; None preserves it. Descendant URIs are rebased
lexically. Moves within one parent do not reorder the child. Callers must
ensure the destination is non-conflicting, its parent is a directory, and
the move does not create a cycle; these invariants are not validated.
§Errors
Returns FileTreeStoreError::MissingNode,
FileTreeStoreError::MissingDestinationParent, or, after mutation,
FileTreeStoreError::RevisionExhausted.
§Panics
Panics if the internal node index loses either the validated source node or destination parent while the move is applied.
§Examples
use ailloli_ui_fs::{FileEntry, FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
let old = FileUri::parse("file:///old")?;
store.apply_attested_insert(store.root(), FileEntry::new(old.clone(), FileMetadata::new(FileKind::File)), None)?;
let id = store.node_id(&old).unwrap();
let new = FileUri::parse("file:///new")?;
store.apply_attested_move(id, new.clone(), None)?;
assert_eq!(store.node_id(&new), Some(id));Sourcepub fn mark_stale(
&mut self,
id: FileTreeNodeId,
) -> Result<FileTreeStoreDelta, FileTreeStoreError>
pub fn mark_stale( &mut self, id: FileTreeNodeId, ) -> Result<FileTreeStoreDelta, FileTreeStoreError>
Marks a retained directory stale without discarding its children.
Repeating the operation is a revision-preserving no-op.
§Errors
Returns FileTreeStoreError::MissingNode,
FileTreeStoreError::NotDirectory, or
FileTreeStoreError::RevisionExhausted.
§Examples
use ailloli_ui_fs::{DirectoryLoadState, FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
store.mark_stale(store.root())?;
assert!(matches!(store.node(store.root()).unwrap().directory_state(), DirectoryLoadState::Stale));Sourcepub fn apply_watch_event(
&mut self,
event: &WatchEvent,
) -> Result<FileTreeStoreDelta, FileTreeStoreError>
pub fn apply_watch_event( &mut self, event: &WatchEvent, ) -> Result<FileTreeStoreDelta, FileTreeStoreError>
Applies one normalized provider watch event without performing I/O.
Sequence numbers must increase within a generation. Events from older
generations, repeated sequences, and matching echoes of the last 256
attested creates/removals/moves are revision-preserving no-ops. A newer
generation resets sequence comparison; sequence zero is still a
duplicate until a positive sequence arrives. Counters saturate at
u64::MAX.
Created/modified events stale the retained parent, removals delete a
known subtree, and overflow stales the named directory or its parent.
Rename/move retention prefers the old URI and otherwise requires a
unique identity so hard links are not conflated. If its destination
parent is not retained, a known moved node is detached but keeps its
former parent field until reconciliation; callers should normally
watch loaded parents and schedule a refresh after gaps or ambiguity.
§Errors
Returns FileTreeStoreError::NotDirectory if an event resolves a
non-directory as the parent to stale, or
FileTreeStoreError::RevisionExhausted after mutation when a non-empty
delta cannot advance the revision. Missing event parents are ignored.
§Panics
Panics if the internal URI/node indexes become inconsistent after a watch move resolves an existing node or destination parent.
§Examples
use ailloli_ui_fs::{DirectoryLoadState, FileKind, FileMetadata, FileTreeStore, FileUri, WatchEvent, WatchEventKind};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
let event = WatchEvent::new(WatchEventKind::Created, FileUri::parse("file:///new")?, 1, 0);
store.apply_watch_event(&event)?;
assert!(matches!(store.node(store.root()).unwrap().directory_state(), DirectoryLoadState::Stale));Sourcepub fn begin_directory_load(
&mut self,
id: FileTreeNodeId,
) -> Result<(DirectoryLoadRequest, FileTreeStoreDelta), FileTreeStoreError>
pub fn begin_directory_load( &mut self, id: FileTreeNodeId, ) -> Result<(DirectoryLoadRequest, FileTreeStoreDelta), FileTreeStoreError>
Starts one provider-owned directory listing request.
The node must be directory-like and have no active request. Request IDs
are monotone and never reused. The returned owned request captures the
current store generation and URI; the caller performs I/O elsewhere and
later passes both request and result to Self::apply_directory_result.
The node is touched and transitions to DirectoryLoadState::Loading.
§Errors
Returns FileTreeStoreError::MissingNode,
FileTreeStoreError::NotDirectory,
FileTreeStoreError::AlreadyLoading, or
FileTreeStoreError::IdentifierExhausted. A
FileTreeStoreError::RevisionExhausted error occurs after the request
and loading state have been installed.
§Panics
Panics if the validated directory node disappears from the internal node index before its loading state is installed.
§Examples
use ailloli_ui_fs::{DirectoryLoadState, FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
let (request, delta) = store.begin_directory_load(store.root())?;
assert_eq!((request.request_id(), delta.revision()), (1, 1));
assert!(matches!(store.node(store.root()).unwrap().directory_state(), DirectoryLoadState::Loading { generation: 1 }));Sourcepub fn cancel_directory_load(
&mut self,
id: FileTreeNodeId,
) -> Result<FileTreeStoreDelta, FileTreeStoreError>
pub fn cancel_directory_load( &mut self, id: FileTreeNodeId, ) -> Result<FileTreeStoreDelta, FileTreeStoreError>
Cancels the currently active load for one directory.
The worker may still finish the owned request. Its response is then rejected as stale because the request identifier is no longer active. This keeps collapse and root replacement UI-local and never blocks on filesystem I/O.
If no request is active, this is a revision-preserving no-op. If an
active request exists but the node is no longer in Loading, only the
correlation is removed and no delta is emitted.
§Errors
Returns FileTreeStoreError::MissingNode for an absent ID or, after
cancellation/state mutation, FileTreeStoreError::RevisionExhausted.
§Examples
use ailloli_ui_fs::{DirectoryLoadState, FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
store.begin_directory_load(store.root())?;
store.cancel_directory_load(store.root())?;
assert!(matches!(store.node(store.root()).unwrap().directory_state(), DirectoryLoadState::Stale));Sourcepub fn apply_directory_result(
&mut self,
request: &DirectoryLoadRequest,
result: Result<Vec<(FileEntry, Option<FileIdentity>)>, FileError>,
) -> Result<FileTreeStoreDelta, FileTreeStoreError>
pub fn apply_directory_result( &mut self, request: &DirectoryLoadRequest, result: Result<Vec<(FileEntry, Option<FileIdentity>)>, FileError>, ) -> Result<FileTreeStoreDelta, FileTreeStoreError>
Applies a provider listing result only when its request is still active.
A successful list is reconciled in input order. Entries must be unique,
direct children of the requested directory; this structural contract is
not validated. Exact URIs preserve IDs, while an identity preserves an
ID only when unique in both the incoming list and live store. Existing
children absent from the list are removed. A provider error records
DirectoryLoadState::Error and retains existing children.
The matching active request is consumed before processing either result. A stale result increments diagnostics but does not consume a newer active request for the same node.
§Errors
Returns FileTreeStoreError::StaleResponse for a canceled, superseded,
or previous-generation request. Reconciliation may return
FileTreeStoreError::MissingNode,
FileTreeStoreError::IdentifierExhausted, or
FileTreeStoreError::RevisionExhausted. These failures are not
transactional: IDs, indexes, nodes, or state may already have changed.
§Examples
use ailloli_ui_fs::{DirectoryLoadState, FileEntry, FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
let (request, _) = store.begin_directory_load(store.root())?;
let entry = FileEntry::new(FileUri::parse("file:///a")?, FileMetadata::new(FileKind::File));
store.apply_directory_result(&request, Ok(vec![(entry, None)]))?;
assert_eq!(store.node(store.root()).unwrap().children().len(), 1);
assert!(matches!(store.node(store.root()).unwrap().directory_state(), DirectoryLoadState::Loaded { .. }));Sourcepub fn invalidate_generation(
&mut self,
) -> Result<FileTreeStoreDelta, FileTreeStoreError>
pub fn invalidate_generation( &mut self, ) -> Result<FileTreeStoreDelta, FileTreeStoreError>
Invalidates all active loads and advances the store generation.
Every node in DirectoryLoadState::Loading becomes stale and every
active correlation is removed. If none were loading, the generation
still advances while the returned delta keeps the current revision.
Watch generation/sequence tracking is independent and is not reset.
§Errors
Returns FileTreeStoreError::RevisionExhausted if either generation
or a required revision cannot advance. In the latter case generation,
requests, and loading states have already changed.
§Examples
use ailloli_ui_fs::{DirectoryLoadState, FileKind, FileMetadata, FileTreeStore, FileUri};
let mut store = FileTreeStore::new(FileUri::parse("file:///")?, FileMetadata::new(FileKind::Directory))?;
store.begin_directory_load(store.root())?;
store.invalidate_generation()?;
assert_eq!(store.generation(), 2);
assert!(matches!(store.node(store.root()).unwrap().directory_state(), DirectoryLoadState::Stale));